Phpstan Phony Laravel Package

Technical Evaluation

Architecture Fit

• Limited Fit: The package provides static analysis support for Phony, a PHP mocking library, but does not directly integrate with Laravel’s core architecture. It is a PHPStan extension, meaning it enhances type-checking rather than altering runtime behavior.
• Use Case Alignment: Best suited for teams using Phony for unit testing and PHPStan for static analysis. If the team relies on mocking in tests (e.g., Laravel’s Mockery or PHPUnit with Phony), this package could improve type safety in test files.
• Laravel-Specific Considerations:
  • Laravel primarily uses Mockery for mocking, not Phony. Adopting Phony would require a testing framework shift, which may not align with existing CI/CD pipelines or developer familiarity.
  • If Phony is already in use (e.g., in a legacy codebase or custom testing layer), this package could reduce false positives in PHPStan analyses.

Integration Feasibility

• Low Effort for Static Analysis: Integration is minimal—just a composer require and PHPStan config update. No Laravel service provider or facade changes are needed.
• Dependency Risks:
  • Requires PHPStan 0.12.x or 1.x (latest versions). If the team uses an older PHPStan version, this package won’t work without upgrades.
  • Phony itself must be installed (php-phony/php-phony), adding another dependency to the project.
• Testing Framework Compatibility:
  • Works with PHPUnit (Phony’s primary framework). If the team uses PestPHP, Laravel’s built-in testing helpers, or other frameworks, compatibility must be verified.

Technical Risk

• Maintenance Risk (High): The package is archived and no longer maintained. Future PHPStan or Phony updates may break compatibility.
• Deprecation Risk: Phony itself is less popular than Mockery in the Laravel ecosystem. Adopting it could lead to long-term maintenance burdens.
• False Positives/Negatives: Since this is a static analysis tool, its effectiveness depends on:
  • The quality of Phony’s type hints (which may lag behind runtime behavior).
  • Whether the team’s testing patterns align with the supported Phony use cases (e.g., mockBuilder, partialMock).
• PHP Version Constraints:
  • Requires PHP 7.2+ (due to PHPStan 0.12.x/1.x support). If the project uses PHP 8.0+, this is non-issue; otherwise, an upgrade may be needed.

Key Questions for TPM

1. Why Phony?
   • Is Phony already used in the codebase, or is this a proposed replacement for Mockery/Pest?
   • What are the advantages over existing mocking solutions (e.g., Mockery, Laravel’s createMock())?
2. Static Analysis Strategy
   • How critical is PHPStan integration for the team? Could this be replaced with Mockery’s PHPStan extension (mockery/mockery-phpstan)?
   • Are there existing false positives in PHPStan that this package would resolve?
3. Long-Term Viability
   • Is the team open to maintaining a fork if the original package stagnates?
   • What’s the exit strategy if Phony or PHPStan evolve incompatibly?
4. Testing Framework Impact
   • Will this require migrating test suites from PHPUnit/Pest to Phony?
   • Are there CI/CD pipeline changes needed (e.g., PHPStan configuration updates)?
5. Performance Overhead
   • Does adding PHPStan + Phony slow down test runs significantly?
   • Is the trade-off for type safety worth the added complexity?

Integration Approach

Stack Fit

• PHPStan Integration:
  • Best for: Teams already using PHPStan for static analysis and Phony for mocking.
  • Alternatives:
    • If using Mockery, consider mockery/mockery-phpstan instead.
    • If using PestPHP, check if it has built-in PHPStan support.
• Laravel-Specific:
  • No direct Laravel integration—this is a testing/dev-time tool, not a runtime dependency.
  • Could be opt-in per project (e.g., only for monorepos with mixed testing frameworks).

Migration Path

1. Assessment Phase:
   • Audit existing tests to determine Phony adoption feasibility.
   • Verify PHPStan and PHP version compatibility.
2. Proof of Concept (PoC):
   • Set up the package in a non-production branch.
   • Test with a subset of mock-heavy test files to validate type accuracy.
3. Gradual Rollout:
   • Step 1: Add eloquent/phpstan-phony and php-phony/php-phony to composer.json (dev dependencies).
   • Step 2: Update phpstan.neon to include the extension:

     includes:
       - vendor/eloquent/phpstan-phony/phony.neon
     

   • Step 3: Run PHPStan on test files and triage false positives/negatives.
4. CI/CD Update:
   • Add PHPStan to the test suite (if not already present).
   • Configure to fail builds on errors (adjust severity as needed).

Compatibility

Sequencing

1. Pre-Requisite: Ensure PHPStan is already in use (or plan to adopt it).
2. Dependency Order:
   • Install php-phony/php-phony → eloquent/phpstan-phony → Update PHPStan config.
3. Testing Order:
   • Start with simple mocks (e.g., mock(ClassA::class)->method()).
   • Gradually test complex cases (e.g., mockBuilder, partialMock).
4. Fallback Plan:
   • If issues arise, revert to Mockery’s PHPStan extension or disable the rule in PHPStan.

Operational Impact

Maintenance

• Low Ongoing Effort:
  • No runtime maintenance—only affects static analysis.
  • Dev-time overhead: Developers must learn Phony’s syntax if migrating from Mockery.
• High Risk of Stagnation:
  • Since the package is archived, future PHPStan/Phony updates may break compatibility.
  • Forking or patching may be required long-term.
• Dependency Bloat:
  • Adds two dev dependencies (php-phony/php-phony + eloquent/phpstan-phony).

Support

• Limited Community Support:
  • No active maintainer → issues may go unresolved.
  • Workarounds may need to be documented internally.
• Debugging Complexity:
  • PHPStan false positives/negatives with Phony may require manual investigation.
  • No Laravel-specific support—general PHP/Phony/PHPStan knowledge needed.

Scaling

• No Runtime Scaling Impact:
  • Purely a static analysis tool—no performance impact on production.
• CI/CD Scaling:
  • May increase test suite runtime if PHPStan runs on every commit.
  • Parallelization: PHPStan can be run in parallel with other tests (if CI supports it).
• Team Scaling:
  • Onboarding cost: New developers must learn Phony + PHPStan.
  • Tooling familiarity: Teams experienced with Mockery may resist the switch.

Failure Modes