Code Style Php Laravel Package

Getting Started

Minimal Setup

1. Install the package in your Laravel project:

   composer require --dev chiiya/code-style-php
   

2. Copy the provided config files from the package into your project root:

   cp vendor/chiiya/code-style-php/.php-cs-fixer.dist.php .
   cp vendor/chiiya/code-style-php/ecs.php .
   cp vendor/chiiya/code-style-php/rector.php .
   

3. Run a dry fix to verify compatibility:

   ./vendor/bin/php-cs-fixer fix --dry-run
   ./vendor/bin/ecs check
   ./vendor/bin/rector process --dry-run
   

First Use Case

Integrate with GrumPHP (included as a dev dependency) for pre-commit hooks:

1. Install GrumPHP:

   composer require --dev phpro/grumphp
   

2. Configure .grumphp.yml to use the new configs:

   parameters:
     tasks:
       phpcsfixer:
         config: .php-cs-fixer.dist.php
       ecs:
         config: ecs.php
       rector:
         config: rector.php
   

Implementation Patterns

Workflow Integration

1. Daily Linting Add a fix script to package.json or composer.json:

   "scripts": {
     "lint:fix": "php-cs-fixer fix && ecs check --fix && rector process"
   }
   

   Run via:

   npm run lint:fix  # or `composer lint:fix`
   

2. CI/CD Pipeline Use the package in GitHub Actions (example):

   - name: Run Code Style Checks
     run: |
       ./vendor/bin/php-cs-fixer fix --dry-run
       ./vendor/bin/ecs check
       ./vendor/bin/rector process --dry-run
   

3. Laravel-Specific Patterns

   • Artisan Commands: Extend php artisan with custom commands for team-wide fixes:

     // app/Console/Commands/FixCodeStyle.php
     public function handle() {
         $this->call('vendor:publish', ['--provider' => 'Chiiya\CodeStyle\CodeStyleServiceProvider']);
         $this->info('Published configs. Run `php-cs-fixer fix` next.');
     }
     

   • Laravel Forge/Envoyer: Deploy with pre-configured hooks to auto-fix on merge.

4. Team Onboarding Include the configs in your README.md under "Development Setup" with:

   ## Code Style
   Ensure your IDE uses these configs:
   - PHP-CS-Fixer: [`.php-cs-fixer.dist.php`](.php-cs-fixer.dist.php)
   - ECS: [`ecs.php`](ecs.php)
   - Rector: [`rector.php`](rector.php)
   

Gotchas and Tips

Pitfalls

1. PHP Version Mismatch

   • The package requires PHP 8.2+. If your project uses an older version, alias the configs manually or fork the package.
   • Fix: Downgrade dependencies in composer.json or use a wrapper script:

     alias cs-fixer='php82 ./vendor/bin/php-cs-fixer'
     

2. Rector Breaking Changes

   • Rector’s InlineArrayReturnAssignRector (added in v1.10.0) may refactor existing logic unexpectedly.
   • Debug Tip: Run Rector with --dry-run and --diff to preview changes:

     ./vendor/bin/rector process --dry-run --diff
     

3. ECS vs. PHP-CS-Fixer Overlap

   • Some rules (e.g., no_unused_imports) exist in both tools and may conflict.
   • Solution: Disable duplicates in one config. Example in ecs.php:

     return ECSConfig::configure()
         ->withRules([
             // Explicitly exclude PHP-CS-Fixer’s unused-imports rule
             new NoUnusedImports(),
         ])
         ->withParallel();
     

4. GrumPHP Caching Issues

   • GrumPHP may cache task results, masking new rule violations.
   • Fix: Clear cache or use --no-cache:

     ./vendor/bin/grumphp run --no-cache
     

Debugging Tips

1. Isolate Rule Failures Use --rules flags to test individual tools:

   ./vendor/bin/php-cs-fixer fix --rules=@PSR12 --dry-run
   ./vendor/bin/ecs check --rules=Symplify\CodingStandard\Rules\Arrays\ArrayPushArrayRule
   

2. Custom Rule Exclusions Exclude specific files/directories in configs:

   // .php-cs-fixer.dist.php
   return PhpCsFixerConfig::create()
       ->withRules([
           '@PSR12' => true,
       ])
       ->withPath('src/')
       ->ignore(['tests/Feature/']);
   

3. IDE Integration

   • PHPStorm: Import .php-cs-fixer.dist.php via: Settings > Languages & Frameworks > PHP > Code Sniffer > Scheme > Import Configuration.
   • VSCode: Use the PHP CS Fixer extension with the config path set to .php-cs-fixer.dist.php.

Extension Points

1. Custom Rules Extend the configs by merging additional rules. Example for rector.php:

   use Rector\Core\Configuration\Option;
   use Rector\Core\ValueObject\PhpVersion;
   
   return static function (RectorConfig $rector): void {
       $rector->importNames();
       $rector->importShortClasses();
       $rector->ruleWithConfiguration(
           InlineArrayReturnAssignRector::class,
           [Option::PHP_VERSION_FEATURES => PhpVersion::PHP_82]
       );
       // Add your custom rector here
       $rector->rule(CustomRector::class);
   };
   

2. Dynamic Configs Use Laravel’s Service Provider to load configs dynamically:

   // app/Providers/CodeStyleServiceProvider.php
   public function boot() {
       $this->publishes([
           __DIR__.'/../../config/code-style.php' => config_path('code-style.php'),
       ], 'code-style');
   }
   

   Then reference config('code-style.php-cs-fixer') in your configs.

3. Git Hooks Auto-fix on git commit via a pre-commit hook:

   echo '#!/bin/sh
   ./vendor/bin/php-cs-fixer fix --dry-run || exit 1' > .git/hooks/pre-commit
   chmod +x .git/hooks/pre-commit