Yoastcs Laravel Package

Technical Evaluation

Architecture Fit

• Strengths:

  • Laravel/WordPress Hybrid Fit: While Laravel is primarily a PHP framework, YoastCS is designed for WordPress projects but includes PHPCompatibilityWP and SlevomatCodingStandard, which are framework-agnostic. This makes it adaptable for Laravel projects with WordPress integrations (e.g., plugins, themes, or custom Laravel-WP bridges).
  • Modular Sniffs: The package aggregates multiple standards (WordPress, Slevomat, PHPCS, etc.), allowing selective adoption. A Laravel TPM could cherry-pick sniffs (e.g., SlevomatCodingStandard for modern PHP practices) while ignoring WordPress-specific rules.
  • Threshold Reporting: The custom Threshold report enables CI/CD integration for enforcing coding standards, aligning with Laravel’s emphasis on automated quality gates.

• Gaps:

  • Laravel-Specific Sniffs Missing: No native Laravel-specific rules (e.g., Eloquent, Blade templating, or Laravel conventions like snake_case migrations). Would require custom sniffs or exclusion of conflicting WordPress rules.
  • PHP Version Lock-in: Defaults to PHP 7.4+ and WP 6.8+, which may conflict with legacy Laravel projects (e.g., LTS versions like 5.8 on PHP 7.2). Requires explicit configuration overrides.

Integration Feasibility

• Composer Integration: Seamless via composer require --dev yoast/yoastcs. The phpcs binary is auto-installed, reducing setup friction.
• CI/CD Readiness: Supports GitHub Actions, GitLab CI, or Jenkins via composer check-cs-warnings and check-cs-thresholds scripts. Can be gated as a pre-merge requirement.
• IDE Support: Works with PhpStorm (via Code Sniffer plugin) and likely VSCode (via extensions like "PHP Intelephense" or "PHP CS Fixer").

Technical Risk

• Dependency Conflicts:
  • PHPCompatibilityWP 3.0.0-alpha: Requires "minimum-stability": "dev" in composer.json, which may break builds if not explicitly configured. Risk: Medium (mitigated by pinning versions).
  • SlevomatCodingStandard 8.17.0+: Some sniffs (e.g., checkIfConditions) may fail on older versions. Risk: Low if using LTS releases.
• Performance:
  • Parallel Lint: Optimized for speed but may still slow down CI pipelines for large codebases. Risk: Low (configurable via --exclude).
  • PHPCS Memory Usage: Heavy sniffs (e.g., VariableAnalysis) could cause timeouts. Risk: Medium (mitigate with --parallel flag).
• False Positives/Negatives:
  • WordPress-specific sniffs (e.g., WordPress.WP.GetMetaSingle) may flag Laravel code as violations. Risk: High (requires custom .phpcs.xml exclusions).

Key Questions for the TPM

1. Framework Alignment:
   • Does the project use WordPress integrations (e.g., REST APIs, plugins)? If not, how will WordPress-specific sniffs be excluded?
   • Are there Laravel-specific coding standards (e.g., Taylor Otwell’s conventions) that should override YoastCS rules?
2. CI/CD Strategy:
   • Should thresholds be strict (block merges on warnings) or lenient (warn-only)? How will YOASTCS_THRESHOLD_ERRORS/WARNINGS be set?
   • Will this replace existing tools (e.g., phpstan, psalm, or pint) or run in parallel?
3. Developer Experience:
   • Should the team adopt pre-commit hooks (e.g., via husky) to run PHPCS locally?
   • How will custom sniffs be added/removed (e.g., for Laravel-specific rules)?
4. Maintenance:
   • Who will update YoastCS (e.g., when PHP 8.5 support is added) and handle breaking changes (e.g., PHPCompatibilityWP alpha dependencies)?
   • Should the project fork YoastCS to remove WordPress-specific rules?

Integration Approach

Stack Fit

• Laravel Core Compatibility:
  • Pros: Works with any Laravel version (5.8+) on PHP 7.4+. Modern Laravel (10+) projects will benefit from sniffs like RequireNullCoalesceOperator.
  • Cons: WordPress sniffs (e.g., WordPress.WP.GetMetaSingle) are irrelevant and should be disabled via .phpcs.xml:

    <rule ref="WordPress.WP.GetMetaSingle">0</rule>
    

• Toolchain Synergy:
  • PHPCS + PHP Parallel Lint: Complements Laravel’s pint (for formatting) and phpstan (for static analysis). Can be chained in CI:

    # Example GitHub Actions step
    - name: Run PHPCS
      run: composer check-cs-warnings
    - name: Run PHPStan
      run: composer test:phpstan
    

  • IDE Integration: PhpStorm’s built-in PHPCS support reduces context-switching for developers.

Migration Path

1. Phase 1: Assessment
   • Run PHPCS against the codebase to identify violations:

     vendor/bin/phpcs --standard=Yoast --report=full src/ tests/
     

   • Action: Document common violations (e.g., "Laravel uses snake_case but Yoast enforces camelCase for variables").
2. Phase 2: Configuration
   • Create a custom .phpcs.xml to:
     • Disable WordPress sniffs.
     • Adjust severity (e.g., downgrade SlevomatCodingStandard warnings to info).
     • Example:

       <config name="installed_paths" value="./vendor/yoast/yoastcs"/>
       <rule ref="SlevomatCodingStandard.Arrays.ArrayAccess">1</rule>
       <rule ref="WordPress">0</rule> <!-- Disable all WordPress sniffs -->
       

3. Phase 3: CI/CD Integration
   • Add to composer.json:

     "scripts": {
       "check-cs": "phpcs --standard=Yoast --report=threshold src/ tests/",
       "check-cs-thresholds": "phpcs --standard=Yoast --report=YoastCS\\Yoast\\Reports\\Threshold src/ tests/"
     }
     

   • Configure CI to fail on YOASTCS_ABOVE_THRESHOLD=true.
4. Phase 4: Developer Onboarding
   • Add pre-commit hooks (optional):

     composer require --dev laravel/pint
     composer require --dev dealerdirect/phpcodesniffer-composer-installer
     

   • Document exceptions (e.g., "Use @phpcs:disable for legacy code").

Compatibility

• Laravel-Specific Conflicts:
  • Blade Templates: PHPCS may misinterpret Blade syntax. Exclude resources/views/:

    phpcs --standard=Yoast --ignore=resources/views/
    

  • Artisan Commands: Use @codeCoverageIgnore or exclude app/Console/ if sniffs conflict.
• Dependency Conflicts:
  • PHPCompatibilityWP Alpha: Pin to a stable version (e.g., 2.1.6) in composer.json:

    "extra": {
      "yoastcs-phpcompatibilitywp": "2.1.6"
    }
    

  • PHPCS Version: Ensure phpcs is updated (^3.12.0) to avoid runtime errors.

Sequencing

1. Start with a Subset: Begin with SlevomatCodingStandard and PHPCSExtra (framework-agnostic).
2. Iterative Enforcement:
   • Week 1: Fix error-level issues (blocked in CI).
   • Week 2: Address warning-level issues (threshold-based).
3. Parallelize with Other Tools:
   • Run PHPCS after pint (formatting) but before phpstan (static analysis) in CI.

Operational Impact

Maintenance

• Dependency Updates:
  • Frequency: YoastCS releases ~quarterly. Monitor for breaking changes (e.g., PHPCompatibilityWP alpha dependencies).
  • Process: Use composer why-not yoast/yoastcs to test updates before merging.
• Custom Rules:
  • Lifetime: Custom sniffs (e.g., for Laravel) must be maintained alongside YoastCS updates.
  • Tooling: Use phpcs --generate=xml to diff rule sets across versions.

Support

• Developer Onboarding:
  • Training: