Coding Standard Laravel Package

Getting Started

Minimal Setup

1. Install the package via Composer:

   composer require --dev wyrihaximus/coding-standard
   

2. Run the coding standard against your project:

   vendor/bin/phpcs
   

   (Ensure phpcs is installed globally or via Composer.)

3. First Use Case: Integrate into your CI pipeline (e.g., GitHub Actions) to enforce standards on every commit:

   # .github/workflows/php-cs-fixer.yml
   - name: PHP Coding Standards
     run: vendor/bin/phpcs --standard=WyriHaximus src/
   

Key Files to Review

• phpcs.xml.dist: Default configuration file (auto-generated by the package).
• composer.json: Ensure require-dev includes wyrihaximus/coding-standard.

Implementation Patterns

Workflows

1. Local Development:

   • Use phpcbf (auto-fixer) for quick fixes:

     vendor/bin/phpcbf --standard=WyriHaximus src/
     

   • Run interactively with --diff to preview changes:

     vendor/bin/phpcs --standard=WyriHaximus --diff src/
     

2. CI/CD Integration:

   • GitHub Actions Example:

     - name: Run PHP Coding Standard
       run: |
         composer install --dev
         vendor/bin/phpcs --standard=WyriHaximus --report=json src/ > phpcs-results.json
         # Fail if issues exist
         test -s phpcs-results.json && exit 1 || exit 0
     

   • GitLab CI:

     test:phpcs:
       script:
         - composer install --dev
         - vendor/bin/phpcs --standard=WyriHaximus --warning-severity=0 src/
     

3. Custom Rules:

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

     <config name="installedPaths" value="WyriHaximus,./ruleset.xml"/>
     

   • Add project-specific rules in ruleset.xml:

     <rule ref="WyriHaximus">
       <exclude name="Generic.Files.LineEndings"/>
     </rule>
     

Laravel-Specific Tips

• Exclude Vendor Files: Add to phpcs.xml:

  <arg name="exclude" value="vendor,node_modules"/>
  

• Focus on App/Modules: Run only on relevant directories:

  vendor/bin/phpcs --standard=WyriHaximus app/Http/
  

Gotchas and Tips

Pitfalls

1. False Positives:

   • The standard may flag modern PHP features (e.g., match expressions) as errors.
   • Fix: Update phpcs.xml to include @phpstan-ignore-next-line or suppress rules:

     <rule ref="WyriHaximus">
       <exclude name="SlevomatCodingStandard.TypeHints.DisallowMixedTypeHint"/>
     </rule>
     

2. Performance:

   • Large codebases may slow down phpcs. Use --parallel (PHP 8.1+) for speed:

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

3. Outdated Rules:

   • The package bundles squizlabs/php_codesniffer (v4+) and slevomat/coding-standard (v8+).
   • Tip: Pin versions in composer.json to avoid breaking changes:

     "require-dev": {
       "slevomat/coding-standard": "^8.25.0",
       "squizlabs/php_codesniffer": "^3.13.5"
     }
     

Debugging

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

  vendor/bin/phpcs --standard=WyriHaximus --verbose app/Models/User.php
  

• Rule Documentation: Check PHP_CodeSniffer’s ruleset or Slevomat’s docs for specifics.

Extension Points

1. Custom Sniffs:

   • Create a Custom/Sniffs directory and reference it in phpcs.xml:

     <config name="installedPaths" value="WyriHaximus,./Custom/Sniffs"/>
     

   • Example: Add a sniff to enforce use statements alphabetization.

2. Autoloading:

   • Ensure your composer.json autoloads custom sniffs:

     "autoload-dev": {
       "psr-4": {
         "Custom\\Sniffs\\": "Custom/Sniffs/"
       }
     }
     

3. Integration with PHPStan:

   • Combine with phpstan for static analysis:

     vendor/bin/phpstan analyse --level=5 && vendor/bin/phpcs --standard=WyriHaximus src/
     

Laravel-Specific Quirks

• Artisan Commands: Exclude generated files (e.g., bootstrap/cache/) in phpcs.xml:

  <file>.</file>
  <exclude-pattern>.*/bootstrap/cache/.*</exclude-pattern>
  

• Dynamic Content: Disable rules for Blade templates if needed:

  <rule ref="WyriHaximus">
    <exclude name="Generic.Files.DisallowBlankLines"/>
  </rule>