Fix Up Drush Site Aliases with a Policy File

One thing that makes Drush site aliases so powerful is the fact that they are defined in regular PHP executable files.  This gives the user many options, as the alias definitions can easily be adjusted in code, factoring out common sections or making other adjustments directly in the alias file.  There are a number of reasons why one might wish to separate this code from the alias data, though.

  1. Some hosting platforms, such as Pantheon, will automatically generate Drush site alias files for every site available to you.  In these instances, it is preferable to not edit the generated file, so that the local copy may be easily updated with a pristine copy any time the set of available sites changes.

  2. Future versions of Drush will be moving away from using PHP executable files for site aliases, and will instead encourage the use of YML files for alias definitions.  This eliminates the concern that a shared alias file might contain code that causes unpredictable side effects.

  3. Separating code from data is simply a best practice.

Fortunately, Drush already provides a hook that allows you to do this.  The mechanism for altering Drush behavior is to use a policy file.  A policy is a regular Drush command file that contains hook implementations rather than Drush commands.  Of course, any command file may provide both commands and hooks, but these behaviors are usually separated just for the sake of organization.  To get started, create a file called, and place in in the .drush folder of your home directory.  There is an example policy file in Drush’s examples folder that you can use to get started, if you wish.

For our example, we will write a policy file that changes all remote aliases to use drush7 instead of drush (that is, the default version of Drush), but only if the target is the Pantheon platform.  Our hook_drush_sitealias_alter function looks like this:

function policy_drush_sitealias_alter(&$alias_record) {
  // Fix pantheon aliases!
  if ( isset($alias_record['remote-host']) &&
      (substr($alias_record['remote-host'],0,10) == 'appserver.') ) {
    $alias_record['path-aliases']['%drush-script'] = 'drush7';

The sitealias alter hook takes a reference to one alias record, which it may adjust as desired.  We start out by testing to see if the record has a remote-host element that points to a server on the Pantheon platform.  If so, we set %drush-script to drush7.  Drush uses the %drush-script element to determine which program to use when running a remote Drush command for that alias; Pantheon has set up their environment so that there is a program called drush7 available that points to Drush version 7.  With this policy file in place, you will be able to use the latest version of Drush on Pantheon:

    $ drush version
    Drush Version   :  7.0.0-rc1

Following the pattern of this example alter hook, you can make any adjustments needed to your alias files on the fly.  If you are currently embedding code inside the alias file directly, it would be a good idea to convert it to a policy file, so you are ready for the shift to YML when it comes.

Topics Development, Drupal Planet, Drupal