Drupal → Создание пользовательских команд в Drush

Создать новую команду drush очень легко. Для этого нужно выполнить 4 шага:

1. Создать файл команды с именем в виде COMMANDFILE.drush.inc.
2. Реализовать функцию COMMANDFILE_drush_help() (опционально).
3. Реализовать функцию COMMANDFILE_drush_command().
4. Реализовать функции ассоциированные с вашими командами. Как правило это фунции вида drush_COMMANDFILE_COMMANDNAME().

Пример готовой пользовательской команды с комментариями можно посмотреть в файле examples/sandwich.drush.inc.

Подробнее о каждом шаге читаем ниже.

Создание COMMANDFILE.drush.inc

Имя файла, в котором будет код ваших команд, очень важно. Оно должно заканчиваться на .drush.inc. Всё что идёт до .drush.inc станет системным именем по аналогии с именами модулей. В одном таком файле может быть несколько пользовательских команд.

Например такие команды как pm-enable, pm-disable и pm-info находятся в файле под общим именем pm.drush.inc.

Drush ищет файлы команд в следующих местах:

• В папке /path/to/drush/commands.
• В папках перечисленных в опции include (подробности по команде drush topic docs-configuration).
• В общей системной папке drush, например /usr/share/drush/commands.
• В папке .drush домашней директории текущего пользователя.
• В модулях текущей установки Drupal.

Поэтому созданный файл нужно положить в одно из этих мест.

Здесь следует отметить, что поиск в модулях ведётся только если drush имеет уровень загрузки не ниже DRUSH_BOOSTRAP_SITE, в этом случаем поиск происходит во всех модулях, как включённых так и нет. Однако, как правило при работе с Drupal сайтом, уровень загрузки будет DRUSH_BOOTSTRAP_FULL, и поиск будет происходить уже в папках только включённых модулей. Подробнее смотрите по команде drush topic docs-bootstrap.

Реализация COMMANDFILE_drush_help()

COMMANDFILE_drush_help() это опциональный хук, в котором можно подробно описать одну или несколько команд. Если у команды есть только краткое описание, то этот хук можно опустить и указать описание только в COMMANDFILE_drush_command().

Пример реализации хука из файла examples/sandwich.drush.inc (в нём описывается команда make-me-a-sandwich):

function sandwich_drush_help($section) {
  switch ($section) {
    case 'drush:make-me-a-sandwich':
      return dt('... brief help summary goes here ...');
  }
}

Обратите внимание, что имя команды сопровождается префиксом drush:. Если в файле содержится несколько команд, то просто добавьте по оператору case на каждую из них.

Реализация COMMANDFILE_drush_command()

Хук COMMANDFILE_drush_command() является наиболее важной частью файла. Он возвращает массив элементов, которые определяют как работают ваши команды. Команды в drush очень похожи на систему меню в Drupal. Каждый элемент (команда) может содержать следующие свойства:

• aliases — синонимы команды. У некоторых команд в drush есть синонимы, по которым их можно вызвать, например у команды pm-download это dl и для того чтобы скачать модуль достаточно написать drush dl.

• deprecated-aliases — то же самое что aliases, но не появляется в справке. Используется в тех случаях, когда синоним планируется убрать в будущем. При использовании такого синонима drush будет выводить предупреждение.

• command hook — изменяет название функции, которая будет вызвана для выполнения команды, с drush_COMMANDFILE_COMMANDNAME() на drush_COMMANDFILE_COMMANDHOOK(), где COMMANDNAME это оригинальное название команды, а COMMANDHOOK — значение свойства command hook.

• callback — название функции для выполнения команды. Название должно начинаться с drush_COMMANDFILE_. Это опциональный параметр и предпочтительно его опускать, чтобы drush сгенерировал имя функции самостоятельно в виде drush_COMMANDFILE_COMMANDNAME().

• callback arguments — массив аргументов для передачи в callback функцию. Если у команды есть аргументы описанные в arguments, то аргументы из callback arguments будут добавлены в конец arguments. Параметр используется довольно редко.

• description — описание команды.

• arguments — массив аргументов, которые можно указывать при выполнении команды. Используется только в drush help.

• options — массив опций, которые можно указывать при выполнении команды. Используется только в drush help.

• examples — массив с примерами использования команды. Используется только в drush help.

• bootstrap — уровень загрузки Drupal. Может принимать значения:

  • DRUSH_BOOTSTRAP_DRUSH
  • DRUSH_BOOTSTRAP_DRUPAL_ROOT
  • DRUSH_BOOTSTRAP_DRUPAL_SITE
  • DRUSH_BOOTSTRAP_DRUPAL_CONFIGURATION
  • DRUSH_BOOTSTRAP_DRUPAL_DATABASE
  • DRUSH_BOOTSTRAP_DRUPAL_FULL
  • DRUSH_BOOTSTRAP_DRUPAL_LOGIN
  • DRUSH_BOOTSTRAP_MAX

  Подробности по команде drush topic docs-bootstrap.

• core — массив мажорных версий друпала, под которые написана команда. Например array(6,7).

• drupal dependencies — модули друпала, от которых зависит работа команды. Например array('search', 'simpletest').

• drush dependencies — системные имена файлов команд, от которых зависит работа этой команды, без суффикса .drush.inc. Например array('sql', 'pm', 'core').

• topics — список тем справки, которые связаны с командой. Например array('docs-aliases', 'docs-policy'). Используется только в drush help.

• topic — установите в TRUE, если команда является темой в справке. Вызывается по drush docs-topics.

Пример из файла examples/sandwich.drush.inc:

function sandwich_drush_command() {
  $items['make-me-a-sandwich'] = array(
    'description' => 'Makes a delicious sandwich.',
    'arguments' => array(
      'filling' => 'The type of the sandwich (turkey, cheese, etc.)',
    ),
    'options' => array(
      'spreads' => 'Comma delimited list of spreads (e.g. mayonnaise, mustard)',
    ),
    'examples' => array(
      'drush mmas turkey --spreads=ketchup,mustard' => 'Make a terrible-tasting sandwich that is lacking in pickles.',
    ),
    'aliases' => array('mmas'),
    'bootstrap' => DRUSH_BOOTSTRAP_DRUSH,
  );

  return $items;
}

Все параметры в этом примере, кроме aliases и bootstrap, не влияют на выполнение команды, а используются только при вызове справки с помощью drush help.

Реализация drush_COMMANDFILE_COMMANDNAME()

Вся логика работы команды находится в функции drush_COMMANDFILE_COMMANDNAME() (конечно если имя функции не изменено в COMMANDFILE_drush_command()), где COMMANDNAME это имя команды, в котором знаки тире заменены на подчёркивания. Например функция для команды make-me-a-sandwich, которая определена в файле sandwich.drush.inc выглядит:

function drush_sandwich_make_me_a_sandwich($filling = 'ascii') {
  // code
}

Если пользователь выполняет команду без аргументов — drush make-me-a-sandwich, то drush вызовет функцию drush_sandwich_make_me_a_sandwich() без каких либо параметров. В этом случае параметр $filling примет значение по умолчанию — ascii.

Соответственно при вызове drush make-me-a-sandwich ham, drush выполнит drush_sandwich_make_me_a_sandwich('ham').

Следует знать, что drush вызывает ещё некоторые функции до и после выполнения drush_COMMANDFILE_COMMANDNAME(). Одна из таких функций это хук validate. Пример из файла examples/sandwich.drush.inc:

function drush_sandwich_make_me_a_sandwich_validate() {
  $name = posix_getpwuid(posix_geteuid());
  if ($name['name'] !== 'root') {
    return drush_set_error('MAKE_IT_YOUSELF', dt('What? Make your own sandwich.'));
  }
}

Подробнее смотрите по drush topic docs-policy и drush topic docs-api.

Это перевод официальной документации.

Пример

Простейший пример пользовательской команды echo, которая просто выводит на экран введённый аргумент:

<?php // commands/my/echo.drush.inc

function echo_drush_command() {
  $items['echo'] = array(
    'description' => 'Output some text',
    'arguments'   => array('text' => 'Some text'),
    'examples'    => array('drush echo hello' => 'Output "hello"'),
    'callback'    => 'drush_echo',
    'bootstrap'   => DRUSH_BOOTSTRAP_DRUSH,
  );
  return $items;
}

function drush_echo($text = '') {
  drush_print($text);
}

?>

Видео:
— How to create a custom Drush command (eng).
— Создание собственных команд для Drush (rus).