Composer Bin Plugin Laravel Package

Getting Started

Start by installing the plugin as a dev dependency in your main project:

composer require --dev bamarni/composer-bin-plugin

This adds the bin command to Composer. The first use case is isolating CLI tools with conflicting dependencies (e.g., PHP-CS-Fixer and Rector both using nikic/php-parser). Create an isolated environment for each tool:

composer bin php-cs-fixer require --dev friendsofphp/php-cs-fixer

This creates vendor-bin/php-cs-fixer/composer.json, installs dependencies there, and avoids polluting your main composer.json dependencies.

Implementation Patterns

• Namespace per tool: Create separate namespaces for each tool (php-cs-fixer, phpstan, rector, etc.) to keep their dependencies isolated.
• bin all for bulk operations: Use composer bin all update or composer bin all require to apply commands across all namespaces.
• Forwarding commands: Enable forward-command in config ("bamarni-bin": { "forward-command": true }) to auto-run composer install/update in all vendor-bin/* directories during main composer install/update.
• Shell aliases or scripts: Since bin links are disabled by default (recommended in v2), define Composer scripts or shell aliases for convenience:

  {
    "scripts": {
      "cs-fixer": "php vendor-bin/php-cs-fixer/vendor/friendsofphp/php-cs-fixer/bin/php-cs-fixer"
    }
  }
  

Gotchas and Tips

• Bin links disabled by default in v2: Symlinks in vendor/bin/ won’t be auto-created. Use scripts or aliases instead.
• .gitignore: Exclude vendor-bin/*/vendor/ to prevent committing tool dependencies:

  vendor-bin/**/vendor/
  

• Lockfile noise: Mark vendor-bin/*/composer.lock as binary in .gitattributes to avoid noisy diffs:

  vendor-bin/**/composer.lock binary
  

• CI integration: In GitHub Actions, install specific bin namespaces with working-directory (since ramsey/composer-install doesn’t support bin all natively).
• Configuration clarity: Explicitly set "bin-links": false and "forward-command": false initially, then opt-in to avoid surprises.
• Avoid autoloading your code: Only isolate tools that do not autoload your project code (e.g., static analyzers, formatters), as mismatched autoloading can cause runtime issues.