Peststan Laravel Package

Technical Evaluation

Architecture Fit

• Seamless PHPStan Integration: PestStan is a PHPStan extension, meaning it leverages PHPStan’s existing architecture (e.g., extension.neon, Extension classes) without requiring custom tooling. This aligns perfectly with Laravel’s reliance on PHPStan for static analysis.
• Pest-Specific Enhancements: The package extends PHPStan’s type system to understand Pest’s unique constructs (e.g., expect(), $this binding, dynamic properties), which is critical for Laravel projects using Pest for testing.
• Laravel Compatibility: Since Pest is the de facto testing framework for Laravel (replacing PHPUnit), PestStan’s features directly address Laravel’s testing workflows, including:
  • Type-safe assertions in feature/unit tests.
  • Proper $this typing in TestCase subclasses (e.g., Illuminate\Foundation\Testing\TestCase).
  • Dynamic property inference for test fixtures.

Integration Feasibility

• Low Friction: Installation is trivial (composer require --dev mrpunyapal/peststan) and works with phpstan/extension-installer (already common in Laravel projects).
• Configuration Overrides: Supports custom TestCase classes (e.g., App\Tests\TestCase) via phpstan.neon, accommodating Laravel’s layered testing structure.
• No Runtime Overhead: Pure static analysis—no impact on test execution speed or memory.

Technical Risk

• PHPStan Version Lock: Requires PHPStan ^2.0 (Laravel’s default is often PHPStan 1.x). Upgrade path is straightforward but may require CI/CD adjustments.
• Pest Version Support: Explicitly supports Pest 3.0–5.0 (Laravel 10+ uses Pest 5.x). Backward compatibility with older Pest versions is untested.
• Edge Cases in Type Inference:
  • Dynamic properties set via method chains (e.g., factories) require @var annotations for accurate typing.
  • Complex union types (e.g., properties set in multiple beforeEach hooks) may need manual refinement.
• Rule Overhead: Static analysis rules (e.g., pest.test.emptyClosure) add noise if ignored indiscriminately. Requires tuning via phpstan.neon or baseline files.

Key Questions

1. PHPStan Upgrade Readiness:

   • Is the team prepared to upgrade from PHPStan 1.x to 2.x? If not, can this be deferred?
   • Are there existing PHPStan extensions that might conflict with PestStan?

2. TestCase Hierarchy:

   • Does the project use a custom TestCase class (e.g., extending Illuminate\Foundation\Testing\TestCase)? If so, manual configuration may be needed in phpstan.neon.

3. Rule Adoption:

   • Should all PestStan rules be enabled by default, or selectively ignored (e.g., pest.test.emptyClosure)?
   • How will rule violations be triaged (e.g., CI failures vs. local warnings)?

4. Performance Impact:

   • Will the additional type analysis slow down PHPStan’s analysis time significantly? Benchmark with a representative test suite.

5. Dynamic Property Handling:

   • Are there complex beforeEach setups (e.g., nested factories, conditional assignments) that might break type inference? If so, @var annotations may be needed.

Integration Approach

Stack Fit

• Laravel + Pest Ecosystem: PestStan is tailored for Laravel’s testing stack, addressing gaps in PHPStan’s native support for Pest. Key alignments:

  • Type-Safe Assertions: Laravel tests often mix dynamic data (e.g., Eloquent models) with static expectations. PestStan’s expect() typing reduces runtime errors.
  • TestCase Integration: Laravel’s TestCase (e.g., Illuminate\Foundation\Testing\TestCase) is automatically detected, ensuring $this-> methods (e.g., actingAs(), assertDatabaseHas()) are statically typed.
  • Architecture Testing: Supports Laravel-specific assertions (e.g., toExtend('Illuminate\Database\Eloquent\Model')).

• Tooling Synergy:

  • Works alongside existing tools like phpstan/extension-installer, pestphp/pest-plugin, and Laravel’s phpunit.xml (if dual-testing).
  • Compatible with Laravel’s phpstan.neon configuration (e.g., paths, level).

Migration Path

1. Prerequisite Check:

   • Verify PHPStan ≥2.0 and Pest ≥3.0 are installed.
   • Run composer require --dev mrpunyapal/peststan in the project root.

2. Configuration:

   • Auto-Detection: If using standard tests/Pest.php, no config is needed.
   • Custom TestCase: Add to phpstan.neon:

     parameters:
         peststan:
             testCaseClass: App\Tests\TestCase
     

   • Explicit Pest.php Paths: If Pest.php files are outside PHPStan’s paths, list them:

     parameters:
         peststan:
             pestConfigFiles:
                 - tests/Feature/Pest.php
                 - tests/Unit/Pest.php
     

3. Incremental Adoption:

   • Start with type inference (e.g., expect($user)->toBeInstanceOf(User::class)) in critical test files.
   • Enable static analysis rules gradually (e.g., pest.test.emptyClosure) and adjust baselines as needed.
   • Use @phpstan-ignore sparingly for edge cases (e.g., dynamic factories).

4. CI/CD Integration:

   • Add PestStan to PHPStan’s CI step (e.g., GitHub Actions, Laravel Forge).
   • Example workflow snippet:

     - name: PHPStan
       run: vendor/bin/phpstan analyse --level=max tests --configuration=phpstan.neon
     

Compatibility

• Laravel Versions:
  • Laravel 10+: Full compatibility (Pest 5.x + PHPStan 2.x).
  • Laravel 9: May require Pest 4.x and manual PHPStan 2.x upgrade.
• Dual Testing (PHPUnit + Pest):
  • PestStan only affects Pest tests. PHPUnit tests remain unchanged.
  • Ensure phpstan.neon excludes PHPUnit test files if using both:

    paths:
        - tests/Unit
        - tests/Feature
    ignoreFiles:
        - tests/PHPUnit/*.php
    

• Third-Party Packages:
  • No known conflicts with Laravel packages (e.g., spatie/laravel-test-factory, nunomaduro/collision).

Sequencing

1. Upgrade Dependencies:
   • PHPStan 1.x → 2.x (if needed).
   • Pest 3.x/4.x → 5.x (if needed).
2. Install PestStan:
   • Composer install + extension setup.
3. Test Configuration:
   • Validate TestCase detection and dynamic properties in a subset of tests.
4. Enable Rules:
   • Start with pest.expectation.* rules, then expand to pest.test.*.
5. Baseline Adjustments:
   • Run PHPStan with --generate-baseline and commit the baseline.
6. Full Rollout:
   • Enable in CI and monitor for false positives.

Operational Impact

Maintenance

• Low Ongoing Effort:
  • PestStan follows Pest’s release cycle (MIT license, active maintenance).
  • Updates are backward-compatible (e.g., Pest 5.x support added in 2026-07-03).
• Dependency Management:
  • Track PestStan’s releases for new features (e.g., support for Pest 6.x).
  • Monitor PHPStan’s breaking changes (e.g., new rule identifiers).
• Rule Maintenance:
  • Periodically review enabled rules to avoid stale false positives/negatives.
  • Update phpstan.neon or baselines as needed.

Support

• Debugging:
  • Type Errors: PestStan provides detailed diagnostics (e.g., "Expectation cannot call toBeString()").
  • Rule Violations: Each rule includes a canonical identifier for suppression (e.g., @phpstan-ignore pest.test.emptyClosure).
  • Edge Cases: Dynamic property unions or factory chains may require manual @var hints.
• Community Resources:
  • GitHub issues (52 stars, active maintainer).
  • Pest/PHPStan documentation (e.g., PestStan README).

Scaling

• Performance:
  • Analysis Overhead: PestStan adds minimal runtime to PHPStan (type inference is incremental).
  • Large Test Suites: Tested with Pest’s parallelization (--parallel flag). No known bottlenecks.
• Team Adoption:
  • Onboarding: Developers familiar with PHPStan/Pest will adopt quickly. Provide a cheat sheet for common patterns (e.g., `