Yoastcs Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev yoast/yoastcs:"^3.0"
   

   Ensure allow-plugins is configured in composer.json:

   {
     "config": {
       "allow-plugins": {
         "dealerdirect/phpcodesniffer-composer-installer": true
       }
     }
   }
   

2. First Run:

   • Parallel Lint (syntax checks):

     composer lint
     

     (Add this script to composer.json scripts section as shown in README.)

   • PHPCS (coding standards):

     vendor/bin/phpcs --standard=Yoast src/
     

3. Key Files:

   • .phpcs.xml.dist (default config, auto-generated by YoastCS)
   • composer.json (scripts for linting/threshold checks)

Implementation Patterns

Workflows

1. Daily Development:

   • Pre-commit Hook:

     # Add to .git/hooks/pre-commit
     #!/bin/sh
     vendor/bin/phpcs --standard=Yoast --report=full src/ || exit 1
     

   • CI Integration (GitHub Actions example):

     - name: Run PHPCS
       run: vendor/bin/phpcs --standard=Yoast --report=full src/ || exit 1
     

2. Threshold Enforcement:

   • Set thresholds in CI/CD (e.g., GitHub Actions):

     YOASTCS_THRESHOLD_ERRORS=5 YOASTCS_THRESHOLD_WARNINGS=20 vendor/bin/phpcs --standard=Yoast --report=YoastCS\Yoast\Reports\Threshold src/
     

   • Check thresholds locally:

     composer check-cs-thresholds
     

3. Custom Configurations:

   • Extend .phpcs.xml.dist:

     <config name="minimum_wp_version" value="6.8" /> <!-- Override default -->
     <rule ref="Yoast">
       <exclude name="Yoast.Arrays.ArrayAccess" /> <!-- Disable specific sniff -->
     </rule>
     

4. Parallel Lint in CI:

   • Cache results for faster runs:

     composer lint -- --cache=/tmp/parallel-lint-cache
     

Integration Tips

1. Laravel-Specific:

   • Exclude vendor/ and bootstrap/cache/ in PHPCS:

     <arg name="exclude" value="vendor,bootstrap/cache" />
     

   • Focus on app/, config/, and routes/:

     vendor/bin/phpcs --standard=Yoast app/ config/ routes/
     

2. PhpStorm Setup:

   • Go to Settings > Languages & Frameworks > PHP > Code Sniffer.
   • Set Standard: Yoast.
   • Enable On Save validation.

3. Custom Sniffs:

   • Add Yoast-specific sniffs to .phpcs.xml.dist:

     <rule ref="Yoast.Arrays.DisallowShortArraySyntax" />
     

Gotchas and Tips

Pitfalls

1. PHP Version Mismatches:

   • YoastCS defaults to PHP 7.4+ and WordPress 6.8+. If your project uses older versions:

     <config name="minimum_php_version" value="7.2" />
     <config name="minimum_wp_version" value="6.6" />
     

2. Threshold Report Quirks:

   • Environment Variables: Must be set before running PHPCS (e.g., in CI).
   • Exact Match: Use YOASTCS_THRESHOLD_EXACT_MATCH to detect if thresholds need updates:

     if (defined('YOASTCS_THRESHOLD_EXACT_MATCH') && !YOASTCS_THRESHOLD_EXACT_MATCH) {
         echo "Thresholds need adjustment!";
     }
     

3. SlevomatCodingStandard Issues:

   • If using versions < 8.17.0, update or exclude problematic sniffs:

     <exclude name="SlevomatCodingStandard.Arrays.ArrayAccess" />
     

4. Parallel Lint False Positives:

   • Exclude node_modules/ or other non-PHP files:

     composer lint -- --exclude=node_modules
     

Debugging

1. Verbose Output:

   • List all sniffs:

     vendor/bin/phpcs -e --standard=Yoast
     

   • Show sniff documentation:

     vendor/bin/phpcs --standard=Yoast --generator=Text
     

2. Fixers:

   • Auto-fix warnings (where possible):

     vendor/bin/phpcbf --standard=Yoast --report=full src/
     

3. CI Failures:

   • Check for YOASTCS_ABOVE_THRESHOLD in CI logs to debug threshold breaches.

Extension Points

1. Custom Rulesets:

   • Create a child ruleset in .phpcs.xml.dist:

     <ruleset>
       <rule ref="Yoast">
         <exclude name="Yoast.Arrays.DisallowShortArraySyntax" />
       </rule>
       <config name="minimum_wp_version" value="6.5" />
     </ruleset>
     

2. Plugin Integration:

   • Use phpcs --config-file=.phpcs.xml.dist to load project-specific configs.

3. Parallel Lint Optimization:

   • Adjust workers for large codebases:

     composer lint -- --workers=4