Phpcs Variable Analysis Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require --dev dealerdirect/phpcodesniffer-composer-installer
   composer require --dev sirbrillig/phpcs-variable-analysis
   

   Add to your phpcs.xml:

   <rule ref="VariableAnalysis"/>
   

2. First Use Case: Run PHPCS on a Laravel controller or service:

   phpcs app/Http/Controllers/ --standard=VariableAnalysis
   

   Focus on files with undefined variables (e.g., typos) or unused variables (e.g., leftover debug code).

Implementation Patterns

Workflows

1. CI/CD Integration: Add to .github/workflows/phpcs.yml:

   - name: Run PHPCS
     run: phpcs --standard=VariableAnalysis --extensions=php app/
   

   Fail builds on warnings (adjust severity in phpcs.xml):

   <arg name="severity" value="10"/>
   

2. Laravel-Specific Customization: Override defaults in phpcs.xml for Laravel patterns:

   <rule ref="VariableAnalysis.CodeAnalysis.VariableAnalysis">
       <properties>
           <property name="allowUnusedFunctionParameters" value="true"/>
           <property name="allowWordPressPassByRefFunctions" value="true"/>
           <property name="sitePassByRefFunctions" value="Laravel\Helper\str_replace:1"/>
       </properties>
   </rule>
   

3. Targeted Analysis: Use --ignore to focus on critical files:

   phpcs --standard=VariableAnalysis --ignore="*,tests/*" app/
   

4. Pre-Commit Hooks: Add to .git/hooks/pre-commit:

   #!/bin/sh
   phpcs --standard=VariableAnalysis --extensions=php --warning-severity=5 "$@"
   

Gotchas and Tips

Pitfalls

1. False Positives in Templates: Disable for Blade templates:

   <file>resources/views/*.blade.php</file>
   <rule ref="VariableAnalysis.CodeAnalysis.VariableAnalysis">
       <properties>
           <property name="allowUndefinedVariablesInFileScope" value="true"/>
       </properties>
   </rule>
   

2. Constructor Promotion Confusion: Ensure sitePassByRefFunctions includes Laravel’s promoted properties:

   <property name="sitePassByRefFunctions" value="__construct:1,2,3"/>
   

3. Arrow Functions: Nested arrow functions may trigger false negatives. Use:

   <property name="allowUnusedForeachVariables" value="false"/>
   

4. Global Variables: Exclude globals like $_ENV or $_SERVER:

   <property name="validUndefinedVariableRegexp" value="/^_|^GLOBALS\["/>
   

Debugging

• Verbose Output:

  phpcs -v --standard=VariableAnalysis app/
  

• Isolate Rules: Test individual sniffs:

  phpcs --standard=VariableAnalysis --sniffs=UndefinedVariable app/
  

Extension Points

1. Custom Regex: Ignore magic methods (e.g., __get):

   <property name="ignoreUnusedRegexp" value="/^__\w+$|^_"/>
   

2. Framework-Specific Rules: Add Laravel’s app() helper:

   <property name="sitePassByRefFunctions" value="app():1"/>
   

3. Performance: Cache results in CI:

   phpcs --standard=VariableAnalysis --cache-file=.phpcs-cache app/