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 (PHP 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:

   composer lint
   

3. First Run (PHP_CodeSniffer): Run basic check:

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

   View all sniffs:

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

Implementation Patterns

Daily Workflow

1. Pre-Commit Hooks: Integrate with pre-commit (e.g., Git Hooks or Husky) to run:

   composer lint && vendor/bin/phpcs --standard=Yoast --report=full src/
   

2. CI/CD Integration: Use composer check-cs-warnings (if using Yoast repo template) or:

   # Example GitHub Actions
   - name: Run PHPCS
     run: vendor/bin/phpcs --standard=Yoast --warning-severity=1 src/ || exit 0
   

3. Threshold-Based Checks: Set thresholds in CI:

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

   Check result in script:

   if (defined('YOASTCS_ABOVE_THRESHOLD') && YOASTCS_ABOVE_THRESHOLD) {
       exit(1); // Fail build
   }
   

4. PhpStorm Integration:

   • Configure PHP Code Sniffer inspection:
     • Standard: Yoast
     • Severity: Warning for warnings, Error for errors.
   • Use Reformat Code (Ctrl+Alt+Shift+T) to auto-fix Slevomat sniffs.

Advanced Patterns

1. Custom Sniff Exclusions: Extend .phpcs.xml.dist:

   <rule ref="Yoast">
       <exclude name="SlevomatCodingStandard.Functions.DisallowTrailingCommaInCall"/>
   </rule>
   

2. Parallel Lint for Large Codebases: Optimize for speed:

   composer lint -- --jobs=8  # 8 parallel processes
   

3. Dynamic Thresholds: Use environment variables in CI:

   YOASTCS_THRESHOLD_ERRORS=$(git diff --name-only | wc -l) vendor/bin/phpcs --report=YoastCS\Yoast\Reports\Threshold src/
   

4. Custom Reports: Generate a custom report for PRs:

   vendor/bin/phpcs --standard=Yoast --report=json src/ > phpcs-report.json
   

Gotchas and Tips

Common Pitfalls

1. PHP Version Mismatches:

   • Ensure minimum-stability in composer.json is set to dev or alpha if using PHPCompatibilityWP ^3.0.0@alpha.
   • Default PHP version check is now 7.4 (up from 7.2 in v3.2.0).

2. WordPress Version Sniffs:

   • minimum_wp_version defaults to 6.8 (v3.3.0). Update in .phpcs.xml.dist if targeting older WP:

     <config name="minimum_wp_version" value="6.3"/>
     

3. Slevomat Sniffs:

   • Trailing Commas: RequireTrailingCommaInCall enforces trailing commas in multi-line calls, while DisallowTrailingCommaInCall applies to single-line calls.
   • Null Coalesce: RequireNullCoalesceOperator (??) and RequireNullCoalesceEqualOperator (??=) are mandatory in v3.3.0+.

4. Threshold Report Quirks:

   • Backslashes in Paths: Escape paths on Windows:

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

   • Exact Match: Use YOASTCS_THRESHOLD_EXACT_MATCH to detect if thresholds were exactly met (not just under).

5. Performance:

   • Exclude vendor/ and .git/ explicitly to avoid slow scans:

     vendor/bin/phpcs --standard=Yoast --exclude=vendor,node_modules src/
     

Debugging Tips

1. Isolate Sniffs: Run a single sniff for debugging:

   vendor/bin/phpcs --standard=Yoast --sniffs=SlevomatCodingStandard.Functions.DisallowTrailingCommaInCall src/
   

2. Verbose Output: Enable debug mode:

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

3. Parallel Lint Errors:

   • Deprecated Functions: --show-deprecated flags deprecated calls (e.g., mysql_*).
   • Parse Errors: Focus on files with Parse error in output.

4. PhpStorm False Positives:

   • Disable conflicting inspections (e.g., "Unused parameter") if they conflict with VariableAnalysis sniffs.

Extension Points

1. Custom Sniffs: Add to Yoast ruleset in .phpcs.xml.dist:

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

2. Override Defaults: Extend the ruleset dynamically:

   // In a Composer script (e.g., post-autoload-dump)
   $ruleset = new \PHP_CodeSniffer\Ruleset();
   $ruleset->importRuleset('Yoast');
   $ruleset->addExcludedFile('path/to/excluded-file.php');
   

3. Custom Reports: Extend the Threshold report or create a new one by subclassing PHP_CodeSniffer\Reports\Report.

4. PHPCompatibilityWP: Adjust PHP version checks:

   <config name="php_version" value="8.1"/>