Coding Standard Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package as a dev dependency:

   composer require --dev chaplean/coding-standard
   

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

   <?xml version="1.0"?>
   <ruleset name="Project Standards">
       <config name="installedPackages" value="chaplean/coding-standard"/>
       <rule ref="Chaplean"/>
   </ruleset>
   

3. First Execution Run PHPCS on your Laravel app directory:

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

4. Auto-Fix Common Issues Use phpcbf for quick fixes:

   vendor/bin/phpcbf --standard=Chaplean app/
   

Where to Look First

• Package Rules: Examine vendor/chaplean/coding-standard/ruleset.xml for custom rules.
• PHPCS Documentation: PHP_CodeSniffer Manual for advanced usage.
• Laravel-Specific Files: Check if Blade templates or facades are covered (may need exclusions).

Implementation Patterns

Core Workflows

1. CI/CD Integration Add to your GitHub Actions workflow:

   - name: PHP Coding Standards
     run: |
       vendor/bin/phpcs --standard=Chaplean \
         --warning-severity=3 \
         --errors-on-warning \
         --extensions=php \
         app/
   

2. Pre-Commit Hook Use with Laravel Pint or Pre-Commit:

   # .pre-commit-config.yaml
   - repo: local
     hooks:
       - id: phpcs
         name: Chaplean Coding Standards
         entry: vendor/bin/phpcs --standard=Chaplean
         language: system
         types: [php]
         args: ["--extensions=php", "app/"]
   

3. IDE Setup

   • PHPStorm: Go to Settings > Editor > Code Style > PHP > PHP Code Sniffer and add the standard.
   • VSCode: Configure phpcs.executablePath in settings.json:

     {
       "phpcs.executablePath": "vendor/bin/phpcs",
       "phpcs.standard": "Chaplean"
     }
     

4. Custom Rule Overrides Extend or disable rules in .phpcs.xml:

   <rule ref="Chaplean">
       <exclude name="Generic.Files.LineEndings"/>
       <arg name="extensions" value="php,blade"/>
   </rule>
   

Laravel-Specific Patterns

• Exclude Blade Templates Add to .phpcs.xml:

  <file>./resources/views/</file>
  <exclude-pattern>.*\.blade\.php$</exclude-pattern>
  

• Focus on Critical Paths Run PHPCS only on app/ and config/ directories:

  vendor/bin/phpcs --standard=Chaplean --extensions=php app/ config/
  

• Diff Mode for PRs Check only changed files in a PR:

  vendor/bin/phpcs --standard=Chaplean --diff app/
  

Gotchas and Tips

Common Pitfalls

1. Rule Conflicts with PSR-12

   • Chaplean may override or extend PSR-12 rules. Test conflicts:

     vendor/bin/phpcs --standard=PSR12 app/ | head -n 20
     vendor/bin/phpcs --standard=Chaplean app/ | head -n 20
     

   • Fix: Use <rule ref="PSR12"/> alongside Chaplean and resolve overlaps.

2. Blade Template Issues

   • PHPCS may flag Blade syntax as errors. Exclude views:

     <exclude-pattern>.*/resources/views/.*</exclude-pattern>
     

3. Performance in Large Projects

   • Full scans on monorepos can be slow. Use caching:

     vendor/bin/phpcs --standard=Chaplean --cache=~/.phpcs_cache app/
     

4. False Positives in Facades

   • Laravel facades (e.g., Cache::get()) may trigger generic rules. Override:

     <exclude name="Generic.Files.LineLength.TooLong"/>
     

Debugging Tips

• Verbose Output Run with -v for detailed errors:

  vendor/bin/phpcs -v --standard=Chaplean app/
  

• Rule-Specific Debugging Isolate a rule:

  vendor/bin/phpcs --standard=Chaplean --ruleset=Chaplean.Generic app/
  

• IDE Debugging For VSCode/PHPStorm, enable PHPCS logging:

  {
    "phpcs.logLevel": "debug"
  }
  

Configuration Quirks

1. Case Sensitivity Ensure .phpcs.xml paths use forward slashes (/), even on Windows.

2. Composer Autoload If rules aren’t loading, run:

composer dump-autoload

3. **PHPCS Version Mismatch**
 Pin `phpcs` version in `composer.json`:
 ```json
 "require-dev": {
     "squizlabs/php_codesniffer": "^3.7"
 }

Extension Points

1. Custom Rules Add project-specific rules by extending the ruleset:

   <rule ref="Chaplean">
       <config name="customRule" value="your_rule_path"/>
   </rule>
   

2. Sniff Development Create a custom sniff in app/CodeSniffer/ and reference it:

   <rule ref="app/CodeSniffer/YourSniff"/>
   

3. CI-Specific Adjustments Use environment variables to toggle strictness:

   - run: vendor/bin/phpcs --standard=Chaplean --${{ env.STRICT_MODE == 'true' && 'error-severity=3' || 'warning-severity=3' }} app/
   

Pro Tips

• Start with Warnings Begin with --warning-severity=3 in CI to avoid blocking PRs.

• Document Exceptions Use @codingStandardsIgnoreStart in files for justified violations:

  // @codingStandardsIgnoreStart
  $legacyCode = "..."; // Ignore for legacy reasons
  // @codingStandardsIgnoreEnd
  

• Pair with Laravel Pint Use pint for formatting and Chaplean for standards:

  composer require --dev laravel/pint
  vendor/bin/pint --test
  vendor/bin/phpcs --standard=Chaplean app/