Coding Standard Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment (Updated):
  • Now aligns with Doctrine Coding Standard v8.1, ensuring compatibility with modern Doctrine ORM (3.x) and PHP 8+.
  • PSR-12 + Doctrine-specific rules remain the core focus, but the upgrade to doctrine/coding-standard:^8.1 introduces new rules (e.g., stricter DQL formatting, updated annotation syntax).
  • Laravel Synergy:
    • Still not framework-agnostic, but the Doctrine ORM integration is now more robust for projects using Doctrine directly (not just Eloquent).
    • New risk: If using Eloquent attributes (Laravel 8+), some Doctrine annotation rules may conflict (e.g., @ORM\ vs. #[Attribute]).
  • Overlap with Existing Tools:
    • Laravel’s default php-cs-fixer (via laravel/framework) still covers PSR-12, but this package now explicitly extends Doctrine’s latest standards.
    • Redundancy risk reduced if configured to complement (not replace) existing tools.

Integration Feasibility

• Installation (Updated):
  • Now Composer 2 compatible (no breaking changes for Composer 1 users).
  • Requires PHP_CodeSniffer (squizlabs/php_codesniffer) and Doctrine Coding Standard v8.1.
  • Can be integrated via:

    composer require --dev dbrekelmans/coding-standard doctrine/coding-standard:^8.1
    

• Configuration (Updated):
  • New ruleset may require updated .phpcs.xml:

    <rule ref="Dbrekelmans/CodingStandard">
      <exclude name="Doctrine.Annotations.DeprecatedAnnotations"/> <!-- Example: Exclude deprecated rules -->
    </rule>
    

  • Doctrine v8.1 introduces:
    • Stricter DQL query formatting (e.g., WHERE clause alignment).
    • Updated annotation syntax validation (e.g., @ORM\Column vs. @Column).
• CI/CD Fit (Updated):
  • Works with modern CI tools (GitHub Actions, GitLab CI) but may fail builds if new rules are too strict.
  • Recommendation: Start with --warning-severity=0 to gradually enforce new rules.

Technical Risk

• Rule Conflicts (Updated):
  • New risk: Doctrine v8.1 may deprecate or modify rules (e.g., @ORM\ annotations vs. PHP 8 attributes).
  • Eloquent vs. Doctrine: If using Eloquent attributes, some rules (e.g., @ORM\Table) may trigger false positives.
• Maintenance Burden (Updated):
  • Now depends on doctrine/coding-standard:^8.1, which is actively maintained (unlike the original package).
  • Potential breaking changes if Doctrine updates its ruleset (e.g., stricter DQL validation).
• False Positives/Negatives (Updated):
  • New rules may flag modern Laravel patterns (e.g., #[UniqueEntity] vs. @UniqueEntity).
  • Mitigation: Test against a subset of the codebase before full enforcement.

Key Questions (Updated)

1. Are you using Doctrine ORM 3.x or Eloquent attributes?
   • If Eloquent attributes are primary, some Doctrine rules may not apply or need exclusions.
2. What’s your current Doctrine version?
   • If using Doctrine ORM 2.x, this upgrade may require migration.
3. How strict should DQL formatting be?
   • Doctrine v8.1 introduces new DQL rules—are these critical for your team?
4. Do you need Composer 2 support?
   • If still using Composer 1, this package may not be necessary (but future-proofing is recommended).
5. What’s the fallback if rules conflict?
   • Plan for custom exclusions in .phpcs.xml (e.g., disabling @ORM\ rules for Eloquent-heavy projects).

Integration Approach

Stack Fit (Updated)

• Best For (Updated):
  • Projects using Doctrine ORM 3.x (Laravel 10+ with Doctrine bundles).
  • Teams needing modern Doctrine standards (e.g., stricter DQL, annotation syntax).
  • Composer 2 users (no compatibility issues).
• Less Ideal For (Updated):
  • Pure Eloquent projects (unless using Doctrine annotations).
  • Teams not ready for Doctrine v8.1 rules (e.g., legacy DQL syntax).
• Complementary Tools (Updated):
  • PHPStan/Psalm: For static analysis (logic, not formatting).
  • Laravel Pint: If migrating from php-cs-fixer to Laravel’s built-in formatter.
  • Doctrine Extensions: If using Doctrine behaviors, ensure rules align with stof/doctrine-extensions-bundle.

Migration Path (Updated)

1. Audit Current Setup:
   • Check Doctrine ORM version (composer show doctrine/orm).
   • Verify Composer 2 compatibility (composer --version).
2. Install Updated Package:

   composer require --dev dbrekelmans/coding-standard doctrine/coding-standard:^8.1
   

3. Configure for Doctrine v8.1:
   • Update .phpcs.xml to include new rules:

     <config name="installed_paths" type="array">
       <element>./vendor/dbrekelmans/coding-standard</element>
     </config>
     <rule ref="Dbrekelmans/CodingStandard">
       <exclude name="Doctrine.Annotations.DeprecatedAnnotations"/> <!-- Example exclusion -->
     </rule>
     

4. Test Incrementally:
   • Run with warning mode:

     ./vendor/bin/phpcs --standard=Dbrekelmans/CodingStandard --warning-severity=0 app/
     

   • Fix violations via php-cs-fixer (if automated fixes are needed).

Compatibility (Updated)

• PHP Version: 8.0+ (Doctrine v8.1 requires PHP 8).
• Doctrine Version: 3.x (Laravel 10+ with Doctrine bundles).
• Laravel Version:
  • Works with Laravel 10+ (Doctrine ORM 3.x).
  • Laravel 8/9: May require adjustments for Eloquent attribute conflicts.
• Conflict Mitigation (Updated):
  • Use <exclude> for Eloquent-specific rules:

    <rule ref="Dbrekelmans/CodingStandard">
      <exclude name="Doctrine.Annotations.ORM"/> <!-- Disable if using Eloquent attributes -->
    </rule>
    

  • Doctrine v8.1 introduces:
    • New DQL rules (e.g., JOIN clause formatting).
    • Stricter annotation validation (e.g., @ORM\ vs. @Column).

Sequencing (Updated)

1. Phase 1: Dry Run with Warnings
   • Run phpcs in warning mode to assess new rule impact.
2. Phase 2: Exclude Conflicting Rules
   • Disable Eloquent-conflicting rules (e.g., @ORM\ annotations).
3. Phase 3: CI Enforcement (Gradual)
   • Start with warnings, then fail builds after 2–4 weeks.
4. Phase 4: Automate Fixes
   • Use php-cs-fixer for automated DQL/annotation fixes.

Operational Impact

Maintenance (Updated)

• Pros (Updated):
  • Now depends on doctrine/coding-standard:^8.1, which is actively maintained.
  • Composer 2 support ensures long-term compatibility.
• Cons (Updated):
  • New rules may break existing code (e.g., legacy DQL syntax).
  • Custom exclusions may need frequent updates if Doctrine rules change.
• Mitigation (Updated):
  • Pin to a specific minor version (e.g., 8.1.x) to avoid surprises.
  • Document excluded rules in the team’s style guide.

Support (Updated)

• Debugging (Updated):
  • New rules may produce unclear errors (e.g., "DQL clause misalignment").
  • No official support → rely on Doctrine’s documentation or community.
• Onboarding (Updated):
  • New devs must understand Doctrine v8.1 rules (e.g., why WHERE clauses need exact spacing).
  • Documentation gap: