Coding Standard Laravel Package

Technical Evaluation

Architecture Fit

• Strengths:

  • Built on Slevomat Coding Standard, a battle-tested foundation for PHP linting, ensuring compatibility with modern PHP (7.2+) and Laravel ecosystems.
  • Strict but configurable ruleset, allowing alignment with Laravel’s PSR-12 baseline while enforcing additional best practices (e.g., strict typing, disallowed numeric literals).
  • Modular design: Supports project-specific overrides (e.g., excluding tests/tmp) and pre-configured rulesets (e.g., Contributte, Gamee).
  • IDE integration: Includes PHPStorm codestyle presets, reducing friction for developer onboarding.

• Potential Conflicts:

  • Overlap with Laravel’s defaults: Laravel’s built-in php-cs-fixer (PSR-12) may conflict with this package’s stricter rules (e.g., disallowed ternary operators, strict type declarations). Requires explicit alignment.
  • PHP version constraints: Minimum PHP 7.2 may exclude legacy Laravel 5.x projects (though Laravel 6+ is PHP 7.2+ compatible).

Integration Feasibility

• Laravel Compatibility:
  • High: Works seamlessly with Laravel’s Composer-based dependency system. Can be integrated into Laravel’s existing php-cs-fixer or phpmd workflows.
  • CI/CD Friendly: Lightweight (no runtime overhead) and ideal for pre-commit hooks (e.g., GitHub Actions, GitLab CI) or pre-push scripts.
• Toolchain Synergy:
  • Complements PHPStan, Psalm, or Pint for a unified static analysis pipeline.
  • Can replace or supplement Laravel’s default php-cs-fixer if stricter standards are desired.

Technical Risk

• Rule Collisions:
  • Risk: Conflicts with existing php-cs-fixer configs or custom sniffs. Mitigation: Audit current rulesets and merge selectively.
  • Example: This package disables ternary operators by default, which may break legacy Laravel codebases.
• Maintenance Burden:
  • Risk: Strict rules may require frequent updates to accommodate Laravel’s evolving patterns (e.g., new Blade syntax, dynamic properties).
  • Mitigation: Use exclude-pattern to isolate high-maintenance areas (e.g., vendor files, generated code).
• Dependency Stability:
  • Risk: Relies on slevomat/coding-standard (v7+), which may introduce breaking changes. Last update was 2022-02-11—monitor for forks or successors.
  • Mitigation: Pin to a specific version (e.g., ^0.12) and test upgrades annually.

Key Questions for TPM

1. Alignment with Team Standards:
   • Does the team prioritize strictness over flexibility? If so, this package is a strong fit.
   • Are there existing php-cs-fixer rules that conflict with this package’s defaults?
2. Onboarding Impact:
   • How will developers adapt to stricter rules (e.g., no ternary operators, strict types on first line)?
   • Is there a phased rollout plan (e.g., start with warnings, then enforce)?
3. CI/CD Integration:
   • Will this replace or augment existing linting steps? What’s the failure threshold (e.g., block merges on warnings vs. errors)?
4. Long-Term Viability:
   • Is the Contributte team actively maintaining this package? Are there plans for PHP 8.2+ support?
5. Performance:
   • How will this impact build times? Should it run in parallel with other static analyzers?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Native Composer Integration: Install via composer require --dev ninjify/coding-standard.
  • CI/CD Plugins: Works with Laravel Forge, Envoyer, or custom scripts (e.g., php ./vendor/bin/phpcs --standard=ruleset.xml).
  • IDE Support: PHPStorm presets reduce manual configuration (see phpstorm/ folder in the package).
• Toolchain Placement:
  • Option 1: Replace Laravel’s default php-cs-fixer (if stricter rules are desired).
  • Option 2: Run alongside php-cs-fixer for layered validation (e.g., php-cs-fixer for PSR-12, this package for additional checks).
  • Option 3: Integrate into phpmd or custom scripts for broader static analysis.

Migration Path

1. Assessment Phase:
   • Audit current codebase against the package’s rules using:

     composer require --dev ninjify/coding-standard
     php ./vendor/bin/phpcs --standard=./vendor/ninjify/coding-standard/ruleset.xml --report=full src/
     

   • Identify high-severity violations (e.g., ternary operators, missing strict types).
2. Pilot Phase:
   • Enable in a feature branch or non-critical module. Use exclude-pattern to isolate changes.
   • Example ruleset.xml:

     <ruleset name="Acme">
         <rule ref="./vendor/ninjify/coding-standard/ruleset.xml"/>
         <exclude-pattern>./vendor</exclude-pattern>
         <exclude-pattern>./tests/Feature/SlowTests.php</exclude-pattern>
     </ruleset>
     

3. Gradual Enforcement:
   • Start with warnings in CI, then transition to blocking failures.
   • Provide a FIXME comment template for developers to document intentional violations.
4. IDE Sync:
   • Distribute the PHPStorm codestyle preset to the team via .idea/codestyle/ or team-wide settings.

Compatibility

• Laravel-Specific Considerations:
  • Blade Templates: Exclude Blade files (.blade.php) unless custom sniffs are added.
  • Dynamic Properties: This package may flag Laravel’s dynamic properties (public function __get(string $name)) as non-compliant. Document exceptions.
  • Service Providers: Strict rules on register()/boot() methods may require adjustments (e.g., no ternary operators in dependency resolution).
• Dependency Conflicts:
  • Avoid conflicts with friendsofphp/php-cs-fixer by either:
    • Disabling overlapping rules in php-cs-fixer config.
    • Using this package as the sole standard.

Sequencing

1. Pre-merge: Run in CI to block violations (e.g., GitHub Actions).
2. Pre-commit: Use phpcs hooks (e.g., with roave/security-advisories or custom scripts).
3. Local Development: Integrate with IDEs (PHPStorm, VSCode with PHP Intelephense).
4. Onboarding: Add to composer.json dev requirements and document in CONTRIBUTING.md.

Operational Impact

Maintenance

• Pros:
  • Reduced Technical Debt: Strict rules prevent drift over time.
  • Consistent Codebase: Easier for new developers to onboard (uniform style).
• Cons:
  • Rule Updates: Requires periodic reviews to ensure compatibility with Laravel updates (e.g., new Blade syntax).
  • False Positives: May flag Laravel idioms as violations (e.g., dynamic properties, magic methods).

Support

• Developer Experience:
  • Pros: Clear error messages and IDE integration reduce friction.
  • Cons: Steep learning curve for teams unfamiliar with strict PHP standards.
• Support Channels:
  • Limited to Contributte’s Gitter or forum. Consider creating a project-specific issue tracker for Laravel integrations.
• Documentation:
  • Minimal but sufficient. Supplement with:
    • A CODE_STYLE.md in the repo explaining exceptions (e.g., "We allow ternary operators in Blade templates").
    • Example ruleset.xml configs for common Laravel use cases.

Scaling

• Performance:
  • Low Overhead: Runs during development/CI, not production.
  • Parallelization: Can be combined with other static analyzers (e.g., PHPStan) in CI pipelines.
• Large Codebases:
  • Use exclude-pattern to avoid scanning generated code (e.g., migrations, model casts).
  • Example:

    <exclude-pattern>./database/migrations/*</exclude-pattern>
    <exclude-pattern>./app/Models/Casts/*</exclude-pattern>
    

Failure Modes