Psr2R Sniffer Laravel Package

Technical Evaluation

Architecture Fit

• Leverage for Laravel/PHP Projects: This package is a PSR-2-R (PHP-FIG Rectified Standards) Code Sniffer, designed to enforce modern PHP coding standards (e.g., PSR-2 with PHP 8.1+ optimizations). It is ideal for Laravel projects due to:
  • Strict adherence to PSR-2 (already a Laravel best practice).
  • PHP 8.1+ compatibility (aligns with Laravel’s long-term support).
  • Auto-fixing capabilities (reduces manual refactoring).
  • Integration with PHP_CodeSniffer (widely used in PHP ecosystems).
• Key Strengths:
  • 230+ sniffs covering syntax, docblocks, whitespace, and semantic checks.
  • Support for modern PHP features (enums, generics, attributes).
  • CI/CD-friendly (can block merges via GitHub Actions, GitLab CI, etc.).
  • IDE integration (PHPStorm, VSCode) for real-time feedback.

Integration Feasibility

• Low-Coupling Design: Works as a dev dependency (composer require --dev), requiring only a phpcs.xml config.
• No Core Laravel Modifications Needed: Runs as a pre-commit hook or CI step without altering Laravel’s architecture.
• Compatibility:
  • PHP 8.1+ (Laravel 9+ compatible).
  • Works alongside existing tools (PHPStan, Psalm, Pest).
  • Extensible (can add custom sniffs or disable rules via phpcs.xml).

Technical Risk

Key Questions for TPM

1. Adoption Strategy:
   • Should this replace existing phpcs (e.g., squizlabs/PHP_CodeSniffer) or run alongside it?
   • How will we phase in stricter rules (e.g., docblock requirements) without disrupting velocity?
2. Rule Customization:
   • Which Laravel-specific patterns (e.g., magic methods, Facade usage) should be exempted from sniffs?
   • Should we whitelist certain files (e.g., legacy migrations)?
3. CI/CD Integration:
   • Should failures block merges (strict) or just warn (lenient)?
   • How will we handle auto-fix (phpcbf) in PRs vs. manual fixes?
4. Developer Experience:
   • Should we integrate with Git hooks (pre-commit) or rely on CI-only enforcement?
   • How will we train teams on the new standards (e.g., docblock formatting)?
5. Long-Term Viability:
   • Will this conflict with Laravel’s internal coding standards (e.g., laravel-shift/coding-standard)?
   • Should we fork the package to add Laravel-specific sniffs (e.g., for Eloquent queries)?

Integration Approach

Stack Fit

• Primary Use Case: Code Quality Gate in CI/CD pipelines (e.g., GitHub Actions, Jenkins).
• Secondary Use Case: Local Development (IDE integration, pre-commit hooks).
• Compatibility Matrix:

  Component	Version Requirement	Laravel Compatibility
  PHP	≥8.1	Laravel 9+ (LTS)
  Laravel	Any (no core changes)	Full
  PHP_CodeSniffer	v4+ (bundled dependency)	Automatic
  Composer	≥2.0	Required
  IDEs (PHPStorm/VSCode)	Plugin support	Full (via external tools)

Migration Path

1. Assessment Phase (Week 1):
   • Audit existing codebase for PSR-2 violations using phpcs --report=summary.
   • Identify high-impact rules (e.g., docblocks, whitespace) vs. low-impact (e.g., trailing commas).
2. Pilot Phase (Week 2):
   • Add to composer.json (require-dev).
   • Configure phpcs.xml with lenient rules (e.g., severity=5 for warnings).
   • Run in CI as a warning-only check.
3. Enforcement Phase (Week 3+):
   • Gradually tighten rules (e.g., severity=9 for errors).
   • Enable auto-fix (phpcbf) in CI for fixable issues.
   • Add to pre-commit hooks (e.g., via husky or pre-commit).
4. Optimization Phase:
   • Customize rules for Laravel-specific patterns (e.g., Facade methods).
   • Add IDE integration (PHPStorm/VSCode shortcuts).

Compatibility Considerations

• Existing Tools:
  • PHPStan/Psalm: PSR-2-R sniffs complement static analysis (e.g., docblocks improve type inference).
  • Laravel Pint: Can run parallel to PSR-2-R (Pint for formatting, PSR-2-R for semantics).
  • Laravel Shift Coding Standard: May overlap; audit for redundancy before adopting.
• Conflict Resolution:
  • Use phpcs.xml to override conflicting rules (e.g., disable PSR2.Methods.Underscore if Laravel uses snake_case).
  • Example:

    <rule ref="PSR2.Methods.Underscore">
      <severity>0</severity> <!-- Disable -->
    </rule>
    

Sequencing

1. Phase 1: CI-Only Enforcement
   • Add to .github/workflows/ci.yml:

     - name: PSR-2-R Sniffer
       run: vendor/bin/phpcs --standard=vendor/fig-r/psr2r-sniffer/PSR2R/ruleset.xml --warning-severity=5
     

2. Phase 2: Local Development
   • Add to package.json (for Node-based projects):

     "scripts": {
       "lint:php": "php vendor/bin/phpcs src/ tests/"
     }
     

   • Configure pre-commit hooks (e.g., simple-php-unit-tester).
3. Phase 3: IDE Integration
   • Set up PHPStorm External Tools (as per README) for Ctrl+Comma sniffs.
4. Phase 4: Auto-Fixing
   • Add phpcbf to CI for auto-correctable issues:

     - name: Auto-Fix PSR-2-R
       run: vendor/bin/phpcbf src/ tests/
     

Operational Impact

Maintenance

• Proactive:
  • Version Pinning: Lock fig-r/psr2r-sniffer to a minor version (e.g., ^2.7) to avoid breaking changes.
  • Dependency Updates: Monitor squizlabs/PHP_CodeSniffer for major updates (e.g., v4 → v5).
• Reactive:
  • Rule Customization: Maintain a phpcs.xml template for onboarding new devs.
  • Sniff Updates: Review changelogs (e.g., 2.7.1) for new rules.
• Tooling:
  • CI Maintenance: Update workflows if PHP_CodeSniffer’s CLI args change.
  • IDE Plugins: Ensure PHPStorm/VSCode plugins are updated.

Support

• Developer Onboarding:
  • Documentation: Create a CONTRIBUTING.md snippet explaining:
    • How to run