Laravel Code Style Laravel Package

Getting Started

Minimal Steps

1. Installation:

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

   • Skip GrumPHP config creation during installation.

2. Publish Configs:

   php artisan vendor:publish --tag="code-style-config"
   

   • Publishes ecs.php, .php-cs-fixer.dist.php, rector.php, and phpstan.neon to your project root.

3. Initialize GrumPHP (if using Git hooks):

   php ./vendor/bin/grumphp git:deinit
   php ./vendor/bin/grumphp git:init
   

4. First Run:

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

   • Fixes basic code style issues immediately.

First Use Case

Run pre-commit checks via GrumPHP to enforce style rules before merging:

./vendor/bin/grumphp run

• Automatically checks PHP-CS-Fixer, ECS, and TLint (default tasks).

Implementation Patterns

Workflows

1. Daily Development:

   • Use php-cs-fixer for quick fixes:

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

   • Run ECS for deeper analysis:

     ./vendor/bin/ecs check src/
     

2. CI Pipeline Integration:

   • Add to .github/workflows/lint.yml:

     - name: Run Code Style Checks
       run: |
         ./vendor/bin/grumphp run
         ./vendor/bin/phpstan analyse --memory-limit=2G
     

3. Team Onboarding:

   • Configure IDEs (PHPStorm/VSCode) to use:
     • PHP-CS-Fixer: ./vendor/bin/php-cs-fixer fix --dry-run
     • ECS: ./vendor/bin/ecs check --fix

4. Custom Rules:

   • Extend ecs.php to add project-specific rules:

     return [
         'rules' => [
             // Custom rule example
             Symfony\CS\Fixer\Rule\ArrayNotationRule::class,
             // ...
         ],
     ];
     

Integration Tips

• GrumPHP: Disable slow tasks (e.g., phpstan) in grumphp.yml and run them separately in CI.
• Rector: Use for refactoring (e.g., upgrade PHP versions):

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

• TLint: Add to grumphp.yml for TypeScript/Laravel Blade checks:

  tasks:
    tlint: ~
  

Gotchas and Tips

Pitfalls

1. GrumPHP Initialization:

   • Forgetting to reinitialize GrumPHP after publishing configs (git:deinit + git:init) causes hooks to fail silently.

2. Performance:

   • phpstan and rector can be slow. Run them in CI, not pre-commit:

     # grumphp.yml
     tasks:
       phpstan: ~  # Disable in GrumPHP
     

3. Config Overrides:

   • Custom rules in ecs.php may conflict with defaults. Use ! to disable:

     return [
         'rules' => [
             '@Symfony' => false,
             Symfony\CS\Fixer\Rule\ClassNotationRule::class,
         ],
     ];
     

Debugging

• Dry Runs: Always use --dry-run first:

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

• Verbose Output: Add -v to see skipped files:

  ./vendor/bin/ecs check -v
  

Extension Points

1. Custom Tasks: Add to grumphp.yml:

   tasks:
     custom_task:
       command: './vendor/bin/your-custom-script.php'
       on_failure: [fail]
   

2. PHPStan Templates: Extend phpstan.neon for project-specific checks:

   includes:
     - vendor/chiiya/laravel-code-style/phpstan.neon
     - phpstan-project.neon  # Your custom rules
   

3. Rector Rulesets: Create a custom ruleset file (rector.php) and reference it:

   return [
       'sets' => [
           Chiiya\LaravelCodeStyle\Rector\Laravel::LARAVEL_10,
           // Add your custom ruleset
       ],
   ];
   

Pro Tips

• IDE Integration: Use PHP-CS-Fixer IDE plugins for real-time fixes.
• Git Hooks: Ensure GrumPHP runs only on relevant files:

  # grumphp.yml
  git_hook_variables:
    EXEC_GRUMPHP_TASKS_ON_FILES_CHANGED_ONLY: true