Coding Standard Laravel Package

Getting Started

Minimal Steps

1. Install the Package Add the package to your project’s composer.json under require-dev:

   composer require --dev pccomponentes/coding-standard
   

2. Configure PHPCS Create or update phpcs.xml.dist in your project root with:

   <?xml version="1.0"?>
   <ruleset name="Project Coding Standard">
       <rule ref="vendor/pccomponentes/coding-standard/src/ruleset.xml"/>
   </ruleset>
   

   • The .dist suffix ensures it’s copied to phpcs.xml during deployment but ignored in Git.

3. Run PHPCS Lint your codebase:

   vendor/bin/phpcs --standard=PcComponentes app/
   

   • Use --report=full for detailed output or --report=summary for a quick overview.

4. First Use Case: Laravel Controller Validation Enforce consistent method naming and docblock formatting in controllers:

   vendor/bin/phpcs --standard=PcComponentes app/Http/Controllers/
   

   • The standard includes sniffs for RequireSingleLineMethod and docblock consistency.

Implementation Patterns

Daily Workflow Integration

1. Pre-Commit Hook Use a script (e.g., pre-commit.sh) to run PHPCS before commits:

   #!/bin/bash
   vendor/bin/phpcs --standard=PcComponentes --colors --report=emacs app/ || exit 1
   

   • Integrate with tools like Husky for Git hooks.

2. CI/CD Pipeline (GitHub Actions Example) Add PHPCS to your workflow to block non-compliant code:

   name: PHPCS
   on: [push, pull_request]
   jobs:
     phpcs:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - uses: shivammathur/setup-php@v2
           with:
             php-version: '8.2'
         - run: composer install
         - run: vendor/bin/phpcs --standard=PcComponentes --warning-severity=3 app/
   

   • Set --warning-severity=3 to fail builds on warnings.

3. IDE Integration Configure PHPStorm/VSCode to use PHPCS for real-time feedback:

   • PHPStorm: Go to Settings > Languages & Frameworks > PHP > Code Sniffer and set the standard to PcComponentes.
   • VSCode: Install the PHP Intelephense extension and configure phpcs.executablePath to vendor/bin/phpcs.

4. Custom Ruleset for Laravel Extend the standard to enforce Laravel-specific conventions:

   <ruleset>
       <rule ref="vendor/pccomponentes/coding-standard/src/ruleset.xml"/>
       <rule ref="vendor/squizlabs/php_codesniffer/CodeSniffer/Standards/PSR2/PSR2.xml">
           <exclude name="PSR2.Methods.MethodDeclaration"/>
       </rule>
       <arg name="tab-width" value="4"/>
       <arg name="encoding" value="utf-8"/>
   </ruleset>
   

Laravel-Specific Patterns

1. Service Container Sniffs Enforce consistent dependency injection patterns:

   vendor/bin/phpcs --standard=PcComponentes app/Providers/
   

   • Check for bind()/singleton() method naming and docblock consistency.

2. Migration File Validation Validate migration file structure and naming:

   vendor/bin/phpcs --standard=PcComponentes database/migrations/
   

   • Ensure snake_case table names and consistent method ordering.

3. Artisan Command Checks Audit command classes for proper naming and method organization:

   vendor/bin/phpcs --standard=PcComponentes app/Console/Commands/
   

   • Enforce handle() method placement and docblock requirements.

4. Facade and Helper Sniffs Detect misuse of facades or static helpers:

   vendor/bin/phpcs --standard=PcComponentes --extensions=php app/ --ignore=tests/
   

   • Flag direct Cache:: or Auth:: usage where dependency injection is preferred.

Gotchas and Tips

Common Pitfalls

1. Rule Conflicts

   • Issue: Overlapping rules between PcComponentes and PSR2 (e.g., method declaration spacing).
   • Fix: Explicitly exclude conflicting rules in phpcs.xml:

     <rule ref="vendor/pccomponentes/coding-standard/src/ruleset.xml">
         <exclude name="PcComponentes.Sniffs.Methods.RequireSingleLineMethod"/>
     </rule>
     

2. Performance Overhead

   • Issue: PHPCS slows down CI pipelines for large codebases.
   • Fix:
     • Use --ignore=tests/ to skip test files.
     • Parallelize linting with tools like PHP Parallel Lint.
     • Cache results using tools like phpcs-cache.

3. False Positives

   • Issue: Rules flag legitimate code (e.g., legacy do-while loops).
   • Fix: Whitelist exceptions in phpcs.xml:

     <file>app/OldLegacyCode/Controller.php</file>
     <exclude name="PcComponentes.Sniffs.ControlStructures.DoWhileSniff"/>
     

4. IDE Misconfiguration

   • Issue: IDE plugins ignore custom sniffs.
   • Fix:
     • Ensure the IDE’s PHPCS path points to vendor/bin/phpcs.
     • Restart the IDE after configuration changes.

Debugging Tips

1. Verbose Output Use --verbose to debug rule application:

   vendor/bin/phpcs --standard=PcComponentes --verbose app/
   

2. Rule-Specific Debugging Isolate which rule triggers a violation:

   vendor/bin/phpcs --standard=PcComponentes --report=checkstyle app/ | grep -A5 "error"
   

3. Dry Run with Custom Rules Test a subset of rules before full adoption:

   vendor/bin/phpcs --standard=PcComponentes --ruleset=PcComponentes.NamingConventions app/
   

Extension Points

1. Custom Sniffs Add project-specific sniffs by extending the ruleset:

   <rule ref="vendor/pccomponentes/coding-standard/src/ruleset.xml"/>
   <rule ref="path/to/your/custom-sniff.xml"/>
   

2. Overriding Default Rules Modify or disable rules in phpcs.xml:

   <rule ref="vendor/pccomponentes/coding-standard/src/ruleset.xml">
       <config name="single_line_comment_spacing" value="1"/>
   </rule>
   

3. Dynamic Rulesets Use environment variables to switch rulesets:

   RULESET=PcComponentes vendor/bin/phpcs app/
   

   • Requires custom scripting to parse $RULESET.

Laravel-Specific Quirks

1. Blade Template Sniffs

   • Issue: PHPCS may not lint Blade files by default.
   • Fix: Add Blade support via phpcs-blade:

     composer require --dev alexpeattie/phpcs-blade
     

     Update phpcs.xml:

     <file>resources/views/*.blade.php</file>
     <rule ref="vendor/alexpeattie/phpcs-blade/ruleset.xml"/>
     

2. Artisan Command Autoloading

   • Issue: PHPCS may miss autoloaded commands in app/Console/Kernel.php.
   • Fix: Explicitly include the Kernel file in your linting command:

     vendor/bin/phpcs --standard=PcComponentes app/Console/Kernel.php
     

3. Service Provider Sniffs

   • Issue: Long register()/boot() methods may violate line-length rules.
   • Fix: Adjust the line length in phpcs.xml:

     <arg name="line_ending" value="LF"/>
     <arg name="line_length" value="180"/>
     

Pro Tips

1. Autofix Common Issues Pair PHPCS with PHP-CS-Fixer to auto-fix formatting:

   composer require --dev friendsofphp/php-cs-fixer
   vendor/bin/php-cs-fixer fix --rules=@PcComponentes --dry-run