Fatal error when installing WP-CLI Doctor package

[GaryJones]

Problem/Motivation

Globally installing a WP-CLI package, Doctor, results in a Type Error within dealerdirect/phpcodesniffer-composer-installer.

At the very least, this fatal error could probably be checked for and handled more gracefully.

cc @schlessera @swissspidy in case the issue lies in Doctor / WP-CLI.

Expected behaviour

Running wp package install wp-cli/doctor-command:@stable should install cleanly. Inside my local dev environment, where there's no PHPCS-related packages installed, it works fine.

Actual behaviour

On my local host machine, where there's also a global Composer install of PHPCS packages, I get a fatal error.

Full stack trace:

$ wp package install wp-cli/doctor-command:@stable
Installing package wp-cli/doctor-command (@stable)
Updating /Users/gary/.wp-cli/packages/composer.json to require the package...
PHP Deprecated:  Return type of Symfony\Component\Finder\Finder::getIterator() should either be compatible with IteratorAggregate::getIterator(): Traversable, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in phar:///usr/local/bin/wp/vendor/symfony/finder/Finder.php on line 566

{snip of multiple deprecation warnings like the above - https://github.com/wp-cli/package-command/issues/192}

Using Composer to install the package...
---
Loading composer repositories with package information
Found 332 package versions referenced in your dependency graph. 193 (58%) were optimized away.
Updating dependencies
Generating rules
Resolving dependencies through SAT
Looking at all rules.
Something's changed, looking at all rules again (pass #1)

Dependency resolution completed in 0.000 seconds
Analyzed 139 packages to resolve dependencies
Analyzed 179 rules to resolve dependencies
Nothing to modify in lock file
Installing dependencies from lock file
Nothing to install, update or remove
Generating autoload files
1 package you are using is looking for funding.
Use the `composer fund` command to find out more!
PHP Fatal error:  Uncaught TypeError: Composer\Installer\InstallationManager::getInstallPath(): Argument #1 ($package) must be of type Composer\Package\PackageInterface, null given, called in /Users/gary/.composer/vendor/dealerdirect/phpcodesniffer-composer-installer/src/Plugin.php on line 558 and defined in phar:///usr/local/bin/wp/vendor/composer/composer/src/Composer/Installer/InstallationManager.php:614
Stack trace:
#0 /Users/gary/.composer/vendor/dealerdirect/phpcodesniffer-composer-installer/src/Plugin.php(558): Composer\Installer\InstallationManager->getInstallPath(NULL)
#1 /Users/gary/.composer/vendor/dealerdirect/phpcodesniffer-composer-installer/src/Plugin.php(358): PHPCSStandards\Composer\Plugin\Installers\PHPCodeSniffer\Plugin->getPHPCodeSnifferInstallPath()
#2 /Users/gary/.composer/vendor/dealerdirect/phpcodesniffer-composer-installer/src/Plugin.php(238): PHPCSStandards\Composer\Plugin\Installers\PHPCodeSniffer\Plugin->getPhpcsCommand()
#3 /Users/gary/.composer/vendor/dealerdirect/phpcodesniffer-composer-installer/src/Plugin.php(193): PHPCSStandards\Composer\Plugin\Installers\PHPCodeSniffer\Plugin->loadInstalledPaths()
#4 [internal function]: PHPCSStandards\Composer\Plugin\Installers\PHPCodeSniffer\Plugin->onDependenciesChangedEvent(Object(Composer\Script\Event))
#5 phar:///usr/local/bin/wp/vendor/composer/composer/src/Composer/EventDispatcher/EventDispatcher.php(192): call_user_func(Array, Object(Composer\Script\Event))
#6 phar:///usr/local/bin/wp/vendor/composer/composer/src/Composer/EventDispatcher/EventDispatcher.php(119): Composer\EventDispatcher\EventDispatcher->doDispatch(Object(Composer\Script\Event))
#7 phar:///usr/local/bin/wp/vendor/composer/composer/src/Composer/Installer.php(372): Composer\EventDispatcher\EventDispatcher->dispatchScript('post-update-cmd', false)
#8 phar:///usr/local/bin/wp/vendor/wp-cli/package-command/src/Package_Command.php(398): Composer\Installer->run()
#9 [internal function]: Package_Command->install(Array, Array)
#10 phar:///usr/local/bin/wp/vendor/wp-cli/wp-cli/php/WP_CLI/Dispatcher/CommandFactory.php(100): call_user_func(Array, Array, Array)
#11 [internal function]: WP_CLI\Dispatcher\CommandFactory::WP_CLI\Dispatcher\{closure}(Array, Array)
#12 phar:///usr/local/bin/wp/vendor/wp-cli/wp-cli/php/WP_CLI/Dispatcher/Subcommand.php(497): call_user_func(Object(Closure), Array, Array)
#13 phar:///usr/local/bin/wp/vendor/wp-cli/wp-cli/php/WP_CLI/Runner.php(470): WP_CLI\Dispatcher\Subcommand->invoke(Array, Array, Array)
#14 phar:///usr/local/bin/wp/vendor/wp-cli/wp-cli/php/WP_CLI/Runner.php(493): WP_CLI\Runner->run_command(Array, Array)
#15 phar:///usr/local/bin/wp/vendor/wp-cli/wp-cli/php/WP_CLI/Runner.php(136): WP_CLI\Runner->run_command_and_exit()
#16 phar:///usr/local/bin/wp/vendor/wp-cli/wp-cli/php/WP_CLI/Runner.php(1228): WP_CLI\Runner->do_early_invoke('before_wp_load')
#17 phar:///usr/local/bin/wp/vendor/wp-cli/wp-cli/php/WP_CLI/Bootstrap/LaunchRunner.php(28): WP_CLI\Runner->start()
#18 phar:///usr/local/bin/wp/vendor/wp-cli/wp-cli/php/bootstrap.php(84): WP_CLI\Bootstrap\LaunchRunner->process(Object(WP_CLI\Bootstrap\BootstrapState))
#19 phar:///usr/local/bin/wp/vendor/wp-cli/wp-cli/php/wp-cli.php(35): WP_CLI\bootstrap()
#20 phar:///usr/local/bin/wp/php/boot-phar.php(20): include('phar:///usr/loc...')
#21 /usr/local/bin/wp(4): include('phar:///usr/loc...')
#22 {main}
  thrown in phar:///usr/local/bin/wp/vendor/composer/composer/src/Composer/Installer/InstallationManager.php on line 614

Fatal error: Uncaught TypeError: Composer\Installer\InstallationManager::getInstallPath(): Argument #1 ($package) must be of type Composer\Package\PackageInterface, null given, called in /Users/gary/.composer/vendor/dealerdirect/phpcodesniffer-composer-installer/src/Plugin.php on line 558 and defined in phar:///usr/local/bin/wp/vendor/composer/composer/src/Composer/Installer/InstallationManager.php:614
Stack trace:
#0 /Users/gary/.composer/vendor/dealerdirect/phpcodesniffer-composer-installer/src/Plugin.php(558): Composer\Installer\InstallationManager->getInstallPath(NULL)
#1 /Users/gary/.composer/vendor/dealerdirect/phpcodesniffer-composer-installer/src/Plugin.php(358): PHPCSStandards\Composer\Plugin\Installers\PHPCodeSniffer\Plugin->getPHPCodeSnifferInstallPath()
#2 /Users/gary/.composer/vendor/dealerdirect/phpcodesniffer-composer-installer/src/Plugin.php(238): PHPCSStandards\Composer\Plugin\Installers\PHPCodeSniffer\Plugin->getPhpcsCommand()
#3 /Users/gary/.composer/vendor/dealerdirect/phpcodesniffer-composer-installer/src/Plugin.php(193): PHPCSStandards\Composer\Plugin\Installers\PHPCodeSniffer\Plugin->loadInstalledPaths()
#4 [internal function]: PHPCSStandards\Composer\Plugin\Installers\PHPCodeSniffer\Plugin->onDependenciesChangedEvent(Object(Composer\Script\Event))
#5 phar:///usr/local/bin/wp/vendor/composer/composer/src/Composer/EventDispatcher/EventDispatcher.php(192): call_user_func(Array, Object(Composer\Script\Event))
#6 phar:///usr/local/bin/wp/vendor/composer/composer/src/Composer/EventDispatcher/EventDispatcher.php(119): Composer\EventDispatcher\EventDispatcher->doDispatch(Object(Composer\Script\Event))
#7 phar:///usr/local/bin/wp/vendor/composer/composer/src/Composer/Installer.php(372): Composer\EventDispatcher\EventDispatcher->dispatchScript('post-update-cmd', false)
#8 phar:///usr/local/bin/wp/vendor/wp-cli/package-command/src/Package_Command.php(398): Composer\Installer->run()
#9 [internal function]: Package_Command->install(Array, Array)
#10 phar:///usr/local/bin/wp/vendor/wp-cli/wp-cli/php/WP_CLI/Dispatcher/CommandFactory.php(100): call_user_func(Array, Array, Array)
#11 [internal function]: WP_CLI\Dispatcher\CommandFactory::WP_CLI\Dispatcher\{closure}(Array, Array)
#12 phar:///usr/local/bin/wp/vendor/wp-cli/wp-cli/php/WP_CLI/Dispatcher/Subcommand.php(497): call_user_func(Object(Closure), Array, Array)
#13 phar:///usr/local/bin/wp/vendor/wp-cli/wp-cli/php/WP_CLI/Runner.php(470): WP_CLI\Dispatcher\Subcommand->invoke(Array, Array, Array)
#14 phar:///usr/local/bin/wp/vendor/wp-cli/wp-cli/php/WP_CLI/Runner.php(493): WP_CLI\Runner->run_command(Array, Array)
#15 phar:///usr/local/bin/wp/vendor/wp-cli/wp-cli/php/WP_CLI/Runner.php(136): WP_CLI\Runner->run_command_and_exit()
#16 phar:///usr/local/bin/wp/vendor/wp-cli/wp-cli/php/WP_CLI/Runner.php(1228): WP_CLI\Runner->do_early_invoke('before_wp_load')
#17 phar:///usr/local/bin/wp/vendor/wp-cli/wp-cli/php/WP_CLI/Bootstrap/LaunchRunner.php(28): WP_CLI\Runner->start()
#18 phar:///usr/local/bin/wp/vendor/wp-cli/wp-cli/php/bootstrap.php(84): WP_CLI\Bootstrap\LaunchRunner->process(Object(WP_CLI\Bootstrap\BootstrapState))
#19 phar:///usr/local/bin/wp/vendor/wp-cli/wp-cli/php/wp-cli.php(35): WP_CLI\bootstrap()
#20 phar:///usr/local/bin/wp/php/boot-phar.php(20): include('phar:///usr/loc...')
#21 /usr/local/bin/wp(4): include('phar:///usr/loc...')
#22 {main}
  thrown in phar:///usr/local/bin/wp/vendor/composer/composer/src/Composer/Installer/InstallationManager.php on line 614
Reverted composer.json.

The first fatal error points to this line.

Steps to reproduce

Here's my global composer (`~/.composer/composer.json`):

{
    "name": "gamajo/global",
    "description": "Local globally installed Composer packages.",
    "license": "MIT",
    "require": {
        "automattic/vipwpcs": "^3",
        "clue/graph-composer": "^1.1",
        "ergebnis/composer-normalize": "^2.43",
        "icanhazstring/composer-unused": "^0.8",
        "phpcompatibility/php-compatibility": "dev-develop as 9.99.99",
        "phpcompatibility/phpcompatibility-wp": "^2.1",
        "phpcsstandards/phpcsdevtools": "^1.0",
        "phpunit/phpunit": "^9.6",
        "psy/psysh": "@stable"
    },
    "require-dev": {
        "shipmonk/composer-dependency-analyser": "^1.5",
        "tomasvotruba/lines": "^0.5.0"
    },
    "minimum-stability": "dev",
    "prefer-stable": false,
    "config": {
        "allow-plugins": {
            "dealerdirect/phpcodesniffer-composer-installer": true,
            "ergebnis/composer-normalize": true,
            "icanhazstring/composer-unused": true
        }
    }
}

• Add the above composer.json to ~/.composer/composer.json`
• Run composer g install / composer g update
• Run wp package install wp-cli/doctor-command:@stable

Environment

Question	Answer
OS	Windows/Linux/Mac (preferably with some version info)
PHP version	8.3.22 (same for older versions)
Composer version	2.8.7
PHP_CodeSniffer version	3.13.2
Composer PHPCS plugin version	1.1.1
Install type	Composer global
WP-CLI	2.12.0 (same for 2.11.0 - no other WP-CLI packages installed)

Output of ~/.composer/vendor/bin/phpcs --config-show:

Using config file: /Users/gary/.composer/vendor/squizlabs/php_codesniffer/CodeSniffer.conf

installed_paths: /Users/gary/.composer/vendor/automattic/vipwpcs,/Users/gary/.composer/vendor/phpcompatibility/php-compatibility,/Users/gary/.composer/vendor/phpcompatibility/phpcompatibility-paragonie,/Users/gary/.composer/vendor/phpcompatibility/phpcompatibility-wp,/Users/gary/.composer/vendor/phpcsstandards/phpcsdevtools,/Users/gary/.composer/vendor/phpcsstandards/phpcsextra,/Users/gary/.composer/vendor/phpcsstandards/phpcsutils,/Users/gary/.composer/vendor/sirbrillig/phpcs-variable-analysis,/Users/gary/.composer/vendor/wp-coding-standards/wpcs

Tested against main branch?

• I have verified the issue still exists in the main branch.

[jrfnl]

Thanks for reporting this @GaryJones.

Additional steps needed to reproduce:
0. Download the WP-CLI PHAR file and put it somewhere in your OS path.

I tried to reproduce

• ... with a composer local install and didn't get the issue.
• ... with a composer global install and yes, I can see the fatal.

When running composer g install, this plugin works fine and when checking --config-show for the Composer globally installed PHPCS version, the installed paths are correct. Both before running the WP-CLI command as well as after, no matter the fatal error.

This plugin already has protection in place in case PHPCS would not being installed and should show a clean error message, however, it appears that the code modernization applied after we dropped support for Composer 1.x does not play nice with WP-CLI programmatically calling the Composer EventDispatcher.

When I tested with the 1.0.0 version of the plugin, things worked fine and there was no fatal error.

I guess we'll have to revert this modernization too.

sigh... bit annoying that even though we dropped support for Composer API < 2.2, we still can't use the Composer 2.2 API....

[swissspidy]

I'll probably have to defer to @schlessera for the details, but is there something we need to fix on the WP-CLI side?

[jrfnl]

I'll probably have to defer to @schlessera for the details, but is there something we need to fix on the WP-CLI side?

@swissspidy I honestly don't know, that would need digging into the WP-CLI code and for now, I'm just trying to unblock users of this plugin.

The 1.1.0 release contained two small code modernizations: #234 and both have caused issues. The second one was reverted in release 1.1.1 (see #239) and I'm now reverting the first one for the 1.1.2 release.

It basically comes down to the code we use to check whether PHPCS is installed via the Composer API returning true, but then the code used to retrieve the path to the PHPCS package either returning null or returning a broken/invalid path, which means this plugin breaks as without the path to PHPCS, we can't set the installed_paths.

Investigation in #239 already identified one other Composer plugin which broke things: Nevay/spi#6, but there may be more and WP-CLI may well be one of them.

[schlessera]

At the very least, this fatal error could probably be checked for and handled more gracefully.

We already run Composer->install() within a try/catch, however we only catch Exception, which TypeError is not. Catching Throwable instead in https://github.com/wp-cli/package-command/blob/bb5258891fbb32e34bc9c2283372c401e547f8af/src/Package_Command.php#L399 would already deal with the "gracefully" here.

Now, as to why the type error happens to begin with, I'll have to do more exploration. I can reproduce the issue locally from within my WP-CLI dev environment, so I'll start digging.

A quick note about what WP-CLI has customized re. the Composer integration:

1. We extend Composer\IO\NullIO to use WP-CLI logging.
2. We have a customized version of the JsonManipulator for manipulations we do ourselves, as we needed to add case-insensitivity to it.

Now, I suspect that 2. above could cause issues, especially since it was implemented 8 years ago and never updated against the Composer source it was copied from. Also, not sure how Composer v2 deals with case-insensitivity in our particular case. I'll have to go through the code to figure out what is happening in detail.

(UPDATE)

Oh, and we have another change, which happens to be in the wrong package:

3. We add a custom PackageManagerEventSubscriber so we can log output as Composer goes through the operations.

This event subscriber is in the wp-cli/wp-cli repo, probably as an oversight, and should be in the wp-cli/package-command repo instead.

[schlessera]

From what I can see, there are two separate bugs in the dealerdirect/phpcodesniffer-composer-installer plugin that combine to create the fatal error:

1. The plugin assumes that the squizlabs/php_codesniffer package is installed in the current local repository, as it uses $this->composer->getRepositoryManager()->getLocalRepository() to retrieve the single repository it uses findPackages() on to find the package. This assumption breaks for example in cases where PHPCodeSniffer is installed globally but not in the currently local repository. This happens to be the case when using the WP-CLI package manager, where the local repository is the one specific to WP-CLI stored in ~/.wp-cli/packages. What the plugin should do instead is have a smarter heuristic of going over all $this->composer->getRepositoryManager()->getRepositories() (not 100% sure on this) and figure out which one would be the correct one to use first. It could be, though, that the correct repository is not even available in such a case. Generally, what we have here is that the PHPCS installer plugin is installed globally and running globally, but it acts on a repository where PHPCS is not installed.

2. The plugin uses the value from $localRepository->findPackages(), which is BasePackage[] (meaning here zero or more packages) and uses array_shift() on it. When findPackages() failed to find a package (which is a valid outcome) it returns an empty array, which the array_shift then turns into null. This value is fed directly into $this->composer->getInstallationManager()->getInstallPath(), which only accepts a PackageInterface. This is a bug and needs to be hardened, as there is no guarantee at this point that we do indeed have a package instance. A more robust approach would be to check if a package was found, and if not abort with a warning or error for the user.

[jrfnl]

Thanks for looking into this @schlessera and your analysis !

There's a couple of things here I will look into when I find some time. As reverting the plugin modernizations solves the issue (for now), the rest will have to wait until I have more time for this.

Couple of things though:

If I remember correctly, there is some global vs local behaviour in Composer by default for plugins, where global takes precedence, which complicates things anyhow for any Composer plugin.
Trying hard to remember the specifics now - something like if the plugin is installed both locally and globally, the global copy of the plugin code is used, not the local copy. Will need to double-check.

A more robust approach would be to check if a package was found, and if not abort with a warning or error for the user.

We already do that and that's the part in which the modernization was causing the breakage now. All the rest is only called after we get confirmation that PHPCS is installed (else the plugin throws an error early).