Composer bin plugin — Isolate your bin dependencies

Table of Contents

1. Why? A hard problem with a simple solution.
2. Usage; How does this plugin work?
3. Installation
4. Configuration
   1. Bin links (bin-links)
   2. Target directory (target-directory)
   3. Forward command (forward-command)
5. Tips & Tricks
   1. Auto-installation
   2. Reduce clutter
   3. GitHub Actions integration
6. Related plugins
7. Backward Compatibility Promise
8. Contributing

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 different 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 vendor-bin/<bin-namespace-name>/composer.json* file.

For example:

$ 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

Installation

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

Configuration

{
    ...
    "extra": {
        "bamarni-bin": {
            "bin-links": false,
            "target-directory": "vendor-bin",
            "forward-command": true
        }
    }
}

Bin links (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 vendor/phpunit/phpunit.

In 1.x, BamarniBinPlugin behaves the same way for "bin dependencies", i.e. when executing 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 use vendor-bin/php-cs-fixer/vendor/friendsofphp/php-cs-fixer/path/tophp-cs-fixer (in which case setting an alias via a Composer script or something is recommended).

Target directory (target-directory)

Defaults to vendor-bin, can be overridden to anything you wish.

Forward command (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

Auto-installation

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:

{
    "scripts": {
        "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).

Reduce clutter

You can add the following line to your .gitignore file in order to avoid committing dependencies of your tools.

# .gitignore
/vendor-bin/**/vendor/

Updating each tool can create many not legible changes in composer.lock files. You can use a .gitattributes file in order to inform git that it shouldn't show diffs of composer.lock files.

# .gitattributes
/vendor-bin/**/composer.lock binary

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 the working-directory:

#...
    -   name: "Install PHP-CS-Fixer Composer dependencies"
        uses: "ramsey/composer-install@v2"
        with:
            working-directory: "vendor-bin/php-cs-fixer"

Related plugins

• 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.

Contributing

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.