Phpcs Styles Laravel Package

Getting Started

Minimal Steps

1. Install the Package

   composer require --dev codeat3/phpcs-styles
   

2. Configure PHP-CS-Fixer Update .php-cs-fixer.dist.php to include the ruleset:

   <?php
   return (\Codeat3\PhpcsStyles\Config::getRules())->merge([
       // Customize rules as needed
       'line_ending' => "\n",
   ]);
   

3. First Run Apply fixes to your codebase:

   vendor/bin/php-cs-fixer fix
   

4. Where to Look First

   • Package Source: Review vendor/codeat3/phpcs-styles/src/Config.php for default rules.
   • PHP-CS-Fixer Docs: Refer to Symfony’s PHP-CS-Fixer documentation for rule explanations.
   • Laravel Integration: Check if using laravel-pint (built on PHP-CS-Fixer) for Laravel-specific optimizations.

Implementation Patterns

Usage Patterns

1. Team-Wide Standardization Use the package as a shared baseline for PHP-CS-Fixer across all Laravel projects. Extend with project-specific rules:

   return (\Codeat3\PhpcsStyles\Config::getRules())->merge([
       'php_unit_method_casing' => true,
       'php_unit_test_class_requires_covers' => false,
   ]);
   

2. CI/CD Enforcement Integrate into GitHub Actions (.github/workflows/php-cs-fixer.yml):

   name: PHP-CS-Fixer
   on: [push, pull_request]
   jobs:
     fix:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - run: composer install
         - run: vendor/bin/php-cs-fixer fix --rules=@codeat3/phpcs-styles --dry-run
   

3. IDE Integration

   • PHPStorm: Configure Code Sniffer to use the ruleset:
     1. Go to Settings > Tools > PHP > Code Sniffer.
     2. Set Custom Ruleset to vendor/codeat3/phpcs-styles/ruleset.xml.
   • VSCode: Use the PHP Intelephense extension with:

     "php-cs-fixer.executablePath": "vendor/bin/php-cs-fixer",
     "php-cs-fixer.rules": "@codeat3/phpcs-styles"
     

4. Laravel-Specific Workflows

   • Pint Integration: If using laravel-pint, extend pint.json:

     {
       "preset": "laravel",
       "rules": {
         "@codeat3/phpcs-styles": true
       }
     }
     

   • Pre-Commit Hooks: Add to .git/hooks/pre-commit:

     #!/bin/sh
     vendor/bin/php-cs-fixer fix --rules=@codeat3/phpcs-styles --dry-run
     

Gotchas and Tips

Pitfalls

1. Rule Conflicts with Laravel Defaults

   • Issue: The package’s rules may conflict with Laravel’s default pint or php-cs-fixer configurations (e.g., line length, array syntax).
   • Fix: Merge rules explicitly:

     return (\Codeat3\PhpcsStyles\Config::getRules())->merge([
         'array_syntax' => ['syntax' => 'short'],
         'line_length' => ['line_ending' => "\n", 'allow_parentheses_on_control_structures' => true],
     ]);
     

2. Performance in Large Codebases

   • Issue: Running PHP-CS-Fixer on large Laravel projects (e.g., monoliths) can slow down CI/CD.
   • Fix:
     • Cache results in CI:

       - name: Cache PHP-CS-Fixer
         uses: actions/cache@v3
         with:
           path: ~/.cache/php-cs-fixer
           key: ${{ runner.os }}-php-cs-fixer
       

     • Exclude generated files (e.g., bootstrap/cache):

       $finder->exclude(['bootstrap/cache', 'storage/framework']);
       

3. Missing Ruleset File

   • Issue: The package lacks a standalone ruleset.xml for direct PHPCS use.
   • Workaround: Generate it dynamically:

     vendor/bin/php-cs-fixer dump-ruleset --rules=@codeat3/phpcs-styles > ruleset.xml
     

4. IDE Misconfiguration

   • Issue: IDEs (e.g., PHPStorm) may not auto-detect the ruleset.
   • Fix: Manually point to the generated ruleset.xml or use the CLI path:

     vendor/bin/php-cs-fixer --rules=@codeat3/phpcs-styles
     

Debugging Tips

1. Dry Run with Diff Preview changes before applying:

   vendor/bin/php-cs-fixer fix --rules=@codeat3/phpcs-styles --dry-run --diff
   

2. Rule-Specific Debugging Isolate problematic rules:

   vendor/bin/php-cs-fixer fix --rules=@codeat3/phpcs-styles --rules-to-fix=line_ending
   

3. Logging Enable verbose output for troubleshooting:

   vendor/bin/php-cs-fixer fix --rules=@codeat3/phpcs-styles -v
   

4. Custom Rule Overrides Temporarily disable rules to debug:

   $rules = (\Codeat3\PhpcsStyles\Config::getRules())->getRules();
   unset($rules['no_unused_imports']); // Disable temporarily
   

Extension Points

1. Fork and Extend Fork the package to add custom rules:

   git clone https://github.com/codeat3/phpcs-styles.git
   composer require your-fork/phpcs-styles --dev
   

2. Composer Scripts Automate rule application in composer.json:

   "scripts": {
     "cs-fix": "php-cs-fixer fix --rules=@codeat3/phpcs-styles"
   }
   

   Run with:

   composer cs-fix
   

3. Dynamic Rule Loading Load rules conditionally based on environment:

   $rules = (\Codeat3\PhpcsStyles\Config::getRules());
   if (app()->environment('local')) {
       $rules->setRiskyAllowed(true);
   }
   

Laravel-Specific Tips

1. Pint Integration If using laravel-pint, ensure compatibility:

   composer require --dev laravel/pint
   pint --preset=laravel --rules=@codeat3/phpcs-styles
   

2. Artisan Command Create a custom Artisan command for quick fixes:

   // app/Console/Commands/FixCodeStyle.php
   namespace App\Console\Commands;
   use Illuminate\Console\Command;
   class FixCodeStyle extends Command
   {
       protected $signature = 'code:fix';
       public function handle()
       {
           $this->call('php-cs-fixer', ['--rules=@codeat3/phpcs-styles']);
       }
   }
   

   Register in app/Console/Kernel.php:

   protected $commands = [
       \App\Console\Commands\FixCodeStyle::class,
   ];
   

   Run with:

   php artisan code:fix
   

3. Testing Add PHP-CS-Fixer checks to Laravel’s test suite:

   // tests/Feature/CodeStyleTest.php
   public function test_code_style_compliance()
   {
       $this->artisan('code:fix')
            ->expectsOutputToContain('Everything looks good!')
            ->assertExitCode(0);
   }