Fixing the Composer Global Command

One of the most commonly documented ways for a PHP command line tool to be installed is via the composer global require command. This command is easy to document and easy to run, which explains its popularity. Unfortunately, this convenient function has a darker side that can cause some pretty big problems. The root of the problem is that Composer, by design, manages dependencies on a per-project basis; however, the global command installs everything into a common central project. The upshot of this is that two distinct projects that were never intended to be combined must suddenly share dependencies. In this configuration, it is all-too-common to encounter dependency conflicts that never would have been observed had these applications been installed independently.

The solution to this problem is a little tool called cgr. Cgr is short for “composer global require”, the command it is intended to replace. The cgr tool can be found on GitHub.

When cgr is used to install a PHP command line tool, it will create a separate project directory for each project that it installs. Each project will have its own vendor directory, avoiding the conflicts caused by the composer global require command. When installing tools, cgr ensures that their binaries will be installed to ~/.composer/vendor/bin—the same location that composer global require places them. Thus, anyone who has already configured their system for composer global require can switch to using cgr at any time, and no additional configuration will be needed.

Installing the cgr tool is a simple matter of running composer global require consolidation/cgr. Cgr does not have any dependencies of its own, so it will always be safe to do this—even if you still have old projects installed via composer global require still lingering on your system.

The composer global require command still has a place in the php ecosystem, however, as Composer will load plugins from the global project. Therefore, composer global require should still be used to install composer plugins, such as composer versions check, that you want to have available everywhere Composer is used. For any project that does not include a composer plugin, however, the cgr tool is the better option.

Finally, there is a discussion around altering the behavior of the Composer global command, so that the cgr tool will no longer be necessary. It will probably take some time to decide how, exactly, to reconcile the needs of command line tool installation vis-a-vis the needs of Composer plugin needs; if you are interested in the current progress, see the issue in the Composer Github project. In the meantime, you should use the cgr tool to avoid any problems you may encounter with composer global require.