Mo4 Coding Standard Laravel Package

Technical Evaluation

Architecture Fit

• Leverage for Laravel/PHP Projects: The mo4-coding-standard is a PHP_CodeSniffer (PHPCS) ruleset that extends the Symfony Coding Standard, making it highly compatible with Laravel projects (which are PHP-based and often use Symfony components). It enforces consistent coding style, reducing cognitive load for developers and improving maintainability.
• Rule Customization: The standard allows fine-grained configuration (e.g., AlphabeticalUseStatements sorting order), enabling alignment with existing team conventions or Laravel-specific best practices.
• Autofix Capabilities: Most violations can be auto-fixed via phpcbf, reducing manual refactoring effort.

Integration Feasibility

• Low Friction: Installation via Composer (composer require --dev mayflower/mo4-coding-standard) is straightforward and integrates seamlessly with Laravel’s existing tooling (e.g., PHPStan, Pest, or custom CI pipelines).
• Dependency Alignment: Requires PHP ≥8.1 and PHPCS ≥4.0, which aligns with modern Laravel (v10+) ecosystems. No Laravel-specific dependencies exist, ensuring no conflicts with existing packages.
• Rule Overrides: Existing Laravel projects using PSR-12 or Symfony standards can selectively adopt MO4 rules (e.g., array alignment, use statement sorting) without enforcing all rules globally.

Technical Risk

• Rule Conflicts: Some MO4 rules (e.g., MO4.WhiteSpace.MultipleEmptyLines) may conflict with Laravel’s Blade templates or legacy codebases. Risk mitigation:
  • Exclude directories (e.g., resources/views) via PHPCS configuration.
  • Custom ruleset.xml to override or disable conflicting rules.
• Performance Overhead: PHPCS runs are CPU-intensive. Risk mitigation:
  • Cache results in CI/CD (e.g., GitHub Actions artifacts).
  • Parallelize checks (PHPCS supports --parallel).
• False Positives: Rules like MO4.Strings.VariableInDoubleQuotedString may flag Blade syntax ({{ $var }}) as violations. Risk mitigation:
  • Exclude Blade files or adjust regex patterns in custom sniffs.

Key Questions for TPM

1. Adoption Scope:
   • Should MO4 replace PSR-12 entirely, or supplement it for PHP logic layers (e.g., app/, src/)?
   • How will Blade templates or legacy code be handled (exclusions, overrides)?
2. CI/CD Integration:
   • Will PHPCS run on every commit (strict) or nightly (lenient)?
   • Should failures block merges (e.g., GitHub PR checks)?
3. Developer Ramp-Up:
   • How will teams adapt to new rules (e.g., { $var } syntax, array alignment)?
   • Will autofix (phpcbf) be used preemptively or reactively?
4. Long-Term Maintenance:
   • Who will update the ruleset as PHP/Laravel evolve (e.g., PHP 8.3+ features)?
   • How will custom sniffs be managed if MO4 lacks a specific rule?

Integration Approach

Stack Fit

• PHP/Laravel Ecosystem: MO4 is native to PHP and integrates with:
  • PHPCS: Standard tool for static analysis.
  • Laravel Mix/Vite: Can be triggered via npm scripts or custom tasks.
  • CI Tools: GitHub Actions, GitLab CI, or CircleCI (via phpcs command).
• Toolchain Synergy:
  • Composer: Dependency management aligns with Laravel’s workflow.
  • PHPStan: MO4 can complement static analysis (e.g., catch style issues early).
  • Pest/PHPUnit: Integrate PHPCS into test suites (e.g., pest.php hooks).

Migration Path

1. Pilot Phase:
   • Select a module (e.g., app/Http/Controllers) and enforce MO4 there.
   • Use phpcs --diff to compare against baseline and measure impact.
2. Incremental Rollout:
   • Phase 1: Enforce AlphabeticalUseStatements, ArrayDoubleArrowAlignment (low friction).
   • Phase 2: Add VariableInDoubleQuotedString, PropertyComment (higher impact).
   • Phase 3: Adopt remaining rules (e.g., MultipleEmptyLines).
3. Autofix Strategy:
   • Run phpcbf in pre-commit hooks (e.g., Husky) or CI to auto-correct fixable issues.
   • Example:

     composer require --dev mayflower/mo4-coding-standard
     ./vendor/bin/phpcbf app/Http --standard=MO4
     

Compatibility

• Laravel-Specific Adjustments:
  • Exclude Blade files: Add to .phpcs.xml:

    <arg name="exclude" value="resources/views,storage"/></arg>
    

  • Override conflicting rules: Disable MO4.WhiteSpace.MultipleEmptyLines for Blade:

    <rule ref="MO4.WhiteSpace.MultipleEmptyLines">
        <properties>
            <property name="exclude" value="\.blade\.php$"/></property>
        </properties>
    </rule>
    

• Dependency Conflicts:
  • MO4 depends on Symfony CS, which may pull in older versions of PHPCS. Pin versions in composer.json:

    "config": {
        "allow-plugins": {
            "dealerdirect/phpcodesniffer-composer-installer": true
        }
    },
    "require-dev": {
        "phpcsstandards/phpcs": "^4.0",
        "mayflower/mo4-coding-standard": "^11.0"
    }
    

Sequencing

1. Setup:
   • Install MO4 and configure PHPCS (~/.phpcs.dist or project-specific .phpcs.xml).
   • Example .phpcs.xml:

     <?xml version="1.0"?>
     <ruleset>
         <config name="installed_paths" value="./vendor/mayflower/mo4-coding-standard"/>
         <config name="default_standard" value="MO4"/>
         <config name="encoding" value="utf-8"/>
         <file>app/</file>
     </ruleset>
     

2. Validation:
   • Run ./vendor/bin/phpcs --standard=MO4 --report=full app/ to baseline violations.
3. Autofix:
   • Apply phpcbf to resolvable issues before enforcement.
4. Enforcement:
   • Integrate into CI (e.g., GitHub Actions):

     - name: Run PHPCS
       run: ./vendor/bin/phpcs --standard=MO4 --warning-severity=3 app/
     

   • Add to pre-commit hooks (optional):

     # package.json
     "scripts": {
       "lint:php": "phpcs --standard=MO4 --report=emacs app/"
     }
     

Operational Impact

Maintenance

• Rule Updates:
  • MO4 is actively maintained (last release: 2026-03-15). Dependency updates (e.g., PHPCS, Symfony CS) may require re-testing.
  • Action: Subscribe to MO4’s release channel and test upgrades in a staging environment.
• Custom Rules:
  • If MO4 lacks a rule (e.g., Laravel-specific), extend PHPCS or use Slevomat’s sniffs (already included in MO4).
  • Example: Add a custom sniff for Illuminate\Support\Facades usage.

Support

• Developer Onboarding:
  • Documentation: Create a team wiki page with:
    • MO4 rules and their purpose (e.g., "Why { $var } in strings?").
    • Exclusion patterns for Blade/Legacy code.
  • Training: Run a lunch-and-learn on PHPCS and MO4’s benefits.
• Troubleshooting:
  • Common issues:
    • False positives: Adjust ruleset.xml or exclude files.
    • Performance: Cache results or run in CI only.
  • Escalation path: Engage MO4 maintainers via GitHub for rule-specific bugs.

Scaling

• Large Codebases:
  • Parallelize checks: Use PHPCS’s --parallel flag or split by directory.
  • Incremental adoption: Enforce MO4 per module (e.g., app/, src/) before full rollout.
• Distributed Teams:
  • CI gating: Block