Psr2R Sniffer Laravel Package

Getting Started

Install the package as a dev dependency using Composer:

composer require --dev fig-r/psr2r-sniffer

Create a phpcs.xml file in your project root referencing the provided ruleset:

<?xml version="1.0"?>
<ruleset name="PSR-2-R">
    <rule ref="vendor/fig-r/psr2r-sniffer/PSR2R/ruleset.xml"/>
    <file>src/</file>
    <file>tests/</file>
</ruleset>

Run static analysis on your code:

vendor/bin/phpcs
vendor/bin/phpcbf   # Auto-fix where possible

The package is a drop-in extension of PHP_CodeSniffer (PHPCS), so all PHPCS commands and flags (e.g., -v, --ignore, --sniffs) work as expected.

Implementation Patterns

• CI Integration: Use phpcs in pre-commit hooks or CI pipelines (e.g., GitHub Actions, GitLab CI) with phpcs --standard=vendor/fig-r/psr2r-sniffer/PSR2R/ruleset.xml to enforce style rules automatically.
• IDE Setup: Configure external tools in PhpStorm or VS Code to run phpcs and phpcbf on save via keyboard shortcuts (e.g., Ctrl+. for fix, Ctrl+, for check).
• Custom Ruleset Tuning: Extend the default ruleset in phpcs.xml to enable, disable, or configure specific sniffs—especially useful when adopting gradually or accommodating legacy code:

  <rule ref="PSR2.Methods.MethodDeclaration.Underscore">
      <severity>0</severity>
  </rule>
  

• Incremental Adoption: Run phpcbf on new code only by using --ignore patterns for legacy directories, then progressively relax exclusions over time.
• Token Analysis for Custom Sniffs: Use the bundled bin/tokenize utility to inspect PHP token streams when developing custom sniffs—critical for understanding node locations, scope conditions, and brace nesting.

Gotchas and Tips

• PHP 8.1+ Only: This package requires PHP 8.1+, as noted in its README. Ensure your CI/run environment meets this.
• Auto-fix Limitations: Not all sniffs support automatic fixing. Use --sniffs=... with -v to verify whether a violation can be corrected automatically.
• Silencing vs. Excluding: Use <severity>0</severity> to disable a sniff, not <exclude>—the latter only suppresses reporting, not execution, and may affect performance unexpectedly.
• Windows Paths: On Windows, use \ instead of / in CLI commands (e.g., vendor\bin\phpcs)—especially in CI scripts.
• IDE Watchers: Avoid aggressive auto-fix watchers; use only safe sniffs (e.g., EndFileNewline, PHP DocBlockTagOrder) to prevent destructive corrections during active editing.
• Debugging: Add -vvv for deep token-level insight into why a sniff triggers. This is invaluable when debugging false positives or custom sniff behavior.
• Extension Points: Since it's built on PHPCS, leverage existing PHPCS ecosystem tooling—custom standards, report formatters (e.g., checkstyle, json), and integrations with static analysis tools like Psalm or PHPStan via CI pipelines.