Phpstan Phony Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev eloquent/phpstan-phony
   

   Ensure phpstan/extension-installer is also installed (recommended for auto-configuration).

2. Configuration:

   • If using extension-installer, no manual config is needed.
   • Otherwise, add to phpstan.neon:

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

3. First Use Case: Run PHPStan on a test file using Phony mocks:

   vendor/bin/phpstan analyse tests/Unit/ExampleTest.php
   

   Verify type hints for mocks (e.g., mock(ClassA::class)->methodA) are recognized.

Implementation Patterns

Workflows

1. Static Analysis for Mocks: Use the package to validate mock chains in test files:

   $mock = mock(MyService::class);
   $mock->expectedMethod()->returns('value'); // PHPStan validates chain
   

2. Multi-Type Mocks: Leverage support for arrays of classes:

   $mock = mock([UserRepository::class, Cache::class]);
   $mock->method()->returns(...); // Validated for both types
   

3. Mock Builders: Integrate with mockBuilder for dynamic mocks:

   $builder = mockBuilder(User::class);
   $builder->partialWith(['id' => 1])->get(); // Type-checked
   

4. Static Method Mocking: Validate static method calls on mocks:

   onStatic(mock(Logger::class))->log('test'); // Validated
   

Integration Tips

• CI/CD Pipelines: Add PHPStan with this extension to your test suite:

  # .github/workflows/test.yml
  - name: PHPStan
    run: vendor/bin/phpstan analyse --level=max tests/
  

• IDE Support: Configure your IDE (PHPStorm, VSCode) to use PHPStan for real-time feedback on mocks.
• Custom Rules: Extend phony.neon for project-specific mock behaviors (e.g., custom return types).

Gotchas and Tips

Pitfalls

1. Unsupported PHPStan Versions:

   • The package is archived and last updated for PHPStan 1.x. Ensure compatibility:

     # phpstan.neon
     phpstan:
       version: ^1.0
     

   • Older versions (e.g., 0.12.x) may require downgrading PHPStan or using a fork.

2. Broken Release:

   • Version 0.2.0 is explicitly marked as broken. Avoid using it.

3. PHP Version:

   • Minimum PHP 7.2+ is required (PHP 7.1 dropped in 0.7.0).

4. Partial Mocks:

   • partialWith() may not infer return types for complex objects. Use @var annotations:

     /** @var User $user */
     $user = mockBuilder(User::class)->partialWith(['id' => 1])->get();
     

Debugging

• False Positives: If PHPStan flags mock methods as undefined, verify:

  • The class exists in autoload.
  • The method is declared in the mocked class (or its parent/trait).
  • No typos in method names (e.g., methodA vs method_a).

• Extension Conflicts: Disable other Phony-related extensions temporarily to isolate issues:

  # phpstan.neon
  extensions:
    - PhpStanExtensions\SomeOtherExtension\extension.neon
    # - PhpStanExtensions\PhonyExtension\extension.neon # Disable if conflicting
  

Tips

1. Combine with Other Extensions: Use alongside phpstan/phpstan-doctrine or phpstan/phpstan-symfony for full-stack type safety:

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

2. Custom Mock Types: Extend phony.neon to add support for custom mock behaviors:

   services:
     - Eloquent\PhonyPhpStan\PhonyExtension
   parameters:
     phony:
       customMocks:
         App\Services\CustomMock: App\Tests\Mocks\CustomMockBuilder
   

3. Performance: Exclude slow-to-analyze mock-heavy files from strict checks:

   # phpstan.neon
   excludeFiles:
     - tests/Integration/SlowMockTest.php
   

4. Legacy Code: For older PHP/Phony versions, use a fork or downgrade PHPStan to a supported version:

   composer require phpstan/phpstan:0.12.99