Yoastcs Laravel Package

Technical Evaluation

Architecture Fit

• Laravel Alignment: YoastCS is primarily designed for WordPress projects but leverages PHP_CodeSniffer (PHPCS) and PHP Parallel Lint, which are language-agnostic tools. Laravel’s PHP-based ecosystem makes it highly compatible with these standards, especially for:
  • Code quality enforcement (e.g., PSR-12, WordPress-specific rules).
  • Static analysis (e.g., PHP version compatibility, deprecated functions).
  • CI/CD integration (e.g., blocking merges on violations).
• Key Synergies:
  • Laravel’s PSR-12 compliance aligns with YoastCS’s WordPressCS + SlevomatCodingStandard rules.
  • PHPCompatibilityWP ensures Laravel apps targeting WordPress (e.g., plugins, themes) avoid PHP/WordPress version mismatches.
  • Parallel Lint accelerates linting for large Laravel monorepos or multi-package projects.

Integration Feasibility

• Low-Coupling: YoastCS is a standalone PHPCS ruleset—no Laravel-specific dependencies. Integration requires:
  1. Adding yoast/yoastcs as a dev dependency (composer require --dev yoast/yoastcs).
  2. Configuring PHPCS to use the Yoast standard (via .phpcs.xml or CLI).
• Toolchain Compatibility:
  • Works with Laravel Forge/Sail, Dockerized PHP, and CI tools (GitHub Actions, GitLab CI).
  • Supports PhpStorm/IDE integration via PHPCS plugins.
• Customization:
  • Override Yoast’s ruleset by extending .phpcs.xml (e.g., relax SlevomatCodingStandard.Arrays.ArrayAccess for legacy code).
  • Disable WordPress-specific sniffs (e.g., WordPress.WP.GetMetaSingle) if irrelevant.

Technical Risk

Key Questions for TPM

1. Scope of Adoption:
   • Will this apply to all Laravel packages or only WordPress-integrated ones?
   • Should we override Yoast’s ruleset (e.g., relax SlevomatCodingStandard) or adopt it fully?
2. CI/CD Strategy:
   • Should errors block merges, or only warnings (configurable via YOASTCS_THRESHOLD_ERRORS)?
   • How will we handle false positives (e.g., legacy Laravel code)?
3. Toolchain Integration:
   • Should we replace existing PHPCS rules (e.g., squizlabs/php_codesniffer) or add YoastCS as a parallel standard?
   • Will we use Parallel Lint in CI, or is Laravel’s php -l sufficient?
4. Developer Experience:
   • Should we pre-configure PhpStorm/VSCode with YoastCS sniffs?
   • Will we document exceptions for Laravel-specific patterns (e.g., Facade usage)?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • PHPCS: Native support via phpcs CLI (included in Laravel’s php binary).
  • Parallel Lint: Complements Laravel’s artisan test workflow (parallel execution for large codebases).
  • Composer Scripts: Aligns with Laravel’s composer.json hooks (e.g., post-autoload-dump).
• Tooling Synergy:
  • GitHub Actions: Use yoast/yoastcs in a phpcs step alongside Laravel’s pest/phpunit.
  • Laravel Valet: Add yoastcs to Valet’s PHP extensions (if needed for local linting).
  • Docker: Include yoast/yoastcs in Laravel Docker images for CI-local parity.

Migration Path

Compatibility

• Laravel-Specific Considerations:
  • Blade Templates: Exclude from PHPCS scans (add <exclude> to .phpcs.xml).
  • Facades/Helpers: YoastCS’s NoFQNTrueFalseNull may conflict; override or document exceptions.
  • PHP 8.2+ Features: YoastCS’s PHPCompatibilityWP ensures backward compatibility with WordPress.
• Dependency Conflicts:
  • PHPCS Version: YoastCS requires PHPCS ^3.12.0; Laravel’s default may lag. Pin in composer.json:

    "config": {
      "allow-plugins": { "dealerdirect/phpcodesniffer-composer-installer": true }
    },
    "require-dev": {
      "yoast/yoastcs": "^3.0",
      "phpcs/phpcs": "^3.12.0"
    }
    

  • SlevomatCodingStandard: Requires ^8.15.0; ensure Laravel’s rector/pint don’t conflict.

Sequencing

1. Pre-Integration:
   • Run YoastCS against a sample Laravel repo (e.g., Laravel Breeze) to validate false positives.
   • Document known exceptions (e.g., Laravel’s app() helper).
2. CI Integration:
   • Add composer check-cs-warnings to pull request checks before merging.
   • Use check-cs-thresholds for release branches.
3. Developer Onboarding:
   • Add YoastCS to IDE plugins (PhpStorm/VSCode).
   • Create a .phpcs.xml.dist template for new Laravel packages.
4. Post-Launch:
   • Monitor false positives and adjust rulesets.
   • Explore Parallel Lint for large monorepos (e.g., Laravel + Jetstream).

Operational Impact

Maintenance

• Rule Updates:
  • YoastCS releases quarterly; Laravel teams must pin versions in composer.json to avoid breaking changes.
  • Upgrade Path: Test new YoastCS versions against Laravel’s minimum PHP version (e.g., PHP 8.1).
• Custom Rules:
  • Extend YoastCS via .phpcs.xml or custom sniffs for Laravel-specific patterns (e.g., Illuminate\Container usage).
  • Example override:

    <config name="exclude_files" value=".*/vendor/.*|.*/resources/views/.*"/>
    <rule ref="Yoast">
      <exclude name="WordPress.WP.GetMetaSingle"/>
    </rule>
    

• Dependency Management:
  • Monitor PHPCSUtils, SlevomatCodingStandard, and PHPCompatibilityWP for breaking changes.

Support

• Developer Training:
  • Onboarding: Add YoastCS to Laravel’s contribution guidelines (e.g., "Fix PHPCS errors before PRs").
  • **Document