Onr Phpcs Laravel Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require --dev onramplab/onr-phpcs-laravel
   

   Add to composer.json under require-dev:

   "scripts": {
       "test": [
           "phpcs --standard=./vendor/onramplab/onr-phpcs-laravel/ruleset.xml"
       ]
   }
   

2. First Run Execute in project root:

   composer test
   

   Or directly:

   phpcs --standard=./vendor/onramplab/onr-phpcs-laravel/ruleset.xml app/
   

3. Key Files

   • ruleset.xml: Core ruleset (extends PSR12 + custom Laravel rules).
   • Sniffs/: Custom sniff classes (e.g., LaravelControllerSniff.php).

Implementation Patterns

Workflows

1. Pre-Commit Hook Integrate with phpcs in .git/hooks/pre-commit:

   #!/bin/sh
   composer test || exit 1
   

2. CI/CD Pipeline Add to GitHub Actions (.github/workflows/lint.yml):

   - name: Run PHPCS
     run: composer test
   

3. Custom Rulesets Extend the default ruleset by creating a custom ruleset.xml:

   <ruleset>
       <config name="installedPaths" value="./vendor/onramplab/onr-phpcs-laravel"/>
       <config name="extensions" value="php"/>
       <rule ref="ruleset.xml">
           <exclude name="Laravel.Controller.MethodLength"/>
       </rule>
   </ruleset>
   

Integration Tips

• Laravel IDE Helper: Pair with barryvdh/laravel-ide-helper for consistent docblock standards.
• PHPStorm Integration:
  1. Go to Settings > PHP > Quality Tools > PHP_CodeSniffer.
  2. Set Default Sniffer to the package’s ruleset.xml.
• Team Onboarding: Use phpcs --generate-baseline to create a baseline for new contributors.

Gotchas and Tips

Pitfalls

1. Rule Overrides

   • Custom rules may conflict with PSR12. Test with:

     phpcs --standard=PSR12 app/  # Compare against PSR12 baseline
     

   • Explicitly exclude rules in your ruleset.xml if needed.

2. Performance

   • Exclude vendor/ and node_modules/ from scans to speed up CI:

     phpcs --standard=ruleset.xml --ignore=vendor/,node_modules/ app/
     

3. False Positives

   • Docblock Issues: Laravel’s dynamic properties (e.g., $fillable) may trigger Generic.Files.LineLength. Adjust Generic.Files.LineLength.MaximumLineLength in ruleset.xml:

     <rule ref="Generic.Files.LineLength">
         <properties>
             <property name="maximumLineLength" value="120"/>
         </properties>
     </rule>
     

Debugging

• Verbose Output: Use --verbose to diagnose rule failures:

  phpcs --standard=ruleset.xml --verbose app/Http/Controllers/
  

• Rule-Specific Help: Check the Sniffs/ directory for rule documentation (e.g., LaravelControllerSniff.php comments).

Extension Points

1. Add Custom Sniffs Extend the ruleset by creating a new sniff class in app/CodeSniffer/:

   class CustomLaravelSniff extends \PHP_CodeSniffer\Standards\AbstractStandard {
       public function __construct() {
           parent::__construct();
           $this->register();
       }
   }
   

   Update ruleset.xml to include it:

   <rule ref="CustomLaravelSniff"/>
   

2. Modify Existing Rules Override sniff classes in your project (e.g., app/CodeSniffer/Sniffs/LaravelControllerSniff.php) and reference them in a custom ruleset.xml.

3. Configuration Use phpcs --config-set to tweak settings dynamically:

   phpcs --config-set installed_paths ./app/CodeSniffer