Prefix bundled dependencies to prevent conflicts with site code

[swissspidy]

Summary

This change implements namespace prefixing for WP-CLI's bundled third-party dependencies to prevent conflicts when the Phar runs against WordPress sites that ship their own versions of those libraries. Since WP-CLI's autoloader is registered before WordPress boots, unprefixed classes from the Phar take precedence over the site's own dependencies, causing fatal errors when interface signatures differ (e.g., psr/log v1 vs v3).

Key Changes

• New utils/scope-dependencies.php script: Orchestrates the prefixing workflow using php-scoper. The script:

  • Installs an isolated php-scoper toolchain (requires PHP 8.2+)
  • Prefixes the composer/composer dependency tree under the WP_CLI\Vendor namespace
  • Rewrites Composer's autoload maps from PSR-4/PSR-0 to classmap format to advertise prefixed class names
  • Validates that the regenerated autoloader contains no unprefixed dependencies
  • Runs between composer install and utils/make-phar.php

• New utils/scoper/scoper.inc.php configuration: Defines php-scoper behavior:

  • Prefixes vendor directories: composer, justinrainbow, marc-mabe, psr, react, seld, symfony
  • Keeps the Composer\ namespace unprefixed so third-party Composer plugins continue working
  • Includes all PHP files (including test fixtures) to prevent unprefixed names from leaking into the classmap
  • Patches string literals that reference Composer\ classes to avoid broken dynamic class resolution

• New utils/scoper/composer.json: Isolated toolchain configuration requiring php-scoper ^0.18, kept separate because php-scoper needs PHP 8.2+ while WP-CLI targets PHP 7.2.24

• Updated utils/make-phar.php: Adapts to work with both prefixed and unprefixed Symfony Finder class depending on whether scope-dependencies.php has already run

• New features/dependency-isolation.feature: Behat scenarios validating that:

  • Sites providing their own psr/log v3 don't fatal due to interface incompatibility
  • Sites providing their own Symfony Console don't conflict with the bundled version
  • Package management still works against the prefixed dependency tree

• Updated .github/workflows/deployment.yml: Adds prefixing step to the Phar build pipeline

Notable Implementation Details

• The script validates that no unprefixed dependencies leak into the regenerated autoloader by scanning generated PHP files for unescaped namespace references
• Composer's autoload rules are rewritten to classmap format because prefixed files no longer satisfy their original PSR-4 declarations
• The --classmap-authoritative flag ensures the ClassLoader consults only the classmap, preventing any leftover PSR-4 rules from resurrecting unprefixed names
• Test fixtures are intentionally included in prefixing to prevent them from surviving the merge with original namespaces intact

https://claude.ai/code/session_01RHtjyXkZh8X16sBgmidSQi

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[swissspidy]

All the failing checks on 2519e02 share a single root cause — php-scoper cannot parse one file, and because the prefixing now runs as post-install-cmd, its non-zero exit aborts composer install itself:

In ParsingException.php line 23:
  Could not parse the file ".../vendor/composer/ca-bundle/src/CaBundle.php".

In UseStmtCollection.php line 56:
  Using null as an array offset is deprecated, use an empty string instead

Error: php-scoper failed.
Script php utils/prefix-dependencies.php handling the prefix-dependencies event returned with error code 1
Script @prefix-dependencies was called via post-install-cmd

Every job that installs dependencies dies with it, which is why the Behat cells fail after ~30s instead of running for 5–9 minutes, and why Lint PHP files and Setup environment are red too. They are not independent failures.

Candidate fixes, cheapest first:

• Pass --php-version to php-scoper so PHP-Parser targets a level that handles the file.
• Bump humbug/php-scoper in utils/scoper/composer.json — the lock is committed, so it may be pinned to a version predating the fix for this.
• Copy composer/ca-bundle verbatim instead of running it through the scoper. It declares Composer\CaBundle, which is inside the excluded Composer\ namespace and never needed prefixing — the same treatment the Symfony polyfills already get.

Worth deciding separately from the parse bug: whether the hook should hard-fail. As wired, any scoper problem takes composer install down with it, for contributors as well as CI. If it warned and skipped instead, this would have been one red check on a working tree rather than a fully blocked PR — and the guarantee is still preserved, since the build job already refuses to build a Phar without third_party/.

On the positive side, PHPCS, PHPStan and the spell check are all green on this head.

---

Generated by Claude Code

[swissspidy]

The package.feature failure on 042f7d6 is not caused by the prefixing — worth saying so before it gets debugged as one.

Uncaught Error: Class "Composer\Console\GithubActionError" not found
  in phar://.../third_party/composer/composer/src/Composer/Installer.php:460
#0 Installer.php(293): Composer\Installer->doUpdate()
#1 vendor/wp-cli/package-command/src/Package_Command.php(438): Composer\Installer->run()

utils/make-phar.php excludes composer/composer/src/Composer/Console from the Phar, and Composer\Installer instantiates new GithubActionError($this->io) on each of its dependency-resolution failure paths (lines 554, 735 and 829 in 2.10.2). The environment check lives inside GithubActionError::emit(), not at the call site, so the class has to exist regardless of whether the run is on GitHub Actions. When wp package install hits an unsolvable dependency problem the Phar therefore fatals where the scenario expects a clean Error: Package installation failed.

main carries the identical exclusion and the same composer/composer 2.10.2, so the missing class predates this branch — the prefixing only changed the path it is reported under (third_party/… rather than vendor/…). I have not checked whether main's own suite reaches the same code path, so I can't say whether it is failing there too or merely latent.

The fix is to stop excluding that class from the Phar — either the whole Console/ directory or just GithubActionError.php, which is referenced from two places in make-phar.php on this branch (the regex around line 109 and the ->exclude() around line 297). Composer flags the same need itself: SelfUpdateCommand.php does a bare class_exists('Composer\Console\GithubActionError'); to force it to load before an error path can need it.

---

Generated by Claude Code