Coding Standard Laravel Package

Getting Started

Minimal Setup

1. Installation Update the package via Composer in your Laravel project:

   composer require --dev dbrekelmans/coding-standard
   

   Ensure php-cs-fixer is installed globally or as a dev dependency (v3.x+ recommended for compatibility):

   composer require --dev friendsofphp/php-cs-fixer:^3.0
   

2. Configuration Create or update .php-cs-fixer.dist.php to leverage the updated ruleset:

   <?php
   return (new PhpCsFixer\Config())
       ->setRules([
           '@dbrekelmans/coding-standard' => true, // Updated to v1.3
           'array_syntax' => ['syntax' => 'short'],
       ]);
   

3. First Use Case Run the updated coding standard fixer on a single file:

   vendor/bin/php-cs-fixer fix app/Models/User.php
   

   Or fix all files in a directory:

   vendor/bin/php-cs-fixer fix app/
   

4. CI/CD Integration Update CI scripts to reflect the new ruleset:

   {
       "scripts": {
           "test:cs": "php-cs-fixer fix --dry-run --diff --rules=@dbrekelmans/coding-standard"
       }
   }
   

Implementation Patterns

Workflows

1. Team Onboarding

   • Share the updated .php-cs-fixer.dist.php (now using Doctrine v8.1) in team docs.
   • Example workflow for new developers:

     git clone <repo>
     composer install
     composer cs-fix  # Updated ruleset
     

2. Pre-Commit Hooks Use the updated package with modern tools like php-cs-fixer v3.x:

   composer require --dev friendsofphp/php-cs-fixer:^3.0
   vendor/bin/php-cs-fixer fix --dry-run --diff
   

   Integrate with tools like Husky or Laravel Pint.

3. Project-Specific Overrides Extend the updated ruleset (now based on Doctrine v8.1):

   return (new PhpCsFixer\Config())
       ->setRules([
           '@dbrekelmans/coding-standard' => true,
           'no_unused_imports' => true,
           'ordered_imports' => ['sort_algorithm' => 'alpha'],
       ]);
   

4. Laravel-Specific Files Target Laravel files with the updated ruleset:

   vendor/bin/php-cs-fixer fix database/migrations/ --rules=@dbrekelmans/coding-standard,ordered_class_elements
   

Integration Tips

• Laravel Pint: Ensure Pint uses the updated config:

  pint --config=.php-cs-fixer.dist.php
  

• IDE Support: Update IDE settings to use the new ruleset (e.g., VSCode):

  {
      "php-cs-fixer.executablePath": "vendor/bin/php-cs-fixer",
      "php-cs-fixer.rules": "@dbrekelmans/coding-standard"
  }
  

• Composer 2 Support: Leverage the updated package’s Composer 2 compatibility for modern workflows.

Gotchas and Tips

Pitfalls

1. Rule Conflicts

   • The updated ruleset (Doctrine v8.1) may introduce stricter checks. Test with --dry-run:

     vendor/bin/php-cs-fixer fix app/Http/Controllers/ --dry-run
     

   • Common conflicts:
     • array_syntax: Short syntax may now be enforced more strictly.
     • concat_space: Doctrine v8.1 may enforce spaces in concatenation ($a . $b).

2. Performance

   • Use --parallel for multi-core systems (supported in php-cs-fixer v3.x):

     vendor/bin/php-cs-fixer fix --parallel
     

   • Cache results in CI with --cache-file=.php-cs-fixer.cache.

3. False Positives

   • Doctrine v8.1 rules may flag Laravel patterns (e.g., Route::group). Exclude or override:

     ->setRules([
         '@dbrekelmans/coding-standard' => true,
         'no_unused_imports' => false, // Disable if Facades cause issues
     ]);
     

4. Breaking Changes

   • Doctrine v8.1: Some rules (e.g., php_unit_test_class_requires_covers) may now apply to tests.
   • Composer 2: Ensure your composer.json is compatible (e.g., no composer.lock conflicts).

Debugging

• Dry Runs: Always use --dry-run to preview changes:

  vendor/bin/php-cs-fixer fix --dry-run --diff
  

• Verbose Output: Debug with -v (now supported in php-cs-fixer v3.x):

  vendor/bin/php-cs-fixer fix -v
  

• Specific Rule Testing: Test individual rules:

  vendor/bin/php-cs-fixer fix --rules=whitespace_after_comma
  

Extension Points

1. Custom Rules Add Laravel-specific rules to the updated config:

   ->setRules([
       '@dbrekelmans/coding-standard' => true,
       'return_type_declaration' => [
           'space' => 'none',
           'nullable_type_declaration_for_builtin_types' => false,
       ],
   ]);
   

2. Path Exclusions Exclude vendor or generated files (now compatible with php-cs-fixer v3.x):

   ->setFinder(
       PhpCsFixer\Finder::create()
           ->in(__DIR__)
           ->exclude('vendor')
           ->exclude('bootstrap/cache')
   );
   

3. Git Integration Use git diff with the updated ruleset:

   git diff --name-only | xargs vendor/bin/php-cs-fixer fix --dry-run
   

4. Combining with Other Tools

   • Use with pest or phpunit for test-specific rules:

     vendor/bin/php-cs-fixer fix tests/ --rules=@dbrekelmans/coding-standard,no_unused_imports
     

   • Integrate with psalm for static analysis alongside CS fixes.