Composer bin plugin — Isolate your bin dependencies
Table of Contents
- Why? A hard problem with a simple solution.
- Usage; How does this plugin work?
- Tips & Tricks
- Related plugins
- Backward Compatibility Promise
Why? A hard problem with a simple solution.
When managing your dependencies with Composer, your dependencies are flattened with compatible versions, or when not possible, result in conflict errors.
There is cases however when adding a tool as a dependency, for example PHPStan*
or Rector could have undesired effects due to the dependencies they
are bringing. For example if phpstan depends on
nikic/php-parser 4.x and rector
3.x, you cannot install both tools at the same time (despite the fact that from
a usage perspective, they do not need to be compatible). Another example, maybe
you can no longer add a non-dev dependency because a dependency brought by PHPStan
is not compatible with it.
There is nothing special or exceptional about this problem: this is how dependencies work in PHP with Composer. It is however annoying in the case highlighted above, because the conflicts should not be: it is a limitation of Composer because it cannot infer how you are using each dependency.
One way to solve the problem above, is to install those dependencies in a
composer.json file. It comes with its caveats, for example if you
were to do that with PHPUnit, you may find yourself in the scenario
where PHPUnit will not be able to execute your tests because your code is not
compatible with it and Composer is not able to tell since the PHPUnit dependency
sits alone in its own
composer.json. It is the very problem Composer aim to
solve. As a rule of thumb, you should limit this approach to tools which do not
autoload your code.
However, managing several
composer.json kind be a bit annoying. This plugin
aims at helping you doing this.
*: You will in practice not have this problem with PHPStan as the Composer package
phpstan/phpstan is shipping a scoped PHAR (scoped via PHP-Scoper)
which provides not only a package with no dependencies but as well that has no
risk of conflicting/crash when autoloading your code.
Usage; How does this plugin work?
This plugin registers a
bin <bin-namespace-name> command that allows you to
interact with the
$ composer bin php-cs-fixer require --dev friendsofphp/php-cs-fixer
# Equivalent to manually doing:
$ mkdir vendor-bin/php-cs-fixer
$ cd vendor-bin/php-cs-fixer && composer require --dev friendsofphp/php-cs-fixer
You also have a special
all namespace to interact with all the bin namespaces:
# Runs "composer update" for each bin namespace
$ composer bin all update
$ composer require --dev bamarni/composer-bin-plugin
Bin links (
In 1.x: enabled by default. In 2.x: disabled by default.
When installing a Composer package, Composer may add "bin links" to a bin
directory. For example, by default when installing
phpunit/phpunit, it will
add a symlink
vendor/bin/phpunit pointing to the PHPUnit script somewhere in
In 1.x, BamarniBinPlugin behaves the same way for "bin dependencies", i.e. when
composer bin php-cs-fixer require --dev friendsofphp/php-cs-fixer,
it will add a bin link
vendor/bin/php-cs-fixer -> vendor-bin/php-cs-fixer/vendor/friendsofphp/php-cs-fixer.
This is however a bit tricky and cannot provide consistent behaviour. For example
when installing several packages with the same bin, (e.g. with the case above installing
another tool that uses PHP-CS-Fixer as a dependency in another bin namespace),
the symlink may or may not be overridden, or not created at all. Since it is not
possible to control this behaviour, neither provide an intuitive or deterministic
approach, it is recommended to set this setting to
false which will be the
default in 2.x.
It does mean that instead of using
vendor/bin/php-cs-fixer you will have to
(in which case setting an alias via a Composer script or something is recommended).
Target directory (
vendor-bin, can be overridden to anything you wish.
Forward command (
Disabled by default in 1.x, will be enabled by default in 2.x. If this mode is
enabled, all your
composer install and
composer update commands are forwarded
to all bin directories.
This is a replacement for the tasks shown in section Auto-installation.
Tips & Tricks
You can easily forward a command upon a
composer install to forward the install
to all (in which case having
extra.bamarni-bin.forward_command = true is more
adapted) or a specific of bin namespace:
"bin": "echo 'bin not installed'",
"post-install-cmd": ["@composer bin php-cs-fixer install --ansi"]
You can customise this as you wish leveraging the Composer script events).
You can add the following line to your
.gitignore file in order to avoid
committing dependencies of your tools.
Updating each tool can create many not legible changes in
You can use a
.gitattributes file in order to inform git that it shouldn't show
GitHub Actions integration
There is currently no way to leverage
ramsey/composer-install to install all
namespace bins. However it is unlikely you need this in the CI and not locally,
in which case forwarding the command should
be good enough.
If you still need to install specific bin namespaces, you can do it by setting
- name: "Install PHP-CS-Fixer Composer dependencies"
- theofidry/composer-inheritance-plugin: Opinionated version of Wikimedia composer-merge-plugin to work in pair with this plugin.
Backward Compatibility Promise
The backward compatibility promise only applies to the following API:
- The commands registered by the plugin
- The behaviour of the commands (but not their logging/output)
- The Composer configuration
The plugin implementation is considered to be strictly internal and its code may change at any time in a non back-ward compatible way.
A makefile is available to help out:
$ make # Runs all checks
$ make help # List all available commands
Note: you do need to install phive first.