Phpstan Strict Rules Laravel Package

Getting Started

Minimal Setup

1. Install the package in your Laravel project:

   composer require --dev thecodingmachine/phpstan-strict-rules
   

2. Enable the rules in your phpstan.neon (located in phpstan.neon or phpstan.neon.dist):

   includes:
       - vendor/thecodingmachine/phpstan-strict-rules/phpstan-strict-rules.neon
   

   (If using phpstan/extension-installer, no manual inclusion is needed.)

3. First use case: Run PHPStan on a single file to see immediate feedback:

   vendor/bin/phpstan analyse app/Http/Controllers/ExampleController.php
   

   Focus on exception handling and superglobal usage first, as these are the most critical rules.

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline Add PHPStan to your Laravel CI (e.g., GitHub Actions):

   - name: Run PHPStan
     run: vendor/bin/phpstan analyse --level=5
   

   Start with --level=5 (default) and gradually increase strictness.

2. Team Onboarding

   • Document the rules in your team’s coding guidelines (e.g., "Never use $_GET directly").
   • Use @codingmachine-ignore annotations for edge cases (e.g., legacy code):

     /** @codingmachine-ignore Exception.CatchThrowableNotRethrown */
     try { ... } catch (Throwable $e) { ... }
     

3. Laravel-Specific Patterns

   • Request Handling: Replace $_POST['field'] with Laravel’s request()->input('field').
   • Exception Wrapping: Use Laravel’s throw_if or throw_unauthorized helpers to auto-wrap exceptions:

     throw new \RuntimeException('Failed', 0, $previousException);
     

4. Gradual Adoption

   • Phase 1: Enable rules for new code only (e.g., via paths in phpstan.neon).
   • Phase 2: Fix critical violations (e.g., empty catch blocks) in CI.
   • Phase 3: Enforce default in switch statements for all files.

Gotchas and Tips

Common Pitfalls

1. Superglobals in index.php

   • The package allows superglobals at the root scope (e.g., index.php), but not in classes/controllers.
   • Fix: Move superglobal logic to a service or use Laravel’s app() helper.

2. Empty catch Blocks

   • The rule blocks empty catch blocks unless annotated:

     try { ... } catch (\Exception $e) {
         // @codingmachine-ignore Exception.EmptyCatchBlock
     }
     

   • Tip: Use @codingmachine-ignore sparingly—log or rethrow exceptions instead.

3. PHPStan Version Mismatch

   • The package targets PHPStan 0.12+ (last release: 2021). If using PHPStan 1.x, some rules may fail.
   • Workaround: Pin PHPStan to ^0.12 in composer.json or fork the package.

4. False Positives in Legacy Code

   • Tip: Exclude legacy directories in phpstan.neon:

     paths:
         - app/Http
         - !app/OldCode
     

Debugging Tips

• Rule-Specific Errors: Use --error-format=github for actionable PR comments:

  vendor/bin/phpstan analyse --error-format=github
  

• Custom Annotations: For complex cases, combine with @phpstan-ignore-next-line:

  // @phpstan-ignore-next-line
  throw new \Exception(); // Allows base Exception (violates thecodingmachine rule)
  

Extension Points

1. Customize Rules Override the included ruleset in phpstan.neon:

   includes:
       - vendor/thecodingmachine/phpstan-strict-rules/phpstan-strict-rules.neon
   parameters:
       rules:
           Exception.EmptyCatchBlock: false # Disable if needed
   

2. Add New Rules Extend the package by creating a custom PHPStan extension (see PHPStan docs).

3. Performance

   • Exclude tests or large directories to speed up analysis:

     paths:
         - app
         - !tests