Code Sniffer Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require --dev spryker/code-sniffer
   

   Add to require-dev in composer.json for project-wide use.

2. First Run:

   vendor/bin/phpcs --standard=vendor/spryker/code-sniffer/Spryker/ruleset.xml ./src
   

   Or use the Spryker CLI shortcut:

   console code:sniff:style
   

3. Fix Issues Automatically:

   console code:sniff:style -f
   

Where to Look First

• List of included sniffs – Understand what rules are enforced.
• Spryker/ruleset.xml – Default configuration for all sniffs.
• SprykerStrict/ruleset.xml – Stricter variant for advanced projects.

First Use Case

Run the sniffer on a single module to validate adherence to Spryker conventions:

console code:sniff:style -m Customer -v

This checks only the src/ directory of the Customer module.

Implementation Patterns

Daily Workflow

1. Pre-Commit Hook: Integrate phpcs into your Git hooks to catch violations early:

   echo 'vendor/bin/phpcs --standard=vendor/spryker/code-sniffer/Spryker/ruleset.xml ./src' >> .git/hooks/pre-commit
   chmod +x .git/hooks/pre-commit
   

2. IDE Integration: Configure PHPStorm (as per README) or VSCode with:

   • Sniff on Save: Use a file watcher to auto-check files.
   • Quick Fix: Bind phpcbf to a keyboard shortcut (e.g., Ctrl+Alt+F).

3. CI Pipeline: Add to your CI (e.g., GitHub Actions, CircleCI):

   - name: Run Code Sniffer
     run: vendor/bin/console code:sniff:style
   

Integration Tips

• Exclude Paths: Ignore generated/third-party code in ruleset.xml:

  <exclude-pattern>*/src/Generated/*</exclude-pattern>
  <exclude-pattern>*/vendor/*</exclude-pattern>
  

• Custom Rulesets: Extend the default ruleset.xml for project-specific needs:

  <rule ref="vendor/spryker/code-sniffer/Spryker/ruleset.xml">
      <exclude name="SlevomatCodingStandard.Functions.DisallowNamedArguments"/>
  </rule>
  

• Strict Mode: Enable stricter checks by switching to SprykerStrict:

  console code:sniff:style --standard=vendor/spryker/code-sniffer/SprykerStrict/ruleset.xml
  

Module-Specific Checks

Target a specific module or path:

console code:sniff:style -m Oms -p OrderManagement

Checks only src/Oms/OrderManagement/.

Gotchas and Tips

Pitfalls

1. False Positives in Generated Code:

   • Generated files (e.g., src/Generated/) often violate rules. Exclude them in ruleset.xml:

     <exclude-pattern>*/src/Generated/*</exclude-pattern>
     

2. PHP Version Mismatches:

   • Some sniffs (e.g., SprykerDisallowFunctions) block PHP 8+ features in PHP 7.4 code.
   • Fix: Configure allowed PHP version in ruleset.xml:

     <rule ref="Spryker.Internal.SprykerDisallowFunctions">
         <properties>
             <property name="phpVersion" value="8.2"/>
         </properties>
     </rule>
     

3. Namespace Conflicts:

   • The sniffer defaults to Spryker’s namespaces (Pyz, Spryker, etc.).
   • Fix: Customize for non-Spryker projects:

     <rule ref="Spryker.Namespaces.SprykerNamespace">
         <properties>
             <property name="namespace" value="App"/>
             <property name="isRoot" value="true"/>
         </properties>
     </rule>
     

4. Performance on Large Codebases:

   • Running phpcs on the entire src/ directory can be slow.
   • Tip: Use --parallel (PHP_CodeSniffer ≥ 3.7.0):

     vendor/bin/phpcs --parallel=8 --standard=Spryker ./src
     

Debugging

1. Verbose Output: Use -v to debug specific errors:

   console code:sniff:style -v
   

2. Isolate Sniffs: Run a single sniff to diagnose issues:

   console code:sniff:style -s Spryker.Namespaces.SprykerNamespace
   

3. Token Inspection: Use the built-in tokenizer to debug custom sniffs:

   bin/tokenize path/to/file.php
   

Extension Points

1. Custom Sniffs: Add new sniffs to Sniffs/ and test them:

   php tests/generate.php MyNamespace.MySniff
   composer test
   

2. Override Default Rules: Create a project-specific ruleset.xml and reference it in DevelopmentConfig.php:

   public function getCodingStandard() {
       return __DIR__ . '/../config/ruleset.xml';
   }
   

3. Silence Rules Temporarily: Disable a rule during migration:

   <rule ref="SlevomatCodingStandard.ControlStructures.ControlStructureSpacing">
       <severity>0</severity>
   </rule>
   

Pro Tips

• Auto-Fix Common Issues: Use phpcbf for fixable errors (e.g., indentation, braces):

  console code:sniff:style -f
  

• Strict Types Enforcement: Enforce declare(strict_types=1) in ruleset.xml:

  <rule ref="Spryker.PHP.DeclareStrictTypesAfterFileDoc">
      <properties>
          <property name="strictTypesMandatory" value="true"/>
      </properties>
  </rule>
  

• License Header Check: Validate license headers via .license file (PHP docblock format).

• CI-Safe Updates: Update the sniffer in a dedicated branch (e.g., master-cs) before merging to avoid breaking builds:

  composer require spryker/code-sniffer:~1.0.0 --dev