Peststan Laravel Package

Technical Evaluation

Architecture Fit

• Seamless PHPStan Integration: PestStan extends PHPStan’s static analysis capabilities, aligning with Laravel’s existing tooling stack (PHPStan is widely adopted in Laravel ecosystems). The package leverages PHPStan’s extension system, ensuring compatibility with Laravel’s type-hinted and dependency-injected architecture.
• Pest Framework Synergy: Pest is Laravel’s preferred testing framework, and PestStan enhances its type safety without requiring changes to Pest’s core functionality. This aligns with Laravel’s emphasis on developer experience and maintainability.
• Architecture Testing Support: PestStan’s support for architecture testing (e.g., toExtend, toBeInvokable) complements Laravel’s layered architecture (e.g., DTOs, repositories, services), enabling stricter enforcement of design patterns.

Integration Feasibility

• Low Friction: Installation is trivial (composer require --dev), and auto-registration via phpstan/extension-installer reduces manual configuration. Existing Laravel projects using Pest and PHPStan can adopt PestStan with minimal effort.
• Backward Compatibility: PestStan works with Pest v3–5 and PHPStan ^2.0, covering Laravel’s supported PHP versions (8.2+). No breaking changes are introduced to Pest’s runtime behavior.
• Type System Alignment: PestStan’s type narrowing and inference align with Laravel’s use of PHP 8.2+ features (e.g., enums, attributes, union types), reducing friction in type-heavy applications.

Technical Risk

• False Positives/Negatives: Static analysis rules (e.g., pest.expectation.impossible) may flag legitimate edge cases as errors. Mitigation: Use @phpstan-ignore or baseline adjustments.
• Dynamic Property Inference: While PestStan auto-infers types for dynamic properties, complex scenarios (e.g., union types across multiple hooks) may require manual @var annotations. Risk: Minor developer overhead in edge cases.
• Pest Configuration Complexity: Projects with custom Pest.php setups (e.g., multi-test-case inheritance) may need explicit peststan.neon overrides. Risk: Low, but requires documentation review.

Key Questions

1. Adoption Readiness: Does the team prioritize static analysis over runtime assertions? PestStan’s value is highest in projects with strict type safety requirements.
2. CI/CD Integration: Will PestStan’s rules be enforced in CI? If so, baseline configuration (e.g., ignoring pest.test.emptyClosure for TODOs) must be pre-defined.
3. Performance Impact: PHPStan analysis may slow down CI pipelines. Benchmark with phpstan --memory-limit=1G to assess trade-offs.
4. Custom TestCase Classes: Are there non-standard TestCase hierarchies (e.g., trait-based)? PestStan’s auto-detection may need manual overrides.
5. Legacy Code: How prevalent are dynamic properties without type hints? PestStan’s inference may not cover all cases, requiring gradual migration.

Integration Approach

Stack Fit

• Laravel/Pest Ecosystem: PestStan is a drop-in extension for Laravel projects using Pest and PHPStan. No changes to Laravel’s core or third-party packages are required.
• Toolchain Compatibility:
  • PHPStan: PestStan is a first-class extension, leveraging PHPStan’s NEON configuration and rule system.
  • Pest: Full support for Pest’s DSL (e.g., it(), expect(), beforeEach()) without runtime modifications.
  • CI/CD: Integrates with GitHub Actions, GitLab CI, or Laravel Forge via phpstan commands.
• IDE Support: Works with PHPStorm, VSCode (with Intelephense), and other IDEs that support PHPStan’s type information.

Migration Path

1. Prerequisite Check:
   • Ensure PHP ^8.2, Pest ^3.0, and PHPStan ^2.0 are installed.
   • Verify phpstan/extension-installer is optional but recommended.
2. Installation:

   composer require --dev mrpunyapal/peststan
   

3. Configuration:
   • Auto-detection: PestStan scans tests/Pest.php files by default.
   • Manual override (if needed):

     # phpstan.neon
     parameters:
         peststan:
             testCaseClass: App\Tests\TestCase
             pestConfigFiles: [tests/Pest.php, tests/Unit/Pest.php]
     

4. Validation:
   • Run phpstan analyse to identify type errors or rule violations.
   • Address false positives with @phpstan-ignore or baseline adjustments.
5. Gradual Adoption:
   • Start with critical test suites (e.g., feature tests) before applying to all tests.
   • Use --level=max for strict mode, then relax as needed.

Compatibility

• Pest Versions: Supports v3–5. Downgrade Pest if using an unsupported version.
• PHPStan Levels: Works with --level=5 (strict) to --level=8 (loose). Rules like pest.expectation.impossible are most valuable at higher levels.
• Custom Assertions: PestStan does not override custom expect() extensions. Use @var annotations for unsupported assertions.
• Legacy Code: Projects with dynamic properties or mixed types may need incremental refactoring to leverage PestStan’s inference.

Sequencing

1. Phase 1: Setup
   • Install PestStan and configure phpstan.neon.
   • Add phpstan to CI pipelines (e.g., phpstan analyse --level=7).
2. Phase 2: Validation
   • Run analysis on a subset of tests to identify issues.
   • Address critical errors (e.g., type mismatches) first.
3. Phase 3: Optimization
   • Enable stricter rules (e.g., pest.test.emptyClosure) for new tests.
   • Use @var annotations for complex dynamic properties.
4. Phase 4: Full Adoption
   • Apply PestStan to all test suites.
   • Monitor CI performance and adjust memory limits if needed.

Operational Impact

Maintenance

• Dependency Management:
  • PestStan is a dev dependency with no runtime impact. Updates can be version-locked (e.g., ^1.0).
  • Monitor for breaking changes in Pest or PHPStan major versions.
• Rule Updates:
  • PestStan’s static analysis rules may evolve. Review changelogs for new rules (e.g., pest.group.invalidName).
  • Baseline configuration should be version-controlled to avoid flaky CI.
• Documentation:
  • Maintain internal docs for custom peststan.neon settings or ignored rules.
  • Train developers on @phpstan-ignore usage and type inference patterns.

Support

• Developer Onboarding:
  • PestStan reduces boilerplate (e.g., no @var for dynamic properties), but complex cases may require IDE tooltips or pair programming.
  • Provide a cheat sheet for common patterns (e.g., expect()->toBeInstanceOf() chaining).
• Debugging:
  • Use phpstan debug to diagnose configuration issues.
  • Leverage PestStan’s error messages (e.g., pest.expectation.impossible) to guide fixes.
• Community:
  • GitHub issues for PestStan are limited; rely on Pest/PHPStan communities for broader questions.

Scaling

• Performance:
  • PHPStan analysis time increases with test suite size. Optimize by:
    • Running PestStan only on changed files (phpstan analyse tests/Feature/NewTest.php).
    • Using --memory-limit=1G or parallel analysis (phpstan --parallel).
  • For large monorepos, consider splitting tests into separate PHPStan projects.
• Rule Customization:
  • Disable rules for specific files or directories:

    paths:
        tests/Integration:
            ignoreErrors:
                - pest.test.duplicateDescription
    

• CI/CD:
  • Cache PHPStan’s phpstan.neon and vendor/ directory to reduce build times.
  • Use GitHub Actions’ actions/cache or Laravel Forge’s composer cache.

Failure Modes

Ramp-Up

• Training:
  • Workshop: Demo PestStan’s features (e.g., type narrowing, $this binding) in a 30-minute session.
  • **