Easy Coding Standard Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require --dev contao/easy-coding-standard
   

   Add the package to your project’s composer.json under require-dev.

2. First Run Execute the default Contao ruleset:

   vendor/bin/ecs check src --config=vendor/contao/easy-coding-standard/ecs.php
   

   Or integrate it into your CI pipeline (e.g., GitHub Actions, GitLab CI).

3. Where to Look First

   • Default Ruleset: Inspect vendor/contao/easy-coding-standard/ecs.php for predefined rules.
   • Customization: Override the ruleset by copying the file to your project (e.g., ecs.php) and modifying it.

4. First Use Case Run ECS on your Contao project’s src/ directory to enforce PSR-12, Contao-specific coding standards, and best practices:

   vendor/bin/ecs check src
   

Implementation Patterns

Usage Patterns

1. Integrate into CI/CD Add ECS to your workflow (e.g., GitHub Actions):

   - name: Run EasyCodingStandard
     run: vendor/bin/ecs check src --config=ecs.php
   

2. Custom Rulesets Extend the default ruleset by merging with your own:

   // ecs.php
   use PhpCsFixer\Config;
   use Symplify\EasyCodingStandard\ValueObject\Option;
   
   return (new Config())
       ->merge(contao_easy_coding_standard())
       ->setRules([
           // Add custom rules here
           '@Symplify:CodingStandard' => true,
       ]);
   

3. Fix Automatically Use --fix to auto-correct issues:

   vendor/bin/ecs fix src
   

4. Parallel Execution Speed up checks with parallel processing:

   vendor/bin/parallel-lint src && vendor/bin/ecs check src --parallel
   

Workflows

• Pre-Commit Hook: Use tools like husky or pre-commit to run ECS before commits.
• Pull Request Checks: Enforce ECS in PRs to maintain consistency.
• Onboarding: Require new developers to run ECS on their first PR.

Integration Tips

• Contao-Specific Rules: Leverage Contao’s built-in rules (e.g., contao/naming for DCA naming conventions).
• Symfony/Doctrine: Combine with @Symfony or @Doctrine rulesets if your project uses them.
• IDE Integration: Configure your IDE (PHPStorm, VSCode) to use ECS for real-time feedback.

Gotchas and Tips

Pitfalls

1. Rule Conflicts

   • Contao’s rules may conflict with other packages (e.g., Symplify). Test thoroughly after merging rulesets.
   • Example: contao/naming might clash with PSR12 for class naming.

2. Performance

   • Running ECS on large codebases can be slow. Use --parallel or exclude tests:

     vendor/bin/ecs check src --exclude=tests/
     

3. False Positives

   • Contao’s legacy code may trigger rules like no_unused_imports. Exclude legacy directories:

     ->setExcludedFiles('legacy/*')
     

4. Configuration Overrides

   • Accidentally overriding Contao’s ruleset entirely can break conventions. Prefer merging:

     ->merge(contao_easy_coding_standard()) // Keep defaults
     

Debugging

• Verbose Output: Use --verbose to diagnose rule failures:

  vendor/bin/ecs check src --verbose
  

• Dry Run: Test changes without modifying files:

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

Tips

1. Incremental Adoption Start with a subset of rules (e.g., @contato/basic) and expand gradually.

2. Document Rules Add a CODING_STANDARDS.md to your repo explaining ECS rules and exceptions.

3. Contao-Specific Extensions

   • Use contato/naming for DCA field naming consistency.
   • Enforce contato/array-syntax for Contao’s array() vs [] preferences.

4. Exclude Vendors Always exclude vendor/ to avoid false positives:

   ->setExcludedFiles('vendor/*')
   

5. Update Rulesets Regularly update contao/easy-coding-standard to align with Contao’s latest standards:

   composer update contao/easy-coding-standard --dev