Coding Standard Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: The respect/coding-standard package enforces Respect’s PHP coding conventions via PHP_CodeSniffer, aligning with developer consistency and maintainability goals in Laravel projects. It is not a core architectural component but enhances code quality and team productivity, which is critical for TPMs managing Laravel-based products.
• Non-Functional Fit: As a static analysis tool, it does not impact runtime performance, database interactions, or HTTP layers. However, it enforces consistency in codebases with multiple contributors, reducing technical debt and onboarding friction.
• Opportunity vs. Risk:
  • Opportunity: High potential for standardizing legacy Laravel codebases or aligning with Respect’s ecosystem (e.g., if using respect/validation or respect/http). The opportunity score (32.88) suggests significant value for teams prioritizing strict coding standards.
  • Risk: Low adoption (0 dependents) and niche focus (Respect-specific) may limit immediate value unless the team already uses Respect libraries. Risk is mitigated by its lightweight, MIT-licensed nature and compatibility with Laravel’s tooling.

Integration Feasibility

• Leverage Points:
  • CI/CD Integration: Seamlessly embeds into PHP_CodeSniffer pipelines (e.g., GitHub Actions, GitLab CI) to enforce standards pre-merge.
  • IDE/Editor Plugins: Works with PHPStorm, VSCode (PHP Intelephense), or PSR-12 plugins for real-time feedback.
  • Custom Rule Extension: Can be combined with Laravel’s built-in rules (e.g., laravel-shift/php-pact) or PSR-12 for hybrid standards.
• Dependencies:
  • Requires PHP_CodeSniffer (squizlabs/php_codesniffer:^4.0), which is not bundled with Laravel by default. Adds ~5MB to tooling footprint.
  • Doctrine Coding Standard (doctrine/coding-standard:^14.0) is a dependency, which may introduce conflicting rules if not managed.
• Conflicts:
  • Laravel’s default PSR-12 or PHPStan rules may clash with Respect’s stricter conventions (e.g., naming, docblock formats).
  • No Laravel-specific optimizations: Unlike laravel-pint or laravel-shift, this package doesn’t account for Laravel’s artisan commands, facade patterns, or blade templates.

Technical Risk

Key Questions for TPM

1. Strategic Fit:
   • Does the team already use Respect libraries (e.g., respect/validation, respect/http)? If not, is there a long-term plan to adopt them?
   • Would this replace or complement existing standards (e.g., PSR-12, PHPStan, Laravel Pint)?
2. Adoption Barriers:
   • How would developers react to stricter rules (e.g., Respect’s SnakeCase for methods vs. Laravel’s camelCase)?
   • Is the team open to tooling-driven enforcement (e.g., CI blocks) or prefer self-enforcement?
3. Integration Depth:
   • Should this be mandatory (block PRs) or optional (linter warnings)?
   • Would a custom hybrid standard (Respect + Laravel/PSR-12 rules) be more practical?
4. Long-Term Cost:
   • How often does the Respect team update rules? Would this require ongoing maintenance?
   • Are there alternatives (e.g., dealerdirect/phpcodesniffer-composer-installer, laravel-shift/php-pact) with lower friction or better Laravel integration?
5. Blade and Artisan Support:
   • How critical is linting Blade templates and Artisan commands? If not critical, should these be excluded?
6. Performance Impact:
   • For large codebases (e.g., monorepos with plugins), would the linting overhead be acceptable in CI/CD?

Integration Approach

Stack Fit

• Compatibility:
  • PHP 8.1+: Aligns with Laravel’s LTS support (Laravel 10+).
  • Composer-Based: Integrates seamlessly with Laravel’s dependency management.
  • Tool-Agnostic: Works with any PHP_CodeSniffer-compatible toolchain (e.g., phpcs, parallel-lint, or custom scripts).
• Laravel-Specific Considerations:
  • Blade Templates: PHP_CodeSniffer does not lint Blade files by default. Requires custom rules or exclusion.
  • Artisan/Console: Respect’s rules may flag Laravel’s command-line conventions (e.g., handle() vs. execute()).
  • Facade Patterns: Respect may enforce PSR-4 autoloading strictly, conflicting with Laravel’s app() helper usage.
  • Service Providers: Rules like ValidClassName may conflict with Laravel’s AppServiceProvider naming.
• Hybrid Standards:
  • Can be merged with PSR-12 or Laravel Pint for a balanced approach:

    <ruleset>
        <rule ref="PSR12"/>
        <rule ref="Respect">
            <exclude name="Respect.NamingConventions.ValidClassName"/>
        </rule>
    </ruleset>
    

Migration Path

1. Pilot Phase (1-2 Weeks):
   • Install in a dev container or CI-only environment:

     composer require --dev respect/coding-standard
     vendor/bin/phpcs --standard=Respect --ignore=*,*.blade.php src/ tests/
     

   • Test against a small codebase subset (e.g., a single module or service).
   • Document initial violations and prioritize fixes.
2. Rule Customization (2-3 Weeks):
   • Extend .phpcs.xml to override conflicting rules:

     <ruleset>
         <rule ref="Respect">
             <exclude name="Respect.NamingConventions.SnakeCaseMethods"/>
             <exclude-pattern>*/AppServiceProvider.php</exclude-pattern>
             <exclude-pattern>*/Console/*Command.php</exclude-pattern>
         </rule>
     </ruleset>
     

   • Merge with existing PSR-12/Laravel Pint rules if applicable.
3. CI/CD Integration (3-4 Weeks):
   • Add to GitHub Actions or GitLab CI as a warning:

     - name: Run Respect Coding Standard (Warning)
       run: vendor/bin/phpcs --standard=Respect --warning-severity=0 src/ || true
     

   • Gradually transition to blocking after developer feedback.
4. Developer Onboarding (Ongoing):
   • Document allowed exceptions (e.g., Blade files, legacy code).
   • Provide a pre-commit hook (e.g., via husky or roave/infection):

     # .husky/pre-commit
     #!/bin/sh
     vendor/bin/phpcs --standard=Respect --report=summary src/ || exit 1
     

   • Offer pair programming sessions to address common violations.

Compatibility Matrix