Code Sniffer Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev php-collective/code-sniffer
   

2. Configure phpcs.xml in your project root:

   <?xml version="1.0"?>
   <ruleset name="your-project">
       <file>src/</file>
       <file>tests/</file>
       <rule ref="vendor/php-collective/code-sniffer/PhpCollective/ruleset.xml"/>
   </ruleset>
   

3. First Use Case: Run a quick check on your codebase:

   composer cs-check
   

   (Add this to your composer.json scripts section as shown in the docs.)

Implementation Patterns

Daily Workflow

1. Pre-Commit Hooks: Integrate with tools like husky or pre-commit to run phpcs automatically:

   # .pre-commit-config.yaml
   - repo: local
     hooks:
       - id: phpcs
         name: PHP Code Sniffer
         entry: vendor/bin/phpcs
         language: system
         types: [php]
         args: ["--standard=PhpCollective"]
   

2. CI/CD Integration: Add to your CI pipeline (e.g., GitHub Actions):

   - name: Run PHP Code Sniffer
     run: vendor/bin/phpcs --standard=PhpCollective
   

3. IDE Integration: Configure PHPStorm or VSCode to run phpcs on save via file watchers or hotkeys (as documented).

4. Team Onboarding:

   • Document the phpcs.xml rules in your CONTRIBUTING.md.
   • Use PhpCollectiveStrict for new projects to enforce stricter standards early.

Advanced Patterns

1. Custom Rulesets: Extend the base ruleset for project-specific needs:

   <ruleset name="ProjectRules">
       <rule ref="vendor/php-collective/code-sniffer/PhpCollective/ruleset.xml">
           <exclude name="PhpCollective.NamingConventions.ValidClassName.NotCamelCaps"/>
       </rule>
       <rule ref="Custom/Sniffs/ruleset.xml"/>
   </ruleset>
   

2. Dynamic Configuration: Use environment variables to toggle rules (e.g., disable DisallowFunctions in CI):

   PHPCS_SKIP_DISALLOW_FUNCTIONS=1 vendor/bin/phpcs
   

3. Fixers Workflow:

   • Run composer cs-fix for auto-fixable issues.
   • Review changes with git diff before committing.

4. Partial Fixes: Fix specific files interactively:

   vendor/bin/phpcbf --interactive src/MyClass.php
   

Gotchas and Tips

Common Pitfalls

1. False Positives:

   • Tokenization Issues: Use vendor/bin/tokenize to debug complex sniffs (e.g., nested closures).
   • Legacy Code: Temporarily exclude problematic files:

     <exclude name="vendor/legacy-library/"/>
     

2. Performance:

   • Exclude large directories (e.g., node_modules, storage/logs) from phpcs.xml:

     <exclude-pattern>.*/(node_modules|storage/logs)/.*</exclude-pattern>
     

3. Strict Mode:

   • Enabling DeclareStrictTypesAfterFileDoc may break type coercion in older PHP versions. Test thoroughly.

4. PHP Version Safety:

   • Misconfigured DisallowFunctions (e.g., phpVersion="8.2" in PHP 8.1) will flag core functions. Use 'off' to disable:

     <rule ref="PhpCollective.Internal.DisallowFunctions">
         <properties>
             <property name="phpVersion" value="off"/>
         </properties>
     </rule>
     

Debugging Tips

1. Verbose Output: Run with -v to see detailed errors:

   vendor/bin/phpcs -v src/
   

2. Sniff-Specific Debugging: Use --report=full to see token-level details for a specific rule:

   vendor/bin/phpcs --report=full --standard=PhpCollective src/MyClass.php
   

3. Testing Sniffs:

   • Generate tests for new sniffs:

     php tests/generate.php MyNamespace.MySniff
     

   • Run all tests:

     composer test
     

4. IDE Debugging:

   • In PHPStorm, enable "Show Console Output" in External Tools settings to debug phpcs/phpcbf commands.

Extension Points

1. Custom Sniffs:

   • Place new sniffs in Sniffs/ with matching test files in tests/.
   • Example structure:

     Sniffs/
     └── MyCompany/
         └── Sniffs/
             └── Arrays/
                 └── DisallowEmptyArraysSniff.php
     tests/
     └── MyCompany/
         └── Sniffs/
             └── Arrays/
                 └── DisallowEmptyArraysSniffTest.php
     

2. Overriding Rules:

   • Override properties dynamically in phpcs.xml:

     <rule ref="PhpCollective.Commenting.DocBlockReturnVoid">
         <properties>
             <property name="checkReturnTypeHint" value="false"/>
         </properties>
     </rule>
     

3. Composite Rulesets: Combine multiple standards (e.g., PhpCollective + SlevomatCodingStandard):

   <ruleset name="Composite">
       <rule ref="vendor/php-collective/code-sniffer/PhpCollective/ruleset.xml"/>
       <rule ref="vendor/slevomat/coding-standard/SlevomatSniffs/ruleset.xml"/>
   </ruleset>
   

4. Parallel Execution: Speed up large codebases with --parallel (PHP 7.4+):

   vendor/bin/phpcs --parallel=8
   

Pro Tips

1. Incremental Adoption:

   • Start with PhpCollective and migrate to PhpCollectiveStrict over time.
   • Use severity="0" to silence rules temporarily:

     <rule ref="PhpCollective.ControlStructures.DisallowShortTernary">
         <severity>0</severity>
     </rule>
     

2. Automated Fixes:

   • Chain phpcbf with git add in a pre-commit hook:

     vendor/bin/phpcbf --standard=PhpCollective --diff && git add -u
     

3. Documentation:

   • Generate a custom sniffs.md after adding new sniffs:

     composer docs
     

4. Legacy Code Handling:

   • Use exclude-pattern to skip legacy directories:

     <exclude-pattern>.*/legacy/.*</exclude-pattern>