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

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f253cc49-5456-40e1-8fad-9ab4b9815dc2

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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.}