Phpcs Symfony2 Standard Laravel Package

Getting Started

Minimal Setup

1. Install via Composer (recommended):

   composer require --dev leaphub/phpcs-symfony2-standard
   

   This auto-installs phpcs as a dev dependency.

2. Run a basic check on your src/ directory:

   vendor/bin/phpcs --standard=vendor/leaphub/phpcs-symfony2-standard/leaphub/phpcs/Symfony2 --extensions=php src/
   

3. Quick alias (add to composer.json scripts):

   "scripts": {
       "cs-check": "phpcs --standard=vendor/leaphub/phpcs-symfony2-standard/leaphub/phpcs/Symfony2 --extensions=php src/"
   }
   

   Then run:

   composer cs-check
   

First Use Case: Pre-Commit Hook

Integrate with pre-commit (e.g., via husky or pre-commit hooks) to enforce standards before merging:

# Example .huskyrc
"pre-commit": "composer cs-check"

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline:

   • Fail builds on violations (e.g., GitHub Actions):

     - name: Run PHP_CodeSniffer
       run: composer cs-check || exit 1
     

   • Use --report=full for detailed output in PRs.

2. IDE Integration:

   • Configure PHPStorm to use the standard: Settings > PHP > Code Sniffer > Standard: vendor/leaphub/phpcs-symfony2-standard/leaphub/phpcs/Symfony2.
   • Enable "On the fly" checks for real-time feedback.

3. Custom Rulesets:

   • Extend the standard by creating a phpcs.xml file:

     <config name="installedPaths" value="vendor/leaphub/phpcs-symfony2-standard/leaphub/phpcs/Symfony2"/>
     <rule ref="Symfony2">
         <exclude name="Symfony2.Files.LineEndings" /> <!-- Disable line-ending checks -->
     </rule>
     

4. Fix Automatically:

   • Use --fix to auto-correct simple issues (e.g., indentation):

     vendor/bin/phpcbf --standard=Symfony2 src/
     

Common Use Cases

Gotchas and Tips

Pitfalls

1. Path Confusion:

   • Issue: phpcs fails with Standard not found.
   • Fix: Use the full path to the standard:

     vendor/bin/phpcs --standard=vendor/leaphub/phpcs-symfony2-standard/leaphub/phpcs/Symfony2 ...
     

   • Tip: Add an alias in ~/.bashrc:

     alias phpcs-sf="vendor/bin/phpcs --standard=vendor/leaphub/phpcs-symfony2-standard/leaphub/phpcs/Symfony2"
     

2. False Positives:

   • Symfony2.Files.LineEndings: May flag LF/CRLF issues. Exclude if using Git’s core.autocrlf.
   • Symfony2.NamingConventions.ValidClassName: Strict about underscores in class names (e.g., User_Manager). Disable if legacy code exists.

3. Performance:

   • Exclude large directories (e.g., vendor/, node_modules/) to speed up checks:

     phpcs --ignore=vendor/,node_modules/ src/
     

Debugging

1. Verbose Output:

   • Use -v to debug rule application:

     phpcs -v --standard=Symfony2 src/Controller/UserController.php
     

2. Unit Tests:

   • Run the standard’s tests to verify correctness:

     cd vendor/leaphub/phpcs-symfony2-standard
     phpunit --filter Symfony2_* tests/AllTests.php
     

Extension Points

1. Custom Sniffs:

   • Add project-specific rules by extending the standard:

     mkdir -p vendor/leaphub/phpcs/Symfony2/Sniffs/YourCompany
     

   • Example: Create YourCompany/Sniffs/Files/ProhibitedFilenameSniff.php to block config_local.php.

2. Override Rules:

   • Place custom rules in app/CodeSniffer/ and reference them in phpcs.xml:

     <rule ref="Symfony2">
         <exclude name="Symfony2.NamingConventions.ValidClassName.NotCamelCaps"/>
     </rule>
     <rule ref="app/CodeSniffer/Sniffs/YourCompany/">
         <active>true</active>
     </rule>
     

3. Symfony-Specific Tips:

   • Doctrine Entities: Use --ignore=src/Entity/* if entity naming conventions conflict.
   • Twig Templates: Exclude .twig files unless you’ve added Twig-specific sniffs.

Configuration Quirks

1. Caching:

   • PHP_CodeSniffer caches standards. Clear cache if rules seem outdated:

     rm -rf ~/.phpcs.cache
     

2. Composer Updates:

   • After updating leaphub/phpcs-symfony2-standard, re-run checks to catch new rules.

3. PHP Version:

   • Ensure your PHP version matches the standard’s requirements (tested on PHP 7.4+). Use a .phpcs.dist file to lock the standard version:

     <config name="installedPaths" value="vendor/leaphub/phpcs-symfony2-standard/leaphub/phpcs/Symfony2"/>
     <config name="standard" value="Symfony2"/>