Coding Standard Laravel Package

Getting Started

Minimal Setup

1. Install via Composer:

   composer require --dev consistence/coding-standard
   

2. Run PHPCS with the ruleset:

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

   • Replace src/ with your target directory (e.g., app/ for Laravel).

3. First Use Case:

   • Pre-commit hook: Integrate with phpcs to block style violations before commits. Example (Git Hook):

     # .git/hooks/pre-commit
     #!/bin/sh
     vendor/bin/phpcs --standard=Consistence --warning-severity=0 --error-severity=5 $@
     

   • CI Pipeline: Add to phpunit.xml or a CI step (e.g., GitHub Actions):

     <php>
         <file>vendor/bin/phpcs</file>
         <arg>--standard=Consistence</arg>
         <arg>--warning-severity=0</arg>
         <arg>--error-severity=5</arg>
         <arg>src/</arg>
     </php>
     

4. Quick Check:

   • Run against a single file to verify:

     vendor/bin/phpcs --standard=Consistence app/Http/Controllers/ExampleController.php
     

Implementation Patterns

Workflows

1. Daily Development:

   • Local Checks: Run phpcs before committing or pushing:

     alias phpcs="vendor/bin/phpcs --standard=Consistence --warning-severity=0"
     

   • IDE Integration: Configure PHPStorm/VSCode to use the Consistence standard for real-time feedback.

2. Team Onboarding:

   • Add a CONTRIBUTING.md section:

     ## Code Style
     Run `composer phpcs` to check your changes against the Consistence standard.
     

   • Pair with php-cs-fixer for auto-fixing common issues:

     composer require --dev friendsofphp/php-cs-fixer
     vendor/bin/php-cs-fixer fix --rules=@Consistence
     

3. CI/CD Integration:

   • GitHub Actions Example:

     - name: Run PHPCS
       run: vendor/bin/phpcs --standard=Consistence --warning-severity=0 --error-severity=5 src/
     

   • GitLab CI Example:

     test:phpcs:
       script:
         - vendor/bin/phpcs --standard=Consistence --warning-severity=0 --error-severity=5 src/
     

4. Laravel-Specific Patterns:

   • Artisan Command: Create a custom command for quick checks:

     // app/Console/Commands/CheckStyle.php
     namespace App\Console\Commands;
     use Illuminate\Console\Command;
     class CheckStyle extends Command
     {
         protected $signature = 'code:check';
         public function handle()
         {
             $exitCode = shell_exec('vendor/bin/phpcs --standard=Consistence --warning-severity=0 src/ 2>&1', $exitCode);
             if ($exitCode !== 0) {
                 $this->error('Code style violations found!');
                 exit(1);
             }
             $this->info('Code style checks passed!');
         }
     }
     

     Register in app/Console/Kernel.php:

     protected $commands = [
         Commands\CheckStyle::class,
     ];
     

     Run with:

     php artisan code:check
     

5. Custom Rulesets:

   • Extend the standard by creating a custom .phpcs.xml:

     <?xml version="1.0"?>
     <ruleset name="App">
         <config name="installedPaths" value="vendor/consistence/coding-standard"/>
         <rule ref="Consistence"/>
         <!-- Override specific rules -->
         <rule ref="Consistence.Exceptions.ExceptionDeclaration">
             <properties>
                 <property name="exceptionDirectory" value="Exceptions"/>
             </properties>
         </rule>
     </ruleset>
     

     Run with:

     vendor/bin/phpcs --standard=app/.phpcs.xml src/
     

Integration Tips

1. Combine with Other Tools:

   • Use alongside phpstan/extension-installer for static analysis:

     composer require --dev phpstan/extension-installer
     vendor/bin/phpstan analyse --level=5 src/
     

   • Pair with pint (Laravel’s PHP-CS-Fixer wrapper) for auto-fixing:

     composer require laravel/pint --dev
     vendor/bin/pint --test
     

2. Partial Adoption:

   • Start with critical paths (e.g., app/Http/ or app/Models/) before full project adoption.

3. Documentation:

   • Add a STYLE_GUIDE.md with examples of compliant code:

     ## PHPDoc Example
     ```php
     /**
      * @return array<int, string>
      */
     public function getItems(): array
     {
         return ['a', 'b'];
     }
     

     Exception Example

     class ValidationException extends \Exception {}
     

     Array Declaration

     $array = [
         'key' => 'value',
     ];
     

4. Excluding Files:

   • Use .phpcsignore to exclude tests or generated files:

     tests/
     bootstrap/cache/
     vendor/
     

Gotchas and Tips

Pitfalls

1. False Positives:

   • Array Declaration: Rule Squiz.Arrays.ArrayDeclaration may flag valid multi-line arrays. Exclude with:

     <rule ref="Consistence">
         <exclude name="Squiz.Arrays.ArrayDeclaration"/>
     </rule>
     

   • Constructor Calls: Rule may incorrectly flag constructor calls without parentheses (e.g., new Class). Disable with:

     <rule ref="Consistence">
         <exclude name="Consistence.Functions.ConstructorCall"/>
     </rule>
     

2. PHP Version Mismatches:

   • The package drops support for PHP <7.2. Ensure your Laravel project meets this requirement (Laravel 8+ is compatible).

3. Rule Conflicts:

   • PSR-12 vs. Consistence: Some rules (e.g., spacing) may conflict with PSR-12. Audit rules before adoption:

     vendor/bin/phpcs --standard=PSR12 src/ 2>&1 | grep -v "OK"
     vendor/bin/phpcs --standard=Consistence src/ 2>&1 | grep -v "OK"
     

   • PHP-CS-Fixer: If using pint, ensure rules are compatible:

     vendor/bin/php-cs-fixer fix --dry-run --rules=@Consistence
     

4. Performance:

   • PHPCS can be slow on large codebases. Mitigate with:
     • Caching: Use --cache flag or tools like php-parallel-lint.
     • Parallel Runs: Split checks by directory:

       vendor/bin/phpcs --standard=Consistence app/Http/ app/Models/ &
       vendor/bin/phpcs --standard=Consistence app/Console/ app/Providers/ &
       

5. DocBlock Quirks:

   • @var for Constants: The rule disallows @var for constants. Update docblocks:

     // Before (flagged)
     /** @var string */
     const VERSION = '1.0';
     
     // After (compliant)
     const VERSION = '1.0';
     

   • @inheritDoc: Avoid standalone @inheritDoc blocks. Merge with parent docblocks.

6. Exception Rules:

   • Directory Enforcement: The ExceptionDeclaration rule requires exceptions to be in a specific directory (default: Exceptions/). Configure in .phpcs.xml:

     <rule ref="Consistence.Exceptions.ExceptionDeclaration">
         <properties>
             <property name="exceptionDirectory" value="App/Exceptions"/>
         </properties>
     </rule>
     

Debugging

1. Verbose Output:

   • Use --report=full for detailed error messages:

     vendor/bin/phpcs --standard=Consistence --report=full src/
     

2. Rule-Specific Help:

   • List available rules:

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

   • Get help for a specific rule:

     vendor/bin/phpcs --standard=Consistence --help Consistence.Functions.ConstructorCall
     

3. Ignore Specific Errors:

   • Use --ignore=ERROR_CODE to skip known issues:

     vendor/bin/phpcs --standard=Consistence --ignore=Consistence.Arrays.ArrayDeclaration src/
     

Tips

1. Auto-Fix Common Issues:
   • Use php-cs-fixer to automate fixes for spacing