Phpcodesniffer Composer Installer Laravel Package

Getting Started

Minimal Steps

1. Install the Plugin Add the package as a dev dependency:

   composer require --dev dealerdirect/phpcodesniffer-composer-installer
   

   Grant plugin execution permission (Composer 2.2+):

   composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
   

   (This auto-configures composer.json with the allow-plugins setting.)

2. Add PHPCS Standards Require any phpcodesniffer-standard packages (e.g., phpcompatibility/php-compatibility):

   composer require --dev phpcompatibility/php-compatibility
   

3. Verify Installation Run composer install or composer update. Afterward, check installed standards:

   ./vendor/bin/phpcs -i
   

First Use Case

Automate PHPCS Standard Setup Replace manual installed_paths configuration in .phpcs.xml by letting Composer auto-detect and register standards from dependencies. Example:

composer require --dev dealerdirect/phpcodesniffer-composer-installer squizlabs/php_codesniffer

Now phpcs will automatically include Squiz standards without manual path setup.

Implementation Patterns

Core Workflow

1. Dependency Management

   • Declare standards as dev dependencies with type: phpcodesniffer-standard (e.g., wpcs/wpcs).
   • The plugin scans these packages for PHPCS rulesets during composer install/update.

2. Integration with CI/CD

   • Add to composer.json scripts for CI environments:

     {
       "scripts": {
         "post-install-cmd": ["PHPCSStandards\\Composer\\Plugin\\Installers\\PHPCodeSniffer\\Plugin::run"]
       }
     }
     

   • Ensures standards are installed in CI pipelines (e.g., GitHub Actions).

3. Custom Standard Development

   • Package your standards as a Composer library with type: phpcodesniffer-standard.
   • Example composer.json:

     {
       "name": "vendor/custom-standards",
       "type": "phpcodesniffer-standard",
       "require": {
         "squizlabs/php_codesniffer": "^4.0"
       }
     }
     

4. Search Depth Customization

   • Override default 3-level search depth in composer.json:

     {
       "extra": {
         "phpcodesniffer-search-depth": 5
       }
     }
     

Laravel-Specific Patterns

• Laravel Mix/Pest Integration Add PHPCS to Laravel’s dev workflow:

  composer require --dev dealerdirect/phpcodesniffer-composer-installer pestphp/pest-plugin-phpunit
  

  Configure Pest to run PHPCS:

  // phpunit.xml
  <phpunit>
    <extensions>
      <extension class="Pest\PHPUnit\Extensions\PHPCSExtension"/>
    </extensions>
  </phpunit>
  

• Artisan Command Hooks Trigger PHPCS in Laravel’s post-update-cmd:

  {
    "scripts": {
      "post-update-cmd": [
        "@php artisan optimize:clear",
        "PHPCSStandards\\Composer\\Plugin\\Installers\\PHPCodeSniffer\\Plugin::run"
      ]
    }
  }
  

• Laravel Forge/Envoyer Ensure standards are installed on deployment by adding the plugin to composer.json in your repo.

Gotchas and Tips

Pitfalls

1. Composer 2.2+ Plugin Permission

   • Issue: Composer 2.2+ prompts for plugin execution permission. Forgetting to grant it (allow-plugins) causes silent failures.
   • Fix: Run composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true or add it manually to composer.json.

2. Global vs. Local Plugin Conflict

   • Issue: Global Composer installs may override project-specific plugin versions.
   • Fix: Use composer self-update to ensure local project plugins take precedence.

3. Open-Basedir Restrictions

   • Issue: Some servers (e.g., shared hosting) restrict open_basedir, breaking PHPCS path resolution.
   • Fix: Update composer.json to include:

     {
       "config": {
         "open_basedir": ["vendor/", "path/to/project"]
       }
     }
     

4. Circular Dependencies

   • Issue: Standards requiring the plugin and being required by other standards can cause version conflicts.
   • Fix: Use flexible version constraints (e.g., * or ^0.4 || ^1.0).

5. PHPCS Version Mismatches

   • Issue: Plugin supports PHPCS 3.x/4.x, but a dependency uses PHPCS 2.x.
   • Fix: Pin PHPCS version in your project’s composer.json:

     {
       "require-dev": {
         "squizlabs/php_codesniffer": "^4.0"
       }
     }
     

Debugging Tips

• Verify Plugin Execution Check Composer logs for plugin output:

  composer install --verbose
  

  Look for lines like:

  [PHPCSStandards\Composer\Plugin\Installers\PHPCodeSniffer\Plugin] Installing standards...
  

• Manual Plugin Invocation Test plugin functionality independently:

  composer run-script install-codestandards
  

• Check Installed Standards List all detected standards:

  ./vendor/bin/phpcs -i
  

  If empty, the plugin failed to register paths. Recheck composer.json for allow-plugins.

Extension Points

1. Custom Standard Discovery Override the plugin’s standard discovery logic by extending the Plugin class:

   // src/Composer/Plugin.php
   namespace App\Composer;
   use PHPCSStandards\Composer\Plugin\Installers\PHPCodeSniffer\Plugin as BasePlugin;
   
   class Plugin extends BasePlugin {
       protected function getStandardPaths(): array {
           return array_merge(
               parent::getStandardPaths(),
               ['/custom/path/to/standards']
           );
       }
   }
   

   Register the custom plugin in composer.json:

   {
     "scripts": {
       "post-install-cmd": ["App\\Composer\\Plugin::run"]
     }
   }
   

2. Post-Install Hooks Extend PHPCS configuration after plugin execution:

   {
     "scripts": {
       "post-install-cmd": [
         "PHPCSStandards\\Composer\\Plugin\\Installers\\PHPCodeSniffer\\Plugin::run",
         "@custom-phpcs-config"
       ]
     },
     "scripts-custom": {
       "custom-phpcs-config": "php artisan phpcs:configure"
     }
   }
   

3. CI-Specific Optimizations Skip plugin execution in CI if standards are already cached:

   {
     "scripts": {
       "post-install-cmd": [
         "@php -r \"if (!getenv('CI')) { PHPCSStandards\\Composer\\Plugin\\Installers\\PHPCodeSniffer\\Plugin::run(); }\""
       ]
     }
   }
   

Pro Tips

• Leverage composer.json Config Centralize PHPCS settings in composer.json:

  {
    "config": {
      "allow-plugins": {
        "dealerdirect/phpcodesniffer-composer-installer": true
      }
    },
    "extra": {
      "phpcodesniffer-search-depth": 4,
      "phpcodesniffer-standard-names": ["PSR12", "Custom"]
    }
  }
  

• Combine with php-cs-fixer Use the plugin alongside php-cs-fixer for auto-fixing:

  composer require --dev dealerdirect/phpcodesniffer-composer-installer friendsofphp/php-cs-fixer
  

  Add to composer.json:

  {
    "scripts": {
      "post-install-cmd": [
        "PHPCSStandards\\Composer\\Plugin\\Installers\\PHPCodeSniffer\\Plugin::run",
        "php-cs-fixer fix --rules=@PSR12 --dry-run"
      ]
    }
  }
  

• Document Standard Usage Add a README.md section to your project:

  ## PHPCS Standards
  This project uses the following standards, auto-installed via Composer:
  ```bash
  ./vendor/bin/phpcs -i