Yoastcs Laravel Package

Getting Started

Minimal Setup

1. Installation:

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

   Ensure allow-plugins is configured in your composer.json:

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

2. First Use Case: Run a basic PHPCS check on your project:

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

   • --standard=Yoast applies Yoast’s custom ruleset (WordPress + PHPCompatibilityWP + Slevomat + custom sniffs).
   • Exclude vendor/ and .git by default (configured in .phpcs.xml.dist).

3. Parallel Lint: Add to composer.json:

   "scripts": {
       "lint": [
           "@php ./vendor/php-parallel-lint/php-parallel-lint/parallel-lint . -e php --show-deprecated --exclude vendor --exclude .git"
       ]
   }
   

   Run with:

   composer lint
   

Implementation Patterns

Workflows

1. Pre-Commit Hooks: Integrate PHPCS into Git hooks (e.g., pre-commit) to block violations:

   vendor/bin/phpcs --standard=Yoast --report=full src/ || exit 1
   

   • Use --report=full for detailed output.
   • Combine with parallel-lint for faster feedback.

2. CI/CD Integration:

   • GitHub Actions:

     - name: Run PHPCS
       run: vendor/bin/phpcs --standard=Yoast --report=threshold src/
     

   • Threshold Checks: Set environment variables in CI:

     export YOASTCS_THRESHOLD_ERRORS=0
     export YOASTCS_THRESHOLD_WARNINGS=5
     

     Run with:

     vendor/bin/phpcs --standard=Yoast --report=YoastCS\Yoast\Reports\Threshold src/
     

     Exit with error if YOASTCS_ABOVE_THRESHOLD is true.

3. PhpStorm Integration:

   • Configure PHP Code Sniffer in Settings > Languages & Frameworks > PHP > Code Sniffer.
   • Set Standard: Yoast.
   • Enable On Save or On File Open validation.

4. Custom Rulesets: Extend .phpcs.xml.dist to override defaults:

   <rule ref="Yoast">
       <exclude name="WordPress.WP.CapitalPDangler"/>
       <arg name="minimum_wp_version" value="6.4"/>
   </rule>
   

Integration Tips

• Exclude Files: Use <exclude-pattern> in .phpcs.xml.dist to skip tests or legacy code:

  <exclude-pattern>*/tests/*</exclude-pattern>
  

• Parallel Lint Optimization: For large projects, split paths:

  parallel-lint src/ app/ --exclude vendor --jobs 4
  

• Threshold Reporting: Use YOASTCS_THRESHOLD_EXACT_MATCH in scripts to auto-update thresholds:

  if (defined('YOASTCS_THRESHOLD_EXACT_MATCH') && !YOASTCS_THRESHOLD_EXACT_MATCH) {
      echo "Update thresholds in CI config.";
  }
  

Gotchas and Tips

Pitfalls

1. PHP Version Mismatches:

   • YoastCS defaults to PHP 7.4 and WP 6.8. If your project targets older versions, explicitly set:

     <arg name="minimum_php_version" value="7.2"/>
     <arg name="minimum_wp_version" value="6.4"/>
     

   • PHPCompatibilityWP may fail if minimum-stability isn’t set to dev (for alpha packages).

2. SlevomatCodingStandard Errors:

   • Versions < 8.17.0 may throw Property "checkIfConditions" does not exist. Update or pin:

     "yoast/yoastcs": "^3.4.1"
     

3. False Positives:

   • WordPress.WP.GetMetaSingle: May flag get_post_meta() calls. Exclude or suppress:

     <exclude name="WordPress.WP.GetMetaSingle"/>
     

   • VariableAnalysis: Overly strict about unused variables. Adjust in .phpcs.xml.dist:

     <rule ref="VariableAnalysis">
         <exclude name="VariableAnalysis.UnusedVariable.UnusedVariable"/>
     

4. Threshold Report Quirks:

   • Backslashes in --report=YoastCS\Yoast\Reports\Threshold may need escaping on Windows:

     vendor/bin/phpcs --report="YoastCS\\Yoast\\Reports\\Threshold"
     

   • CI Timeouts: Threshold checks can be slow for large codebases. Cache results or run in parallel.

Debugging

• List All Sniffs:

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

• Inspect a Specific Sniff:

  vendor/bin/phpcs --standard=Yoast --generator=Text | grep "WordPress.WP"
  

• Dry Run: Use --dry-run to test PHPCS without fixing:

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

Extension Points

1. Custom Sniffs: Add to .phpcs.xml.dist:

   <rule ref="Yoast">
       <file>app/Path/To/CustomSniff.php</file>
   </rule>
   

   Ensure the sniff follows PHPCS standards.

2. Override Rules: Disable or modify sniffs globally:

   <rule ref="Yoast">
       <exclude name="SlevomatCodingStandard.ControlStructures.RequireNullCoalesceOperator"/>
       <arg name="line_ending" value="LF"/>
   </rule>
   

3. Parallel Lint Customization: Extend the composer.json script for project-specific paths:

   "lint": [
       "@php ./vendor/php-parallel-lint/php-parallel-lint/parallel-lint src/ app/ --exclude tests/ --jobs 8"
   ]
   

Pro Tips

• Auto-Fix: Use --fix for auto-correctable issues (e.g., whitespace, trailing commas):

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

• Selective Checks: Target specific files/directories:

  vendor/bin/phpcs --standard=Yoast app/Models/
  

• Performance: Cache PHPCS results in CI using phpcs --cache (requires phpcs-cache extension).
• IDE Shortcuts: Bind PhpStorm’s Reformat Code to PHPCS for consistent formatting:

  <!-- .phpstorm.meta.php -->
  <option name="phpCodeSnifferSettings">
      <option name="standard" value="Yoast"/>
      <option name="onSave" value="true"/>
  </option>