Code Style Laravel Package

Getting Started

Start by installing the package in your Laravel project’s dev dependencies:

composer require --dev ibexa/code-style:~2.2.0

First Steps:

1. Create a .php-cs-fixer.php file in your project root with the minimal Ibexa config:

   <?php
   return Ibexa\CodeStyle\PhpCsFixer\InternalConfigFactory::build()
       ->setFinder(
           PhpCsFixer\Finder::create()
               ->in(__DIR__ . '/src')
               ->in(__DIR__ . '/tests')
               ->files()->name('*.php')
       );
   

2. Run the fixer to auto-correct code:

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

3. Integrate into CI (e.g., GitHub Actions):

   - name: PHP CS Fixer
     run: ./vendor/bin/php-cs-fixer fix --dry-run --diff
   

First Use Case:

Use it to standardize a new Laravel project or align an existing codebase with Ibexa’s conventions before onboarding new developers. Run php-cs-fixer fix --diff to preview changes.

Implementation Patterns

Core Workflows:

1. Local Development:

   • Add a pre-commit hook (via husky or pre-commit) to run:

     ./vendor/bin/php-cs-fixer fix --allow-risky=yes
     

   • Use IDE integration (PHPStorm/VSCode) with .php-cs-fixer.dist.php for real-time feedback.

2. CI/CD Pipeline:

   • GitHub Actions Example:

     - name: PHP CS Fixer (Fix)
       run: ./vendor/bin/php-cs-fixer fix --dry-run --diff
     - name: PHP CS Fixer (Validate)
       run: ./vendor/bin/php-cs-fixer fix --stop-on-failure
     

   • GitLab CI Example:

     php-cs-fixer:
       script:
         - ./vendor/bin/php-cs-fixer fix --dry-run --diff
         - ./vendor/bin/php-cs-fixer fix --stop-on-failure
     

3. Custom Rulesets: Extend Ibexa’s defaults for Laravel-specific needs:

   $factory = new Ibexa\CodeStyle\PhpCsFixer\InternalConfigFactory();
   $factory->withRules([
       '@PSR12' => true, // Merge with PSR-12 for Laravel compatibility
       'ordered_imports' => ['sort_algorithm' => 'alpha'],
       'no_unused_imports' => true,
   ]);
   

Laravel-Specific Patterns:

• Exclude Vendor Files:

  ->exclude([
      'vendor/',
      'node_modules/',
  ])
  

• Target Blade Templates:

  ->files()->name('*.php')->ignoreDotFiles(true)->notPath('resources/views');
  

• Parallel Execution (for large codebases):

  $factory->runInParallel(); // or `InternalConfigFactory::build(runInParallel: true)`
  

Integration Tips:

• Combine with PHPStan: Add to composer.json:

  "scripts": {
      "test": "phpstan analyse --level=5 && php-cs-fixer fix"
  }
  

• Laravel Valet: Add to ~/.valet/Laravel/valet.php for global projects:

  $this->after('install', function () {
      if (file_exists(__DIR__ . '/../.php-cs-fixer.php')) {
          exec('composer require --dev ibexa/code-style');
      }
  });
  

Gotchas and Tips

Pitfalls:

1. Rule Conflicts:

   • Ibexa’s import_order may conflict with Laravel’s use statements (e.g., use Illuminate\Support\Facades\*).
   • Fix: Override in withRules():

     $factory->withRules([
         'ordered_imports' => false, // Disable if needed
     ]);
     

2. Performance:

   • Parallel mode (runInParallel) can overload CI systems. Test locally first:

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

3. False Positives:

   • Ibexa’s no_unused_imports may flag Laravel’s dynamic use statements (e.g., use \App\{$model}).
   • Fix: Exclude dynamic imports:

     $factory->withRules([
         'no_unused_imports' => true,
         'no_unused_imports' => ['ignore_relative_paths' => true],
     ]);
     

4. Version Locking:

   • The package does not follow SemVer strictly. Minor updates may break compatibility.
   • Tip: Pin to a specific patch version (e.g., ~2.2.3) to avoid surprises.

Debugging:

• Dry Run: Always use --dry-run first to preview changes:

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

• Verbose Mode: Debug rule application:

  ./vendor/bin/php-cs-fixer fix --verbose
  

• Rule Whitelisting: Temporarily disable rules to isolate issues:

  $factory->withRules([
      'phpdoc_align' => false, // Disable problematic rules
  ]);
  

Extension Points:

1. Custom Rulesets: Create a CustomRuleset class to encapsulate Laravel-specific overrides:

   class LaravelRuleset extends Ibexa\CodeStyle\PhpCsFixer\InternalConfigFactory {
       public function __construct() {
           $this->withRules([
               'array_syntax' => ['syntax' => 'short'],
               'concat_space' => ['spacing' => 'one'],
           ]);
       }
   }
   

2. Git Hooks: Add to .git/hooks/pre-commit:

   #!/bin/sh
   ./vendor/bin/php-cs-fixer fix --allow-risky=yes --dry-run || exit 1
   

3. CI Feedback: Use --format=checkstyle for CI tools (e.g., Jenkins, GitLab) to parse violations:

   ./vendor/bin/php-cs-fixer fix --format=checkstyle > php-cs-fixer.xml
   

Pro Tips:

• Laravel-Specific Exclusions: Exclude bootstrap/cache/ and storage/ from analysis:

  ->exclude([
      'bootstrap/cache/',
      'storage/',
  ])
  

• Team Onboarding: Include a CONTRIBUTING.md snippet:

  ## Code Style
  Run `composer cs-fix` to auto-format your code before committing.
  

• Benchmarking: Compare performance with/without parallel mode:

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