While working on WordPress projects with PHP 8.x, you may encounter the following error:

Fatal error: Uncaught PHP_CodeSniffer\Exceptions\RuntimeException: trim(): Passing null to parameter #1 ($string) of type string is deprecated in /path/...

This error occurs due to a deprecation warning in PHP 8.x, where passing null to the trim() function is no longer permitted. Specifically, this issue arises within a WordPress Coding Standards (WPCS) sniff, part of the PHP_CodeSniffer setup. As of the date of this writing, even with the latest versions of PHP_CodeSniffer and WordPress Coding Standards, this issue persists.

Understanding PHP_CodeSniffer and WPCS

PHP_CodeSniffer is a tool that helps developers maintain coding standards by checking their PHP code for violations of specified rules. WordPress Coding Standards (WPCS) provide a set of guidelines for writing consistent and clean code in WordPress projects. The error mentioned above typically indicates that a code snippet is not adhering to these standards due to changes in PHP's behavior.

Fixing

To fix this, we can manually modify the file causing the issue, locate the line where trim() is called and update the code to ensuring that null values are properly handled when calling trim().

For example, in the file vendor/wp-coding-standards/wpcs/WordPress/Sniffs/NamingConventions/PrefixAllGlobalsSniff.php, locate line 280 and replace the following line:

// this 
$cl_prefixes = trim( PHPCSHelper::get_config_data( 'prefixes' );

// to this 

$cl_prefixes = is_null( PHPCSHelper::get_config_data( 'prefixes' ) ) ? '' : trim( PHPCSHelper::get_config_data( 'prefixes' ) );

However, as in lots of decisions in software development, just because you can do this, doesn't mean you should.

While the previous approach may fix the error, it's important to remember that modifying vendor files is not a sustainable solution. Changes will be lost every time you update your dependencies via Composer.

A better approach, then, is to create a patch file.

Creating a Patch File

Here is a step-by-step guide on how to create and apply a patch for the issue

Create the Patch File

A more robust solution is to create a patch file. This method allows you to apply your changes automatically every time you install or update your dependencies.

A patch file is a text file that contains the differences between two versions of a file—essentially a "before" and "after" snapshot.

In your project directory, create a folder to hold the patch file:

mkdir -p patches

Inside the patches/ folder, create a new patch file called fix-null-trim.patch. You can do this with your text editor:

touch patches/fix-null-trim.patch

Open fix-null-trim.patch in your text editor and add the following content:

  --- a/vendor/wp-coding-standards/wpcs/WordPress/Sniffs/NamingConventions/PrefixAllGlobalsSniff.php
    b/vendor/wp-coding-standards/wpcs/WordPress/Sniffs/NamingConventions/PrefixAllGlobalsSniff.php
@@ -280,7  280,7 @@

        // Original code with `trim()`
        // Update this line:
-       $cl_prefixes = trim( PHPCSHelper::get_config_data( 'prefixes' ) );
        $cl_prefixes = is_null( PHPCSHelper::get_config_data( 'prefixes' ) ) ? '' : trim( PHPCSHelper::get_config_data( 'prefixes' ) );

--- a/vendor/wp-coding-standards/wpcs/WordPress/Sniffs/WP/I18nSniff.php
    b/vendor/wp-coding-standards/wpcs/WordPress/Sniffs/WP/I18nSniff.php
@@ -194,7  194,7 @@

        // Original code with `trim()`
        // Update this line:
-       $cl_text_domain = trim( PHPCSHelper::get_config_data( 'text_domain' ) );
        $cl_text_domain = is_null(PHPCSHelper::get_config_data( 'text_domain' )) ? '' : trim( PHPCSHelper::get_config_data( 'text_domain' ) );

--- a/vendor/wp-coding-standards/wpcs/WordPress/Sniffs/Sniff.php
    b/vendor/wp-coding-standards/wpcs/WordPress/Sniffs/Sniff.php
@@ -1144,7  1144,7 @@

        // Original code with `trim()`
        // Update this line:
-       $cl_supported_version = trim( PHPCSHelper::get_config_data( 'minimum_supported_wp_version' ) );
        $cl_supported_version = is_null(PHPCSHelper::get_config_data( 'minimum_supported_wp_version' )) ? '' : trim( PHPCSHelper::get_config_data( 'minimum_supported_wp_version' ) );

This patch tells Composer to replace the problematic line in PrefixAllGlobalsSniff.php with a safer version that uses the null coalescing operator (??) to avoid passing null to trim().

Modify composer.json to Apply the Patch

Next, you need to instruct Composer to apply this patch automatically whenever you install or update your dependencies.

Open your project's composer.json file. Add the following configuration under the "extra" section. If the "extra" section does not already exist, you will need to create it.

    json

    "extra": {
        "patches": {
            "wp-coding-standards/wpcs": {
                "Fix null trim() issue": "patches/fix-null-trim.patch"
            }
        }
    }

This tells Composer to apply the fix-null-trim.patch file to the wp-coding-standards/wpcs package when it installs or updates dependencies.

Install the Composer Patch Plugin

To apply patches via Composer, you need the composer-patches plugin.Run the following command to install:

composer require cweagans/composer-patches

Apply the Patch

Now, you can apply the patch by running the following command:

composer install

During the installation, Composer will apply the patch from the patches/ folder to the PrefixAllGlobalsSniff.php file.

By creating and applying a patch file, you ensure that your fixes persist across Composer updates, adhering to best practices in software development. Regularly monitor updates to PHP_CodeSniffer and WordPress Coding Standards, as these issues may be resolved in future releases. This proactive approach not only enhances code quality but also improves your development workflow in PHP 8.x environments.

I've shared the patch file in this Gist. Feel free to use it as a reference to implement similar fixes in your projects!