Prophecy Shim Laravel Package

Getting Started

1. Install via Composer:

   composer require --dev weirdan/prophecy-shim
   

   No additional configuration required — it autoregisters shims for Prophecy\Prophecy\ObjectProphecy, MethodProphecy, etc., when Prophecy is not already present or conflict-free.

2. First use case: Preserve legacy test behavior during upgrades. If your test suite already uses Prophecy (e.g., $this->prophesize(MyService::class)) and you’re upgrading PHP, PHPUnit, or Symfony, but encounter class/interface conflicts (e.g., duplicate Prophecy autoloading), this package ensures Prophecy aliases resolve to a single, compatible version — even if your phpunit/phpunit or other deps pull in conflicting Prophecy versions.

3. Where to look first:

   • composer.json → require-dev to confirm presence
   • phpunit.xml → no changes needed, but verify bootstrap.php or custom test runners don’t redeclare Prophecy classes
   • composer.lock → inspect for duplicate phpdocumentor/reflection-docblock or sebastian/comparator if errors occur (a common conflict vector)

Implementation Patterns

• Drop-in replacement for Prophecy: Use exactly the same syntax as before — no API changes. Prophecy remains imported via use Prophecy\Prophecy\ObjectProphecy; — the shim transparently satisfies the autoloader.

• Gradual migration strategy:

  • Phase 1: Install prophecy-shim → tests still pass, upgrade proceeds
  • Phase 2: Slowly replace prophesize() with PHPUnit’s native mock builder ($this->createMock()) or PHPUnit’s own prophecy integration (PHPUnit\Framework\MockObject\MockObject)
  • Phase 3: Remove prophecy-shim once fully migrated
    The shim acts as a bridge, not a migration tool — so plan migrations in small test commits.

• Test suite isolation: Ideal for monorepos or multi-package repos where one package must use Prophecy but others don’t. The shim ensures only one canonical Prophecy interface set exists in the autoloader — critical for phpunit —no-coverage or parallel runs.

• CI/CD-friendly: Lightweight (≈5–10 files), zero-runtime impact. Adds no config files or bootstrap hooks — safe for high-throughput pipelines.

Gotchas and Tips

• Only active when Prophecy is missing or conflicting: The shim does not replace a clean, non-conflicting Prophecy install. If you explicitly require "phpunit/phpunit": "^9.5" and "phpspec/prophecy": "^1.12" without conflicts, the shim will do nothing. It only kicks in when Composer detects class conflicts.

• Debugging tip: Run composer why phpunit/phpunit and composer why phpspec/prophecy to trace dependency trees. Conflicts often stem from indirect dependencies (e.g., symfony/browser-kit pulling old Prophecy).

• Don’t use with PHPUnit ≥10: As of PHPUnit 10+, Prophecy is fully decoupled and distributed separately (phpunit/phpunit no longer bundles Prophecy), and official PHPUnit shims (or phpspec/prophecy-phpunit) are preferred. Using prophecy-shim with PHPUnit ≥10 adds unnecessary complexity.

• Extension points are minimal: There are no configuration files or DI entries. Extension happens via Composer’s autoloader and class aliasing — so any manual __construct-based Prophecy initialization (e.g., in custom test runners) should avoid direct new Prophecy\... calls.

• Warning flags: If you see Cannot redeclare class Prophecy\..., but prophecy-shim is installed, check for duplicate ClassLoader registrations or conflicting bootstrap files in phpunit.xml. Remove duplicate require statements.