Mo4 Coding Standard Laravel Package

Technical Evaluation

Architecture Fit

• Strengths:

  • Laravel Alignment: MO4 extends Symfony’s coding standards, which are already well-aligned with Laravel’s ecosystem (e.g., PSR-12 compatibility, Symfony’s use statement conventions). This reduces friction for Laravel projects already using Symfony components or following PSR standards.
  • Opinionated but Flexible: The standard enforces best practices (e.g., array alignment, use statement sorting, variable interpolation) without being overly restrictive (e.g., optional docblocks, flexible license placement). This fits Laravel’s pragmatic approach to coding standards.
  • Auto-Fix Capabilities: Most rules support phpcbf (PHP Code Beautifier and Fixer), enabling seamless integration into CI/CD pipelines for automated enforcement.
  • Modern PHP Support: Requires PHP 8.1+, aligning with Laravel’s current LTS support (Laravel 10+).

• Gaps:

  • Laravel-Specific Rules: No Laravel-specific sniffs (e.g., Blade template conventions, Eloquent query formatting, or Facade usage). A TPM would need to supplement with custom rules or other standards (e.g., laravel-shift/coding-standard).
  • Symfony Overlap: Some Symfony-specific rules (e.g., Symfony.Components.AnnotationFormat) may not apply to Laravel projects, requiring customization via ruleset.xml.
  • No Blade Support: The standard focuses on PHP files only; Blade templates would need separate linting (e.g., nunomaduro/larastan or custom rules).

Integration Feasibility

• Low-Coupling: Installs as a Composer dev dependency, requiring no Laravel core modifications. Integrates via phpcs CLI or PHPStan.
• Toolchain Compatibility:
  • Works with PHP_CodeSniffer 4.0+ (required), PHPStan, and Psalm.
  • Can be integrated into Laravel Forge/Envoyer for deployment-time validation.
  • Supports Git hooks (pre-commit) or CI tools (GitHub Actions, GitLab CI) via phpcs/phpcbf.
• Configuration Override: Custom rulesets can extend or override MO4 via ruleset.xml, allowing team-specific adjustments.

Technical Risk

• Minimal:
  • Dependency Stability: Relies on mature tools (PHP_CodeSniffer, Symfony CS). No breaking changes in Laravel core expected.
  • Performance: Lightweight; runs in milliseconds for typical Laravel codebases (e.g., 10K LOC).
  • Backward Compatibility: PHP 8.1+ requirement may exclude legacy Laravel 8.x projects, but Laravel 9/10+ are unaffected.
• Mitigations:
  • Fallback: Use PSR12 or SquizLabs as a baseline if MO4’s rules are too opinionated.
  • Custom Rules: Extend MO4 with Laravel-specific sniffs via ruleset.xml or custom sniffs.

Key Questions for the TPM

1. Adoption Scope:
   • Should MO4 replace the current standard (e.g., PSR12) entirely, or supplement it for specific teams/modules?
   • Are there Laravel-specific conventions (e.g., Facade usage, Blade templates) that MO4 doesn’t cover?
2. Toolchain Integration:
   • How will this integrate with existing CI/CD pipelines (e.g., GitHub Actions, Laravel Pint)?
   • Should phpcbf run automatically in CI, or require manual fixes?
3. Customization Needs:
   • Are there existing custom rules (e.g., in-house sniffs) that conflict with MO4?
   • Should the team override specific rules (e.g., AlphabeticalUseStatements order) via ruleset.xml?
4. Performance:
   • Will the standard run acceptably fast for large codebases (e.g., 50K+ LOC)?
   • Should parallel execution (e.g., php-parallel-lint) be used for speed?
5. Blade Templates:
   • How will Blade files be linted? Options:
     • Ignore them (not recommended).
     • Use a separate tool (e.g., nunomaduro/larastan).
     • Create custom Blade sniffs.
6. Team Buy-In:
   • Has the team used Symfony’s coding standards before? If not, will MO4’s opinionated rules be too restrictive?
   • Should a phased rollout be planned (e.g., start with phpcbf in PRs, then enforce in CI)?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • PHP_CodeSniffer: Native support via Composer; no Laravel-specific plugins needed.
  • PHPStan/Psalm: Can integrate MO4 rules via phpstan/extension-installer or custom configs.
  • Laravel Pint: MO4’s auto-fixable rules could replace or supplement Pint for PHP linting.
  • IDE Support: Works with PHPStorm, VSCode (via extensions like "PHP_CodeSniffer"), and Laravel IDE Helper.
• Toolchain Synergy:
  • CI/CD: Run phpcs in parallel with tests (e.g., GitHub Actions matrix).
  • Git Hooks: Use pre-commit to run phpcbf locally (via husky or pre-commit framework).
  • Deployment: Enforce in Envoyer/Forge via phpcs in the after hook.

Migration Path

1. Pilot Phase:
   • Step 1: Add MO4 to a single module (e.g., a new feature) as a dev dependency.
   • Step 2: Configure phpcs in composer.json:

     "scripts": {
       "lint": "phpcs --standard=MO4 app/",
       "fix": "phpcbf --standard=MO4 app/"
     }
     

   • Step 3: Run composer require --dev mayflower/mo4-coding-standard and test locally.
2. Gradual Rollout:
   • Phase 1: Enforce in PRs (via CI) with --warning-severity=0.
   • Phase 2: Run phpcbf in CI to auto-fix issues.
   • Phase 3: Enforce in local dev (via Git hooks) and deployment.
3. Customization:
   • Create a custom ruleset.xml to:
     • Disable conflicting rules (e.g., Symfony-specific sniffs).
     • Override defaults (e.g., AlphabeticalUseStatements order).
     • Add Laravel-specific rules (e.g., Facade usage).

Compatibility

• Laravel Versions:
  • Supported: Laravel 9/10 (PHP 8.1+).
  • Legacy: Laravel 8.x may require PHP 8.0 compatibility mode (not officially supported).
• Existing Tools:
  • Conflicts: None with Laravel core, but may conflict with:
    • Custom phpcs configs (merge or override).
    • Other coding standards (e.g., PSR12, SquizLabs).
  • Synergy: Works alongside:
    • Pint: Use MO4 for linting, Pint for formatting (if rules overlap).
    • PHPStan: Extend PHPStan with MO4 rules via phpstan/extension-installer.
• Blade Templates:
  • Workaround: Exclude Blade files from phpcs or use a separate tool (e.g., nunomaduro/larastan).

Sequencing

1. Pre-Integration:
   • Audit current codebase for existing violations (run phpcs with --report=full).
   • Identify high-effort fixes (e.g., array alignment, use statement sorting).
2. Integration:
   • Add MO4 to composer.json and test locally.
   • Configure CI to run phpcs in parallel with tests.
3. Enforcement:
   • Start with --warning-severity=0 in CI.
   • Gradually increase severity to --warning-severity=5.
4. Optimization:
   • Customize ruleset.xml based on team feedback.
   • Add custom sniffs for Laravel-specific needs.

Operational Impact

Maintenance

• Pros:
  • Low Maintenance: MO4 is actively maintained (last release: 2026-03-15) with a clear roadmap.
  • Community Support: Backed by the Symfony ecosystem; issues are resolved promptly.
  • Auto-Fixable: Most rules support phpcbf, reducing manual effort.
• Cons:
  • Rule Updates: New PHP versions (e.g., PHP 9.0) may require MO4 updates.
  • Custom Rules: Any Laravel-specific extensions must be maintained in-house