Coder Laravel Package

Technical Evaluation

Architecture Fit

• Limited Laravel Fit: The drupal/coder package is Drupal-specific, leveraging PHP_CodeSniffer (PHPCS) to enforce Drupal coding standards (e.g., Drupal, DrupalPractice). Laravel follows PSR-12 and SquizLabs PHP_CodeSniffer standards by default, making this package non-native to Laravel’s ecosystem.
• PHPCS Integration: Since Laravel already uses PHPCS (via squizlabs/php_codesniffer), this package could be bolted on but would require custom configuration to avoid conflicts with Laravel’s existing standards.
• Opportunity for Hybrid Workflows: If a Laravel project includes Drupal modules (e.g., via Drupal as a service layer or headless Drupal), this package could enforce Drupal-specific standards in those modules while leaving Laravel core untouched.

Integration Feasibility

• Modular Integration: Possible to scope usage to specific directories (e.g., app/DrupalModules/), treating it as a niche tool rather than a global standard.
• PHPCS Compatibility: Since PHPCS is already a dependency in Laravel (via phpunit/phpunit or friendsofphp/php-cs-fixer), adding this package is low-risk in terms of toolchain compatibility.
• Configuration Overhead: Requires custom phpcs.xml.dist to avoid overriding Laravel’s PSR-12 rules. Example:

  <ruleset>
    <file>app/DrupalModules</file>
    <arg name="extensions" value="php,module,inc"/>
    <rule ref="Drupal"/>
    <rule ref="DrupalPractice"/>
    <!-- Exclude Laravel-specific rules -->
    <exclude name="PSR12"/>
  </ruleset>
  

Technical Risk

• Rule Conflicts: Drupal’s Drupal and DrupalPractice standards may clash with PSR-12 (e.g., namespace formatting, class naming). Requires explicit exclusion of conflicting rules.
• Maintenance Burden: Since this is Drupal-specific, long-term maintenance may fall on the Drupal team rather than Laravel’s ecosystem. Deprecation risk if Drupal evolves standards.
• Performance Impact: Running PHPCS on a large Laravel codebase could introduce CI/CD slowdowns if not scoped properly.

Key Questions

1. Why Drupal Standards in Laravel?
   • Is this for Drupal module development within Laravel (e.g., plugins, services)?
   • Or is there a strategic need to enforce Drupal conventions (e.g., legacy migration, hybrid apps)?
2. Scope of Enforcement
   • Should this apply to all PHP files or only specific directories (e.g., modules/Drupal)?
3. CI/CD Integration
   • How will failures be handled? (e.g., block merges, require manual fixes)
4. Toolchain Conflicts
   • Will this override existing PHPCS/PHP-CS-Fixer configurations, or run in parallel?
5. Long-Term Viability
   • Is the team committed to maintaining Drupal-specific rules in a Laravel codebase?

Integration Approach

Stack Fit

• PHPCS Dependency: Laravel already uses PHPCS (via phpunit/phpunit or php-cs-fixer), so adding drupal/coder is toolchain-compatible.
• IDE/Editor Support: Works with PhpStorm, VSCode, Vim, etc., via PHPCS plugins. No additional setup needed beyond standard PHPCS integration.
• Hybrid Workflows: Best suited for projects with mixed Laravel/Drupal codebases (e.g., Laravel as an API for Drupal, or Drupal modules embedded in Laravel).

Migration Path

1. Installation

   composer require --dev drupal/coder
   

2. Configuration
   • Create a scoped phpcs.xml.dist (e.g., phpcs-drupal.xml) targeting only Drupal-related files.
   • Example:

     <ruleset>
       <file>app/Modules/Drupal</file>
       <arg name="extensions" value="php,module,inc"/>
       <rule ref="Drupal"/>
       <rule ref="DrupalPractice">
         <exclude name="DrupalPractice.Functions.ValidDefaultValue.NotAtEnd"/>
       </rule>
     </ruleset>
     

3. CI/CD Integration
   • Add to .github/workflows/phpcs.yml:

     - name: Drupal Code Standards
       run: ./vendor/bin/phpcs -p --standard=Drupal --extensions=php app/Modules/Drupal
     

4. IDE Setup
   • Configure editors to use the custom ruleset (e.g., PhpStorm: Settings > PHP > Code Sniffer).

Compatibility

• PHPCS Version: Ensure compatibility with Laravel’s existing PHPCS version (e.g., ^3.7).
• Rule Exclusions: Must explicitly exclude PSR-12 rules to avoid conflicts (e.g., PSR12.Methods.CamelCapsMethodName vs. Drupal.Commenting.FunctionComment).
• File Extensions: Drupal’s standards target .module, .inc, etc.—irrelevant for Laravel core but useful for Drupal modules.

Sequencing

1. Phase 1: Pilot
   • Apply to one Drupal module in Laravel to test rule conflicts.
2. Phase 2: CI Gating
   • Fail builds on violations in Drupal-scoped directories only.
3. Phase 3: IDE Enforcement
   • Enable real-time checks in editors for Drupal files.
4. Phase 4: Auto-Fix
   • Use phpcbf (PHPCS fix) for safe, reversible fixes (e.g., docblock formatting).

Operational Impact

Maintenance

• Rule Updates: Drupal’s coding standards may change independently of Laravel’s PSR-12. Requires periodic syncing with upstream updates.
• Conflict Resolution: Need a process to handle rule clashes (e.g., documentation, team agreements on overrides).
• Dependency Bloat: Adding a Drupal-specific tool to a Laravel project may confuse new developers unfamiliar with Drupal conventions.

Support

• Onboarding: Developers must learn two coding standard systems (PSR-12 + Drupal). Requires clear documentation on when to apply each.
• Debugging: PHPCS errors may be less familiar to Laravel teams, increasing support overhead for coding standard violations.
• Tooling Support: Limited Laravel-specific documentation—relies on Drupal community resources.

Scaling

• Performance: Running PHPCS on large Drupal modules could slow CI/CD. Mitigate by:
  • Caching results (e.g., GitHub Actions cache).
  • Parallelizing checks (e.g., split by module).
• Team Adoption: Harder to scale if only some team members work on Drupal modules. Risk of inconsistent enforcement.
• Monorepo Challenges: In a Laravel + Drupal monorepo, must isolate PHPCS runs to avoid false positives/negatives.

Failure Modes

Ramp-Up

• Training
  • 1-hour workshop on Drupal coding standards vs. PSR-12.
  • Cheat sheet for common rule differences (e.g., Drupal.Commenting.ClassComment vs. PSR-12).
• Documentation
  • README section explaining:
    • Where Drupal standards apply.
    • How to disable rules temporarily.
    • Example phpcs.xml configurations.
• Gradual Rollout
  • Start with optional local checks before enforcing in CI.
  • Opt-in for teams working on Drupal modules.
• Tooling
  • VSCode/PhpStorm snippets for common Drupal patterns (e.g., hook implementations).
  • Pre-commit hooks (e.g., Husky) to catch issues early.