Coding Standard Laravel Package

Technical Evaluation

Architecture Fit

• Laravel Synergy: The package’s rulesets (PHP_CodeSniffer/PHPMD) align with Laravel’s PHP-centric architecture, enabling consistent code quality enforcement across controllers, models, and service layers. It complements Laravel’s built-in conventions (e.g., app/Providers/) while allowing custom overrides for framework-specific patterns.
• Tooling Stack Compatibility: Integrates seamlessly with Laravel’s dependency injection, artisan commands, and CI/CD pipelines (e.g., GitHub Actions). The package’s XML-based rulesets are extensible for Laravel-specific needs (e.g., excluding routes/web.php from certain checks).
• Opportunity for Standardization: Addresses fragmented coding styles in Laravel teams by providing a pre-configured, opinionated standard, reducing technical debt and onboarding friction. The phpcq/phpcq wrapper further simplifies adoption.

Integration Feasibility

• Low-Coupling Design: The package does not modify Laravel core files; it operates as a standalone static analysis layer. This minimizes risk of conflicts with Laravel updates.
• Configuration Flexibility:
  • Supports granular exclusions (e.g., vendor/, bootstrap/cache/) via XML rulesets.
  • Can coexist with Laravel’s pint (formatter) and Rector (refactoring) by focusing on static analysis rather than code transformation.
• Dependency Risks:
  • Requires PHP_CodeSniffer (phpcs) and PHPMD as prerequisites. If these are missing, the integration path is blocked until they’re added to devDependencies.
  • Mitigation: Use Composer scripts to auto-install dependencies:

    "scripts": {
      "cs-fix": "vendor/bin/phpcs --standard=PhpCodeQuality --report=emacs src/"
    }
    

Technical Risk

Key Questions

1. Does the team already enforce PSR-12 or custom rules? If yes, how does PhpCodeQuality compare?
2. Are phpcs and phpmd already in the stack? If not, what’s the effort to add them?
3. How will this interact with Laravel’s pint or rector? Avoid duplication of formatting/refactoring tools.
4. What’s the CI/CD pipeline’s tolerance for build failures? Gradual enforcement may be needed.
5. Are there Laravel-specific files/directories to exclude? (e.g., routes/, app/Providers/).
6. Will developers need IDE support? (e.g., PHPStorm plugins for phpcs).

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • PHP_CodeSniffer: Already used in Laravel for static analysis (e.g., php artisan make:controller conventions).
  • PHPMD: Detects code smells (e.g., unused methods, long classes) that are critical in Laravel’s service-layer-heavy architecture.
  • Complementary Tools:
    • pint: Handles formatting (leave phpcs for style rules).
    • rector: Handles refactoring (leave phpmd for static analysis).
• CI/CD Synergy:
  • Integrates with GitHub Actions, GitLab CI, and Travis CI via Composer scripts.
  • Can fail builds on violations, enforcing consistency early.

Migration Path

1. Phase 1: Audit Existing Codebase

   • Run phpcs and phpmd with default rules to identify violations.
   • Compare output with current PSR-12/PSR-2 compliance.
   • Example command:

     vendor/bin/phpcs --standard=PhpCodeQuality src/ --report=full > phpcs-report.txt
     

2. Phase 2: Configure Integration

   • Option A: Standalone phpcs/phpmd Add to composer.json:

     "scripts": {
       "cs-check": "phpcs --standard=vendor/phpcq/coding-standard/phpcs/PhpCodeQuality/ruleset.xml src/",
       "pmd-check": "phpmd src/ text vendor/phpcq/coding-standard/phpmd/ruleset.xml"
     }
     

   • Option B: phpcq/phpcq Wrapper Configure build.default.properties:

     phpcs.standard=${basedir}/vendor/phpcq/coding-standard/phpcs/PhpCodeQuality/ruleset.xml
     phpmd.ruleset=${basedir}/vendor/phpcq/coding-standard/phpmd/ruleset.xml
     

     Run via:

     vendor/bin/phpcq check
     

3. Phase 3: Incremental Enforcement

   • Start with CI checks (non-blocking):

     # .github/workflows/phpcq.yml
     - name: PHPCQ Check
       run: composer cs-check
     

   • Gradually introduce pre-commit hooks (e.g., via husky):

     // package.json
     "husky": {
       "hooks": {
         "pre-commit": "composer cs-check"
       }
     }
     

4. Phase 4: Customization

   • Override rules in a local phpcs.ruleset.xml:

     <rule ref="PhpCodeQuality">
       <exclude name="App\Providers" />
       <exclude name="routes" />
     </rule>
     

   • Add Laravel-specific rules (e.g., enforce use App\Models\ imports).

Compatibility

• Laravel Versions: Works with PHP 7.4+ (Laravel 8+). Test with your version.
• IDE Support:
  • PHPStorm: Use the PHP_CodeSniffer plugin to highlight violations in real-time.
  • VSCode: Extensions like PHP Intelephense + PHP CS Fixer.
• CI/CD Plugins:
  • GitHub Actions:

    - name: Run PHPCQ
      run: composer cs-check
    

  • GitLab CI:

    test:phpcq:
      script: composer cs-check
    

Sequencing

1. Short-Term (1 Sprint):
   • Set up CI checks (non-blocking).
   • Document common violations for the team.
2. Medium-Term (2-3 Sprints):
   • Enforce pre-commit hooks (fail fast).
   • Customize rules for Laravel-specific patterns.
3. Long-Term:
   • Integrate with automated fixes (e.g., php-cs-fixer).
   • Extend to third-party packages (if applicable).

Operational Impact

Maintenance

• Rule Updates:
  • Monitor phpcq/coding-standard for new rule additions.
  • Fork the repo if heavy customization is needed (e.g., Laravel-specific rules).
• Dependency Management:
  • Pin versions in composer.json:

    "require-dev": {
      "phpcq/coding-standard": "^1.0",
      "squizlabs/php_codesniffer": "^3.7",
      "phpmd/phpmd": "^2.11"
    }
    

• Documentation:
  • Maintain a CODE_QUALITY.md with:
    • How to run checks locally.
    • Excluded files/directories.
    • Custom rule overrides.

Support

• Developer Onboarding:
  • Add a quick-start guide:

    ## Code Quality
    - Run `composer cs-check` to validate changes.
    - Fix issues with `composer cs-fix`.
    - Exclude files via `phpcs.ruleset.xml`.
    

  • Common Issues:
    • Laravel’s app/Providers/ may trigger false positives.
    • Dynamic properties (#[\AllowDynamicProperties]) may need exclusions.
• Troubleshooting:
  • Cache phpcs results to