Psr2R Sniffer Laravel Package

Getting Started

Minimal Setup

1. Installation:

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

2. Configure phpcs.xml in your project root:

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

3. Run Sniffer:

   vendor/bin/phpcs src/
   

4. Auto-fix Issues:

   vendor/bin/phpcbf src/
   

First Use Case

Run the sniffer on your src/ directory to catch PSR-2-R violations:

vendor/bin/phpcs src/ --standard=PSR2R

Use --sniffs=PSR2R.WhiteSpace to focus on whitespace issues initially.

Implementation Patterns

Daily Workflow

1. Pre-commit Hook: Integrate phpcs into your Git pre-commit hook to enforce standards before merging:

   vendor/bin/phpcs --standard=PSR2R --colors --report=emacs src/ || exit 1
   

2. IDE Integration:

   • Configure PHPStorm to run phpcs on save (via External Tools).
   • Use phpcbf for auto-fixing via hotkey (e.g., Ctrl+Alt+F).

3. CI Pipeline: Add to your CI (GitHub Actions, GitLab CI, etc.):

   - name: Run PSR2R Sniffer
     run: vendor/bin/phpcs --standard=PSR2R --report=checkstyle src/ tests/ > phpcs.xml
   

4. Selective Scanning: Target specific files or directories:

   vendor/bin/phpcs --sniffs=PSR2R.Classes.PropertyDeclaration.Underscore src/Models/
   

Integration Tips

• Exclude Paths: Use <exclude-pattern> in phpcs.xml to skip vendor/ or test files:

  <exclude-pattern>*/vendor/*</exclude-pattern>
  <exclude-pattern>*/tests/Feature/*</exclude-pattern>
  

• Custom Rulesets: Extend the default ruleset by overriding severity:

  <rule ref="PSR2R.Classes.PropertyDeclaration.Underscore">
      <severity>0</severity> <!-- Disable this rule -->
  </rule>
  

• Verbose Debugging: Use -vvv to diagnose tokenization issues:

  vendor/bin/phpcs -vvv src/
  

Laravel-Specific Patterns

1. Service Provider Files: Run sniffer on app/Providers/ to enforce consistent spacing in service method signatures:

   vendor/bin/phpcs --sniffs=PSR2R.WhiteSpace src/Providers/
   

2. Migration Files: Exclude migrations from strict checks (they often use dynamic SQL):

   <exclude-pattern>*/database/migrations/*</exclude-pattern>
   

3. Facade/Helper Methods: Use --sniffs=PSR2R.NamingFunctions to validate helper function names (e.g., snake_case):

   vendor/bin/phpcs --sniffs=PSR2R.NamingFunctions app/Helpers/
   

Gotchas and Tips

Common Pitfalls

1. False Positives in Blade Templates: PSR2R may flag Blade syntax (e.g., @foreach) as invalid control structures. Exclude resources/views/:

   <exclude-pattern>*/resources/views/*</exclude-pattern>
   

2. Tokenization Conflicts:

   • Symfony Components: Some Symfony classes (e.g., ContainerInterface) may trigger PSR2R.Namespaces.ReferenceUsedNamesOnly. Suppress with:

     <rule ref="PSR2R.Namespaces.ReferenceUsedNamesOnly">
         <exclude name="Symfony\Component\DependencyInjection\ContainerInterface"/>
     </rule>
     

   • Laravel Facades: Facades like Route::get() may fail PSR2R.Namespaces.UseStatement.AlphaSort. Disable:

     <rule ref="PSR2R.Namespaces.UseStatement.AlphaSort">
         <severity>0</severity>
     </rule>
     

3. Auto-Fixer Limitations:

   • phpcbf may not fix complex issues (e.g., docblock alignment). Manually edit or suppress:

     <rule ref="PSR2R.Commenting.DocCommentAlignment">
         <severity>0</severity>
     </rule>
     

4. PHP Version Mismatches: Ensure <config name="php_version" value="80100"/> matches your project’s PHP version to avoid false positives for newer syntax (e.g., enums).

Debugging Tips

1. Token Inspection: Use the built-in tokenizer to debug sniffer behavior:

   vendor/bin/tokenize src/Models/User.php -v
   

   Look for unexpected tokens (e.g., T_ATTRIBUTE for PHP 8 attributes).

2. Sniff Isolation: Test individual sniffs to identify culprits:

   vendor/bin/phpcs --sniffs=PSR2R.WhiteSpace src/
   vendor/bin/phpcs --sniffs=PSR2R.NamingFunctions src/
   

3. CI Debugging: Save CI output to a file for review:

   - vendor/bin/phpcs --standard=PSR2R --report=full > phpcs-report.txt
   

Extension Points

1. Custom Sniffs: Extend the sniffer by creating a custom rule (e.g., AppSniffs):

   // app/Sniffs/AppSniffs/DisallowMagicMethodsSniff.php
   class DisallowMagicMethodsSniff implements Sniff {
       public function register() {
           return [T_MAGIC_METHOD];
       }
       public function process($phpcsFile, $stackPtr) {
           $error = 'Magic methods are not allowed';
           return [$stackPtr, $error];
       }
   }
   

   Reference it in phpcs.xml:

   <rule ref="app/Sniffs/AppSniffs/DisallowMagicMethodsSniff"/>
   

2. Overriding Default Rules: Disable or modify sniffs in phpcs.xml:

   <!-- Disable a sniff -->
   <rule ref="PSR2R.ControlStructures.ControlStructureSpacing">
       <severity>0</severity>
   </rule>
   
   <!-- Adjust severity -->
   <rule ref="PSR2R.WhiteSpace.ScopeClosingBrace">
       <severity>5</severity>
   </rule>
   

3. Laravel-Specific Extensions: Create a Laravel-specific ruleset by combining PSR2R with custom sniffs for:

   • Blade template consistency.
   • Eloquent model naming (e.g., User vs users table).
   • Artisan command naming (e.g., make:model).