Avoiding “Dependency Hell” with Site-Local Drush

Composer has brought the PHP community a long way, making dependency management much more convenient. With the advent of Drupal 8.0.0-rc1, even more people are going to be using composer indirectly, whether they realize it or not. This is because Drupal 8 uses Composer to manage its external libraries. Drush also uses Composer to manage  dependencies, which means you can get spectacularly bad results, including some very difficult to diagnose crashes, unless  all of Drush’s dependencies are very strictly compatible with all of Drupal’s dependencies. 

Managing compatible dependencies independently is extremely difficult—so much so that the moniker “dependency hell” has been coined to describe the situations that can arise when things get out of sync. The intricacies of this problem is quite involved, but the simplified conclusion is that the only safe solution is to make Drush a dependency of Drupal. We’ll examine how to do that below.

If you are using one of the standard project templates for using Composer to manage your Drupal 8 site, such as the recommended standard template, drupal-composer/drupal-project, you will see that Drush is already listed as a dependency in the provided composer.json file:

    "require": { 
        "composer/installers": "^1.0.20", 
        "drupal/core": "~8.4", 
        "drush/drush": "~8", 
        "drupal/console": "^1.0.2" 
    },

Drush has been part of this example project for a long time, and most of the other Drupal 8 Composer project templates are also following suit, so odds are good that you have already adopted this practice if you based your site on one of these projects. Most people, however, are probably downloading Drupal from drupal.org, or using Drush or the Drupal Console to get it. If you fall into that category of user, you can add Drush as a dependency of Drupal in two easy steps:

    cd /path/to/drupal8/root
    composer require "drush/drush:^8"

That’s it.  It used to be a lot more complicated to start managing your Drupal dependencies with Composer, but now it really is this easy. Once you use composer require to add something to your Drupal site, though, you should be careful to thereafter use composer update rather than drush pm-update to keep your Drupal site up-to-date. If you do not heed this advice, you will overwrite your composer.json file and lose the extra dependencies you added.

If you have already tried your hand at using Composer to add Drush to your Drupal 8 site, you may have noticed that your site-local Drush was placed in the vendor/bin directory inside of your Drupal root. You may be wondering whether you should put this directory in your $PATH, or what you should do if you have more than one Drupal 8 site on the same computer. Fortunately, Drush has already anticipated this problem for you and solved it. All that you need to do is update your global Drush—the one that is on your $PATH--to Drush 8.0.0-rc1 or later. Then, any time you run a Drush command, the global Drush will notice that there is a site-local Drush, and will use it instead. So, to run a status command on your Drupal 8 site using the site-local Drush that you added to it, all you need to do is:

    cd /path/to/drupal8/root
    drush status

That’s it. If everything is working correctly, you should see that the line in the output labeled “Drush script:“ points at a drush.php file that is inside your Drupal site’s vendor directory. You may now rest assured that future Drupal upgrades will not lead you into “dependency hell”.