Coding Standard Laravel Package

Getting Started

Minimal Setup

1. Installation Update to the latest version via Composer:

   composer require --dev phpyh/coding-standard:^3.0.1
   

   This release deprecates legacy rule sets and introduces explicit support for modern PHP syntax, including array_destructuring and match expressions in trailing_comma_in_multiline rules.

2. Basic Usage Run the updated coding standard checker with the new rules:

   php artisan coding-standard:check
   

   The --fix flag now automatically corrects syntax for match expressions and array destructuring.

3. First Use Case Integrate into CI with JSON reporting and explicit rule configuration:

   - name: Run Coding Standard (v3.0.1)
     run: php artisan coding-standard:check --format=json --fix
   

Implementation Patterns

Workflow Integration

1. Pre-Commit Hooks Use JSON output for CI-friendly reporting, now including array_destructuring and match violations:

   php artisan coding-standard:check --format=json > coding-standard.json
   

2. IDE Integration Ensure your IDE uses the latest .php_cs config. Re-publish if needed:

   php artisan vendor:publish --provider="Phpyh\CodingStandard\CodingStandardServiceProvider" --tag="config"
   

   Note: Legacy rule sets are deprecated and will trigger warnings.

3. Explicit Rule Configuration Update config/coding-standard.php to explicitly enable new syntax support:

   'rules' => [
       'trailing_comma_in_multiline' => [
           'enabled' => true,
           'array_destructuring' => true, // Explicitly enabled
           'match' => true, // Explicitly enabled
       ],
   ],
   

4. Automated Fixes The --fix flag now automatically corrects match and array destructuring syntax:

   php artisan coding-standard:check --fix
   

5. Parallel Processing For large codebases, use parallel checks (if supported):

   php artisan coding-standard:check --parallel=4
   

Gotchas and Tips

Pitfalls

1. Deprecated Rule Sets

   • Breaking Change: Older rule sets (pre-3.0) are deprecated and will trigger warnings. Update configs to use explicit syntax:

     // Old (deprecated):
     'rules' => ['legacy_rule_set' => true],
     
     // New (3.0.1+):
     'rules' => [
         'trailing_comma_in_multiline' => [
             'enabled' => true,
             'array_destructuring' => true,
             'match' => true,
         ],
     ],
     

2. False Positives in New Rules

   • match expressions or array destructuring may trigger unexpected warnings. Use explicit rule configuration:

     'rules' => [
         'trailing_comma_in_multiline' => [
             'enabled' => true,
             'array_destructuring' => true,
             'match' => ['enabled' => true, 'ignore_patterns' => ['**/Legacy/*.php']],
         ],
     ],
     

3. Performance

   • Exclude directories to improve speed (e.g., vendor/, storage/):

     php artisan coding-standard:check --exclude="vendor,storage"
     

4. PHP Version Compatibility

   • match expressions require PHP 8.0+. Ensure your project’s PHP version supports them.

Debugging

• Verbose Output Use --verbose to debug new rule applications:

  php artisan coding-standard:check --verbose
  

  Look for logs related to array_destructuring or match violations.

• JSON Output Parse JSON for CI integration, now including new rule types:

  php artisan coding-standard:check --format=json > report.json
  

Extension Points

1. Custom Rulesets for New Syntax Extend the Rule classes to handle match or array destructuring explicitly:

   namespace App\Rules;
   use Phpyh\CodingStandard\Rules\AbstractRule;
   
   class MatchExpressionRule extends AbstractRule {
       protected function getPattern() {
           return '/match\s*\(\s*\(/'; // Target `match` expressions
       }
   }
   

2. Event Listeners for New Violations Hook into coding-standard.checked to log match or array destructuring issues:

   CodingStandard::addListener(function ($violations) {
       $matchViolations = collect($violations)->where('rule', 'match');
       Log::info('Match expression violations:', $matchViolations);
   });
   

3. Integration with PHP-CS-Fixer If using UnderlyingPHP/PhpCsFixer, update .php-cs-fixer.dist.php to include:

   return (new PhpCsFixer\Config())
       ->setRules([
           '@PSR12' => true,
           'array_destructuring_case' => true,
           'match' => true,
       ]);
   

Pro Tips

• Dry Runs for New Rules Preview changes before applying fixes for match or array destructuring:

  php artisan coding-standard:check --fix --dry-run
  

• Team Onboarding Update CODING_STANDARD.md to include:

  • Examples of match and array destructuring violations.
  • How to configure new rules in config/coding-standard.php.
  • Deprecation warnings for legacy rule sets.

• Partial Checks for Legacy Code Target specific files to avoid breaking changes:

  php artisan coding-standard:check app/Http --exclude="**/Legacy*.php"