Shim Laravel Package

Getting Started

The php-cs-fixer/shim package provides a lightweight, self-contained PHAR distribution of PHP CS Fixer, ideal for projects wanting to avoid installing the full friendsofphp/php-cs-fixer package (which pulls many dependencies). To start:

1. Install: Run composer require --dev php-cs-fixer/shim
   (Note: Ensure phar.readonly = Off in php.ini if running PHARs globally or via Composer scripts)
2. Verify: Run ./vendor/bin/php-cs-fixer --version
3. First use: Apply default rules to your codebase:
   ./vendor/bin/php-cs-fixer fix src/

This is especially useful in CI pipelines or constrained environments where minimizing dependency bloat matters. Begin with the main PHP CS Fixer docs for configuration and rule sets.

Implementation Patterns

• CI Integration: Use in GitHub Actions or GitLab CI by installing via Composer, then run php-cs-fixer fix --dry-run before build steps to fail fast on style violations.
• Pre-commit Hook: Add to pre-commit via husky + lint-staged or custom shell scripts:

  ./vendor/bin/php-cs-fixer fix --path-mode=override src/ tests/
  

• Config Files: Use .php-cs-fixer.php (or .php-cs-fixer.dist.php) in project root to define rulesets (e.g., @Symfony, @PSR12, or custom rules). The shim respects Composer’s autoloading and config discovery.
• Custom Rulesets: Extend built-in rulesets by referencing rule sets in config:

  return PhpCsFixer\Config::create()
      ->setRules([
          '@PSR12' => true,
          'phpdoc_summary' => false,
          'single_blank_line_before_namespace' => true,
      ]);
  

Gotchas and Tips

• No Autoloader Integration: Unlike the full package, the shim does not expose its classes via Composer’s autoloader—only the PHAR binary is included. Don’t try to use its classes directly.
• Version Pinning: The shim releases track major/minor versions of the upstream PHAR. Always pin to a specific version (e.g., ^3.54) to avoid unexpected rule changes in CI.
• File Permissions: If running into phar “…” has wrong permissions, ensure the PHAR file (vendor/bin/php-cs-fixer) is executable:
  chmod +x vendor/bin/php-cs-fixer
• PHP Version Compatibility: The PHAR includes its own PHAR stub—ensure your CI/runner uses PHP ≥7.4 (current PHAR requirements).
• Debugging: Use -vvv for verbose output or --dry-run to preview changes. If rules don’t apply as expected, check your config file path and rules syntax (e.g., using string keys like 'array_syntax' => ['syntax' => 'short']).
• Fallback for Legacy: Ideal for projects migrating away from friendsofphp/php-cs-fixer, since it avoids conflicts if the full package is still installed elsewhere.