We are about to create the file where our command will reside. It is important that we carefully follow the structure COMMANDFILE.drush.inc so that Drush can discover it, and also that think about a good name for COMMANDFILE as Drush will use this part of the filename to invoke the callback function that will actually do the processing.

Custom Drush command files can be placed in several locations in our system:

For this scenario, we will go with the last option. We will create a file with the filename user_blocker.drush.inc inside the .drush folder within our home path (for example, at /home/juampy/.drush/user_blocker.drush.inc). This file has a hook for defining the command properties and a callback function that actually does the processing. The first part defines the command properties, such as the command description, examples, arguments, and options:

<?php
/**
* @file
* Blocks users with no activity in a period of time
*/
/**
* Implementation of hook_drush_command().
*/
function user_blocker_drush_command() {
$items['user-blocker'] = array(
'description' => 'Blocks user accounts with no activity in a period of time.',
'aliases' => array('ub'),
'examples' => array(
'drush user-blocker' => 'Blocks user accounts who did not log in in the last two years.',
'drush user-blocker en es' =>
'Blocks user accounts who did not log in in the last two years whose default language is English or Spanish.',
'drush user-blocker --since="two months ago" es' => 'Blocks user accounts which have Spanish as their default language and an account age ' .' of more than two months without activity.',
),
'bootstrap' => DRUSH_BOOTSTRAP_DRUPAL_FULL,
'arguments' => array(
'languages' => 'A list of languages to filter user accounts.',
),
'options' => array(
'since' =>
'Specifies last time a user account should have logged in ' .
'so it won't get blocked. Defaults to 2 years ago. Accepts ' .
'all date formats described at ' .
'http://www.php.net/manual/en/dtetime.formats.php.show.',
),
);
return $items;
}

The second part implements the command callback. It first gathers arguments and options and then performs the SQL query to block users:

/**
* Callback implementation for user-blocker command
*/
function drush_user_blocker() {
// Grab all languages given. If any.
$languages = func_get_args();
// See if we received a date from which we should filter
$since = strtotime(drush_get_option('since', '2 years ago'));
// Perform the update over the users table
$query= db_update('users')
->fields(array('status' => 0,))
->condition('uid', array(0, 1), 'NOT IN')
->condition('access', array(1, $since), 'BETWEEN'),
// Add the condition to filter by language
if (count($languages)) {
$query->condition('language', $languages, 'IN'),
}
$total_blocked = $query->execute();
drush_log(dt("Blocked !total_blocked users", array('!total_blocked' => $total_blocked)), 'success'),
}

Save the file. Let's verify that the command was loaded by reading its help information in the main Drush help:

$ drush help
...
Other commands: (userblocker)
user-blocker (ub) Blocks user accounts with no activity

Our command is listed at the end of the output. This is fine for just one command, but if you define many commands and they do not fit in any of the existing categories, you can classify it within the drush help output by implementing hook_drush_help(). More information about this hook can be seen by executing drush topic docs-examplecommand. Now let's see the detailed description of our command:

$ drush help user-blocker
Blocks user accounts with no activity
Examples:
drush user-blocker Blocks user accounts who did not log in in the last two years.
drush user-blocker en es Blocks user accounts who did not log in in the last two years and whose default language is English or Spanish.
drush user-blocker Blocks user accounts which have Spanish --since="two months ago" es as their default language and an account age of more than two months without activity.
Arguments:
roles of roles. Note that you have to wrap a role between quotes if it has a space in its name.
Options:
--since Specifies the date that marks the last time a user account should have logged in so it wont get blocked. Defaults to 2 years ago. Accepts all date formats described at http://www.php.net/manual/en/ datetime.formats.php.show.
Aliases: ub

The previous information is extracted from the first hook implemented at the command file: hook_drush_command(). It shows its basic description, examples, arguments, options, and command aliases.

When writing commands, keep an eye at the Drush API as it describes a lot of functions that will be very useful for your scripts http://api.drush.org/api/functions.

Following is how we can quickly test our command before studying its implementation:

$ drush user-create user1
$ drush sql-query "update {users} set access=1 where name = 'user1';"
$ drush user-blocker
Blocked 1 users.

Now we are going to analyze the source code of our command to understand how it works and then improve it.

The first function defined contains the implementation of hook_drush_command(). This hook is used to tell Drush about commands implemented in the file. They are defined as a keyed array; the key of each element being the command name. Following is a description of each of the properties defined within the key user-blocker:

There are other important options not defined in our command, such as:

After a quick look at the code of our callback function, we can see that apart from drush_get_option() and drush_print() the rest is day-to-day Drupal code. This is good news because it means that we can use the Drupal APIs within our command when a Drupal site is bootstrapped. So far, the code is very simple and it just grabs the list of languages, calculates the date of the last time a user must have logged in, and finally performs a SQL query to block user accounts, which match the criteria. Let's set a user with Spanish as default language; an old last access date and then test our command again:

$ drush sql-query "update {users} set status=1, access=1,  language='es' where name = 'user1';"
$ drush user-blocker es
Blocked 1 users.

The previous command blocked one user account that also matched to Spanish as its default language. Languages are grabbed in the command at the following lines as an array and then added to the SQL query:

// Grab all languages given
$languages = func_get_args();

Drush provides the command drush_get_option() to catch options if they are given. Let's first see a working example and then examine the code. We will set the last access date of our test user account to one hour ago and run the command again:

$ drush sql-query "update {users} set status=1, 
access=(unix_timestamp() - 3600) where name = 'user1';"
$ drush user-blocker --since="1 hour ago" es
Blocked 1 users.

The previous command blocked the account as we changed the default last access date from two hours to one with the --since option.

Options and arguments can be used together as we saw in Chapter 1, Installation and Basic Usage. Following is a command example of how we could block user accounts, which last accessed the site more than a year ago, and have Spanish, English, or French as their default language. We will also use the command alias that we defined:

$ drush ub --since="1 year ago" es en fr

As you can see, options and arguments provide higher flexibility so our commands can cover the widest range of scenarios. In the next section, we will validate them.

We are assuming that all the arguments and options given through the command line are safe and valid, but in order to make our command robust we have to validate the input. We will implement drush_hook_COMMAND_validate() to add some logic that ensures that the options and arguments given are valid. Add the following code below userblocker_drush_command() in the file userblocker.drush.inc:

/**
* Implementation of drush_hook_COMMAND_validate()
*/
function drush_userblocker_user_blocker_validate() {
// Validates language arguments if they were given
$languages = func_get_args();
if (count($languages)) {
$languages = array_unique($languages);
$valid_languages = array_intersect( $languages, array_keys(language_list()));
if (count($languages) != count($valid_languages)) {
return drush_set_error('INVALID_LANGUAGE', dt( 'At least one of the languages given does not exist.'));
}
}
// Validates if a valid date was given
if (drush_get_option('since')) {
if (!strtotime(drush_get_option('since'))) {
return drush_set_error('INVALID_SINCE_DATE', dt( 'The date given as --since option is invalid.'));
}
}
}

The previous code validates the languages and date given. Note that the function name follows the format that we explained before: hook is the name of our command file (userblocker), and COMMAND is the name of our command using underscores instead of dashes (user_blocker). We added some logic to make sure that all languages provided exist in our site (in case the user misspelled one of them) and that the date provided in the --since option is a valid date that can be converted to a timestamp through strtotime(). If any of this validations failed then we set an error by calling to drush_set_error(), which will stop the execution and print a message. Drush can translate strings (such as the error descriptions) using the function dt(), which is a wrapper for the well know t() function from Drupal. Now we will test our command to verify that it validates user input:

$ drush user-blocker --since="nonsense date"
The date given as --since option is invalid [error]
$ drush user-blocker en es
At least one of the languages given do not exist [error]
$ drush user-blocker --since="1970" en
Blocked 0 users [success]

First, we executed the command with a string date that cannot be converted to a timestamp, hence we did not pass validation. Then we attempted to block user accounts with English and Spanish as their default languages, but the fact is that Spanish language has not been enabled nor the Locale module so again an error was reported. We finally verified that the command works as expected by giving it a valid language and a valid date, which returned a success message although we did not block any user account.