Phpstan Strict Rules Laravel Package

Product Decisions This Supports

• Enforcing PHP Best Practices: This package aligns with initiatives to standardize code quality across the Laravel/PHP codebase, reducing inconsistencies and technical debt. It enforces defensive programming principles (e.g., exception handling, superglobal avoidance) that are critical for maintainability and security.
• Security and Reliability: By catching issues like empty catch blocks, raw Exception throws, and missing switch-case defaults, this package helps prevent production bugs and security vulnerabilities early in the development cycle. This supports broader goals like SOC 2 compliance or zero bug bounties.
• Framework Consistency: Laravel encourages dependency injection and avoids superglobals, but legacy or custom code may violate these principles. This package enforces Laravel’s request/session object usage over superglobals ($_GET, $_POST), reducing friction between custom code and framework conventions.
• Developer Productivity: Automating static analysis via PHPStan reduces manual code reviews for edge cases, allowing developers to focus on feature development. It also standardizes onboarding by automatically rejecting PRs that violate rules (via CI).
• Build vs. Buy Decision: This is a low-effort "buy"—integrating it requires minimal setup (Composer + PHPStan config) compared to building custom rules. The package’s opinionated but proven rules (from TheCodingMachine) justify adoption without reinventing the wheel.
• Use Cases:
  • New Projects: Enforce standards from day one to prevent anti-patterns.
  • Legacy Codebases: Gradually introduce rules via PHPStan’s --level configuration to avoid overwhelming the team.
  • CI/CD Enforcement: Block PR merges that violate rules, ensuring consistency across the codebase.
  • Security Audits: Use as part of shift-left security strategies to catch vulnerabilities early.

When to Consider This Package

• Adopt if:

  • Your team prioritizes defensive programming and proactive bug prevention in PHP/Laravel.
  • You already use PHPStan (or plan to) and want to extend its default rules with industry-proven best practices.
  • Your project is Laravel-based (or another framework) and you want to avoid superglobals in favor of framework-provided abstractions (e.g., Request, Session).
  • You’re willing to trade short-term developer friction (e.g., refactoring superglobals) for long-term code reliability.
  • Your CI/CD pipeline can handle incremental adoption (start with --level=0, then ramp up to stricter levels).
  • You lack the bandwidth to maintain custom static analysis rules but want stricter enforcement than PHPStan’s defaults.

• Look elsewhere if:

  • Your team resists static analysis or prefers runtime checks (e.g., PHPUnit) over static tools.
  • You’re using PHP < 7.4 (this package requires PHP 7.4+).
  • Your project has no PHPStan adoption plan—this package is useless without PHPStan.
  • You need custom rules beyond this package’s scope (e.g., domain-specific logic). Consider:
    • Extending PHPStan directly.
    • Using framework-specific packages like phpstan/phpstan-symfony.
    • The original thecodingmachine/phpstan-strict-rules is revived and actively maintained (monitor forks).
  • Your codebase heavily relies on superglobals (e.g., legacy scripts) or Laravel features that conflict with rules (e.g., public properties in Eloquent models).

How to Pitch It (Stakeholders)

For Executives/Business Leaders:

*"This package is a low-cost, high-impact way to reduce bugs and security risks in our PHP/Laravel codebase. By adopting these stricter PHPStan rules—enforced automatically in our CI pipeline—we’ll catch critical issues like:

• Unhandled exceptions (e.g., empty catch blocks, raw Exception throws).
• Superglobal misuse (e.g., $_GET, $_POST—replaced with Laravel’s Request object).
• Missing edge-case handling (e.g., default cases in switches).

This aligns with our goals for [security compliance/zero bug bounties] while requiring minimal upfront effort. Think of it as ‘static analysis on autopilot’—no manual code reviews needed for these edge cases.

Key Outcomes:

• Fewer production incidents from PHP edge cases.
• Codebase consistency with Laravel’s best practices.
• Reduced onboarding time for new developers (clear standards).
• ROI: Estimated 30–50% reduction in critical bugs from static analysis alone (based on similar adopters).

Ask: Should we pilot this in [Project X] to measure impact before rolling out company-wide?"*

For Engineering Teams:

*"We’re proposing to add kcs/phpstan-strict-rules to our PHPStan setup to enforce TheCodingMachine’s battle-tested PHP best practices. This will catch:

• Exception anti-patterns: Throwing raw Exception, empty catch blocks, or not wrapping exceptions.
• Superglobal misuse: $_GET, $_POST, etc.—replaced with Laravel’s Request object.
• Defensive programming gaps: Missing default cases in switches, public properties.

How it works:

1. Install via Composer:

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

2. Enable in phpstan.neon (or use phpstan/extension-installer for zero config).
3. Start with --level=0 to avoid overwhelming the team, then ramp up.

Why now?

• Aligns with our [Laravel framework standards] and [security initiatives].
• Reduces tech debt by catching issues before they reach production.
• Minimal overhead—PHPStan runs in CI anyway.

Trade-offs:

• Some rules may require code changes (e.g., replacing superglobals, refactoring public properties).
• We’ll phase this in gradually to avoid disruption.

Next Steps:

• Review the rules list to understand impacts.
• Test locally before enabling in CI (e.g., run vendor/bin/phpstan analyse --level=max).
• Propose exclusions for legacy code or Laravel-specific edge cases (e.g., Eloquent models).

Example CI Integration:

# .github/workflows/phpstan.yml
jobs:
  phpstan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: composer install
      - run: vendor/bin/phpstan analyse --level=5 --error-format=github

Questions for the Team:

1. Should we disable specific rules (e.g., NoPublicPropertiesRule for Eloquent)?
2. How should we handle legacy code that violates these rules?
3. Should we integrate this with our existing linting tools (e.g., pint, php-cs-fixer)?"*