Ecs Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require --dev craftcms/ecs
   

   Ensure PHP_CodeSniffer (squizlabs/php_codesniffer) and ECS (symplify/easy-coding-standard) are also installed:

   composer require --dev squizlabs/php_codesniffer symplify/easy-coding-standard
   

2. First Run Execute ECS with the default Craft CMS ruleset:

   vendor/bin/ecs check src
   

   Fix issues automatically (if desired):

   vendor/bin/ecs fix src
   

3. Key Files

   • ecs.php: Main configuration file (auto-generated by the package).
   • .php_cs: PHP_CodeSniffer config (optional, but often used alongside ECS).

Implementation Patterns

Workflow Integration

1. Pre-Commit Hooks Use ECS in a Git pre-commit hook to enforce standards before code is committed:

   composer require --dev php-cs-fixer
   echo 'vendor/bin/ecs check src --parallel' >> .git/hooks/pre-commit
   

   Tip: Use ecs check --parallel for faster execution on large codebases.

2. CI/CD Pipeline Add ECS to your CI pipeline (e.g., GitHub Actions) to block non-compliant code:

   - name: Run ECS
     run: vendor/bin/ecs check src --no-interaction --ansi
   

3. Custom Rulesets Extend the default ruleset by creating a custom ecs.php:

   <?php
   return [
       'rules' => [
           \CraftCMS\EasyCodingStandard\Sniffs\Arrays\ArrayKeySpacingSniff::class,
           \Symplify\EasyCodingStandard\Sniffs\Arrays\ArrayKeySpacingSniff::class,
           // Add custom rules here
       ],
   ];
   

4. Team Onboarding Document the ECS rules in your CONTRIBUTING.md or README.md to onboard new developers:

   ## Code Standards
   Run `composer lint` to check your code against Craft CMS standards.
   

Gotchas and Tips

Common Pitfalls

1. Performance with Large Codebases

   • Use --parallel to speed up checks:

     vendor/bin/ecs check src --parallel
     

   • Exclude generated or vendor files in ecs.php:

     return [
         'exclude' => [
             'vendor/**',
             'storage/**',
             'web/assets/**',
         ],
     ];
     

2. Conflicting Rules

   • Some ECS rules may conflict with PHP_CodeSniffer (e.g., array syntax). Prioritize one tool over the other by adjusting configs.
   • Example: Disable a rule in ecs.php:

     return [
         'rules' => [
             \Symplify\EasyCodingStandard\Sniffs\Arrays\ArrayKeySpacingSniff::class => false,
         ],
     ];
     

3. Fixing vs. Checking

   • ecs fix may not handle all edge cases (e.g., complex logic). Review changes manually after auto-fixing.
   • Use --dry-run to preview changes:

     vendor/bin/ecs fix src --dry-run
     

4. Caching Issues

   • Clear ECS cache if rules seem outdated:

     vendor/bin/ecs clear-cache
     

Pro Tips

1. Custom Sniffs Add project-specific sniffs by extending the ruleset:

   return [
       'imports' => [
           __DIR__ . '/rules/CustomSniff.php',
       ],
   ];
   

2. Partial Fixes Fix specific files without running the full suite:

   vendor/bin/ecs fix src/plugins/MyPlugin/services/MyService.php
   

3. IDE Integration Use PHPStorm’s "Reformat Code" with ECS by configuring the php-cs-fixer plugin to use ECS rules.

4. Version Pinning Pin the ECS package version in composer.json to avoid rule changes across updates:

   "require-dev": {
       "craftcms/ecs": "^1.0"
   }
   

5. Debugging Rules Use --verbose to debug why a rule is failing:

   vendor/bin/ecs check src --verbose