How To Declare Your Own Drush Commands with your VPS

About Drush

Drush is a cool command line interface for managing your Drupal sites. It provides a lot of simple commands with which you can perform some administrative tasks on your site with great speed. If you are not familiar with what Drush can do, check out this beginner guide to using Drush.

What’s cool about Drush is that it is very developer-friendly. This means that aside from the existing commands, you can declare custom ones that perform the tasks you want. So in this article, you will get a straight and to the point tutorial for declaring your own Drush commands. To illustrate how to do this, we will declare a command that will publish all the nodes of a given content type the user passes as the command argument.

Getting Started

To go through this tutorial, you should already have Drush set up on your VPS. Preferably, you should also have a Drupal installation to work with and must not be afraid of some simple Drupal code. To learn how to set up Drush on your VPS and use it to quickly deploy a Drupal site, read this tutorial.

Creating your own Drush command requires three main steps:

1. Creating a file that will store the command declaration and its callback code
2. Declaring the command function
3. Declaring the command callback function (the php functions that will be called by the Drush command to perform the actions)

Step 1: Creating the Command File

The most important thing in this step is giving the right name to the command file and placing it into a folder that Drush will look. That name must end with .drush.inc (in our case it will be publish.drush.inc) and must be placed either in the folder of a custom module on your site (will work for that site if the module is enabled) or in the .drush folder in your server’s root directory.

Also, don’t forget to add the opening php tag at the top of the file.

Step 2: Declaring the Command Function

To declare a new Drush command you have to invoke hook_drush_command() in the file you created above and below the php opening tag. For our example, it will look something like this:

function publish_drush_command() {
  $items = array();
  $items['publish-content'] = array(
    'description' => 'Publish content',
    'aliases' => array('pc'),
    'arguments' => array(
      'type' => 'Nodes of this type will be published',
    ),
  );
  return $items;
}

Note: This command is declared in a file that has been placed in the .drush folder that resides in the VPS’s root folder.

With this function, we are declaring a new command called publish-content (a new key in the $items array) which has a number of characteristics. The description and what’s included in the arguments key is what you will see when you run the drush help publish-content command. What’s actually helpful here is that you can also specify an alias (or shortcut) that can be run instead of the longer publish-content version. In this case, drush publish-content will equal drush pc.

Although there are other stuff you can add here, these are some of the basics you can start with. Please note that you can specify an optional callback function to be called by this command but if you omit it (like we just did), drush_invoke() will generate automatically the function name for the callback.

Step 3: Declare the Command Callback Function

Now comes the interaction with Drupal. With this function, you need to write the code you want Drupal to perform when you run the custom command. The name of the function needs to be in the format: drush_command_name. So for our case, something like this (please note that the dash in the command name becomes an underscore in the function name):

function drush_publish_content($type) {
  $nodes = node_load_multiple(array(), array('type' => $type));
  $count = 0;
  foreach ($nodes as $node) {
    if($node->status == 0) {
      $count++;
      $node->status = 1;
      node_save($node);
    }  
  }
  if($count > 0) {
    drush_print($count . " nodes of the " . $type . " content type have been successfully published.");
  }

  else {
    drush_print("No nodes of the " . $type . " content type were published.");
  }
}

This callback function takes as argument the machine name of the content type of all the nodes we want published. This gets passed as a command argument like so:

drush publish-content article

This command will publish all the nodes of the article content type that are currently unpublished. It does so by loading all the nodes of that type with the node_load_multiple() function and changing the status attribute of those that are 0 to 1. Drush will then print out how many nodes have been published (displaying only the number of nodes that have been in fact affected by the command).

In addition, you can also declare a validation hook to check and display an error if something is not right with the command. This will be called before the command is actually run by Drush. In our case, we can use it to check whether the content type supplied in the command argument actually exists. If not, Drush will throw an error:

function drush_publish_content_validate($type) {
  if(node_type_load($type) === FALSE) {
	return drush_set_error('NON_EXISTENT', dt('There is no content type by that name'));
  }
}

And that’s pretty much it for registering a basic Drush command that will perform some actions on your site. You can also easily duplicate this work to create a reverse unpublish command that will unpublish content in the same way: the sky's the limit!