Coding Standard Laravel Package

Getting Started

Minimal Steps

1. Install the Package

   composer require --dev respect/coding-standard
   

   This installs the Respect Coding Standard ruleset as a dependency.

2. Run PHP_CodeSniffer Execute the standard against your Laravel project:

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

   • Replace src/ with your target directory (e.g., app/ for Laravel-specific checks).
   • Use --report=summary for a quick overview or --report=full for detailed output.

3. First Use Case

   • Onboarding: Run against a new developer’s PR to enforce consistency.
   • Refactoring: Audit a module before major changes to align with Respect’s conventions.

Implementation Patterns

Workflows

1. CI/CD Pipeline Integration Add to your GitHub Actions or GitLab CI:

   - name: Enforce Respect Coding Standard
     run: vendor/bin/phpcs --standard=Respect --warning-severity=0 src/ || exit 1
   

   • Laravel Tip: Exclude vendor/, storage/, and bootstrap/cache/:

     vendor/bin/phpcs --standard=Respect --ignore="vendor/,storage/,bootstrap/cache/" src/
     

2. Pre-Commit Hook Use husky or a custom script to block commits with violations:

   # .husky/pre-commit
   #!/bin/sh
   vendor/bin/phpcs --standard=Respect --report=summary src/ || exit 1
   

3. IDE Integration Configure PHPStorm or VSCode to use the Respect standard:

   • PHPStorm: Set phpcs.xml path in Settings > Editor > Inspections > PHP > PHP_CodeSniffer.
   • VSCode: Use the PHP Intelephense extension with phpcs.xml configured.

4. Hybrid Standards Combine with Laravel’s PSR-12 or custom rules:

   <!-- phpcs.xml -->
   <ruleset>
       <rule ref="Respect"/>
       <rule ref="PSR12">
           <exclude name="PSR12.Files.SideEffects"/>
       </rule>
   </ruleset>
   

Laravel-Specific Tips

1. Exclude Blade Files Respect’s standard doesn’t handle Blade templates. Exclude them:

   vendor/bin/phpcs --standard=Respect --ignore="*.blade.php" src/
   

2. Facade and Helper Methods Respect may flag Laravel’s app() or facades. Override in phpcs.xml:

   <exclude name="Respect.NamingConventions.ValidMethodName" from="app/Helpers/*.php"/>
   

3. Artisan Command Naming Respect enforces SnakeCase for methods. Laravel’s handle() may conflict. Adjust severity:

   <arg name="severity" value="2" name="Respect.NamingConventions.ValidMethodName"/>
   

Gotchas and Tips

Pitfalls

1. Strict Naming Conventions

   • Issue: Respect enforces snake_case for methods (e.g., get_user()), conflicting with Laravel’s camelCase (e.g., getUser()).
   • Fix: Override or exclude specific rules:

     <exclude name="Respect.NamingConventions.SnakeCaseMethods"/>
     

2. False Positives in Legacy Code

   • Issue: Existing Laravel code may violate Respect’s rules (e.g., AppServiceProvider class names).
   • Fix: Use --ignore or patch violations incrementally:

     vendor/bin/phpcs --standard=Respect --ignore="app/Providers/AppServiceProvider.php" src/
     

3. Performance Overhead

   • Issue: Large codebases (e.g., Laravel + plugins) slow down phpcs.
   • Fix: Parallelize checks:

     vendor/bin/phpcs --standard=Respect --parallel=4 src/
     

4. Dependency Conflicts

   • Issue: doctrine/coding-standard (a transitive dependency) may introduce rule conflicts.
   • Fix: Audit dependencies and pin versions in composer.json.

Debugging Tips

1. Detailed Error Output Use --report=full to diagnose specific violations:

   vendor/bin/phpcs --standard=Respect --report=full src/ | grep "ERROR"
   

2. Rule-Specific Help List available rules:

   vendor/bin/phpcs --standard=Respect --list-rules
   

3. Dry Run with Fixes Test auto-fixes (where supported):

   vendor/bin/phpcs --standard=Respect --fix --dry-run src/
   

Extension Points

1. Custom Rules Extend the standard by adding your own rules to phpcs.xml:

   <rule ref="Respect">
       <arg name="extensions" value="php,blade.php"/>
   </rule>
   

2. Sniff Integration Create custom sniffs for Laravel-specific patterns (e.g., Route::resource naming):

   // CustomSniff.php
   class LaravelRouteSniff implements Sniff {
       public function register() {
           return [T_WHITESPACE, T_DOC_COMMENT_OPEN_TAG];
       }
   }
   

3. Configuration Overrides Use environment-specific configs (e.g., phpcs.dev.xml vs. phpcs.prod.xml) to adjust severity:

   <arg name="severity" value="5" name="Respect.NamingConventions.ValidClassName"/>
   

Laravel-Specific Quirks

1. Service Provider Naming Respect may flag AppServiceProvider as invalid. Exclude:

   <exclude-pattern>*/Providers/AppServiceProvider.php</exclude-pattern>
   

2. Facade Usage Respect’s rules may target Facade::class. Suppress with:

   <exclude name="Respect.NamingConventions.ValidClassName" from="app/Facades/*.php"/>
   

3. Migration Files Exclude or adjust rules for database/migrations:

   vendor/bin/phpcs --standard=Respect --ignore="database/migrations/" src/