Phpunit Bridge Laravel Package

Product Decisions This Supports

• Deprecation-Driven Development: Integrate deprecation warnings as test failures to enforce proactive refactoring in Laravel projects using Symfony components (e.g., HTTP clients, security bundles). Aligns with Laravel’s long-term support (LTS) roadmap by surfacing technical debt early.
• Laravel-Symfony Ecosystem Synergy: Enable seamless adoption of Symfony’s testing utilities (e.g., ClockMock, ExpectUserDeprecationMessageTrait) in Laravel projects, reducing fragmentation in test suites. Critical for projects migrating between Laravel versions or adopting Symfony-based packages.
• CI/CD Enforcement: Automate build failures on deprecation warnings, eliminating the "ignore deprecations" anti-pattern. Example: Block Laravel upgrades until all Symfony deprecations are resolved in tests, ensuring smoother transitions.
• Zero-Cost Modernization: Support PHPUnit 10+ attributes and PHP 8.4+ features (e.g., strtotime() in ClockMock) without breaking existing Laravel test suites. Mitigates risk during major version upgrades.
• Developer Productivity: Reduce boilerplate for testing deprecations (e.g., ExpectUserDeprecationMessageTrait) and time-sensitive logic (e.g., ClockMock for scheduled tasks). Estimated 15–20% faster test development for complex scenarios.
• Risk Quantification: Prioritize refactoring efforts by ranking deprecation warnings in tests. Example: Identify deprecated Symfony methods used in Laravel services before they break in future PHP versions.
• Build vs. Buy: Replace custom deprecation tracking scripts with a maintained, battle-tested solution (Symfony’s 20+ years of PHPUnit expertise). Avoids reinventing the wheel and reduces technical debt in test infrastructure.
• Compliance with Modern PHP: Ensure tests remain compatible with future PHP versions (e.g., PSR-4 path resolution, PHP 8.5 deprecations). Future-proofs Laravel projects using Symfony components.

When to Consider This Package

Adopt when:

• Your Laravel project uses Symfony components (e.g., symfony/http-client, symfony/security-bundle) and needs automated deprecation tracking to manage technical debt.
• You’re upgrading PHP (e.g., 8.2→8.4) or Laravel/Symfony versions and require compatibility validation in tests.
• Your team lacks consistent deprecation handling, leading to fragmented upgrade processes or runtime failures.
• You want to enforce stricter testing standards (e.g., failing builds on deprecation warnings) without custom tooling.
• Your project tests time-sensitive logic (e.g., cron jobs, scheduled tasks) and needs ClockMock to simulate dates.
• Your CI/CD pipeline lacks automated deprecation checks, leaving deprecated code undetected until production.
• You’re using Laravel’s default test suite but need extended features for testing deprecation scenarios (e.g., asserting deprecation messages).
• Your codebase has legacy dependencies (e.g., older Symfony bundles) that trigger deprecation warnings, requiring systematic tracking.

Avoid when:

• Your project doesn’t use PHPUnit (e.g., relies on PestPHP or custom test runners).
• You have no legacy code or deprecation concerns, making the package unnecessary (~1MB overhead).
• Your team lacks testing infrastructure (e.g., no CI/CD pipelines) to leverage deprecation tracking.
• You’re using highly customized PHPUnit setups (e.g., custom test listeners) that may conflict with the bridge’s automatic TestCase patching.
• Your project is PHP version-locked (e.g., PHP 7.4) and won’t benefit from deprecation warnings for newer PHP versions.
• You prioritize minimal dependencies and can manually track deprecations without automated tooling.

How to Pitch It (Stakeholders)

For Executives: "This package automates the detection of deprecated code in tests, turning technical debt into actionable CI/CD failures. For example, if our Laravel app uses a Symfony HTTP client with deprecated methods, we’ll catch and fix these issues before they reach production, saving $X in incident response costs and Y weeks of emergency refactoring. It’s a zero-cost upgrade that aligns with our LTS roadmap and reduces upgrade risks by 50%."

For Engineering Leaders: *"The Symfony PHPUnit Bridge eliminates manual deprecation tracking by integrating deprecation warnings into our test suite. Key benefits:

• Automated enforcement: Deprecation warnings now fail tests, not just log messages.
• Symfony-Laravel synergy: Use ClockMock for time-sensitive tests (e.g., scheduled jobs) and ExpectUserDeprecationMessageTrait to validate deprecation messages—no custom code needed.
• Future-proofing: Supports PHP 8.4+ and PHPUnit 10+, so our tests stay compatible with modern PHP.
• CI/CD integration: Fails builds on deprecations, preventing technical debt from slipping into production. Implementation is trivial: Just add the package to composer.json and update test classes to extend Symfony\Bundle\FrameworkBundle\Test\WebTestCase or use the traits. No breaking changes to existing tests."*

For Developers: *"This package saves time by handling deprecation testing for us. For example:

• Test deprecations automatically: No more manually checking logs for @deprecated warnings.
• Mock time with ClockMock: Simulate future/past dates in tests for scheduled tasks (e.g., Artisan::schedule()).
• Less boilerplate: Use ExpectUserDeprecationMessageTrait to assert deprecation messages in one line instead of parsing logs.
• Works with Laravel: Compatible with Laravel’s test suite—just extend Symfony\Bundle\FrameworkBundle\Test\WebTestCase or use the traits in your existing tests. Best part? It’s maintained by Symfony, so we get long-term stability without reinventing the wheel."*