Drupal PostInstall — модуль, позволяющий другим модулям «настраиваться» после установки

Как известно, некоторым модулям (таким как Google Analytics например) необходима некоторая начальная настройка, прежде чем они смогут хоть как-то функционировать. Кроме того, иногда, приходится сталкиваться с ситуацией, когда еще при установке модуля требуется узнать от пользователя какую-то информацию. Конечно, Drupal позволяет в каждом конкретном случае сделать все это с помощью механизма хуков. Однако, я решил, что будет лучше иметь некий унифицированный способ, интерфейс для решения данной задачи. Для этих целей и был написан небольшой сервис-модуль под названием PostInstall.

Что такое?

Суть модуля заключается в следующем. Он позволяет другим модулям выводить свои страницы настройки сразу после установки. Модуль отлично справляется с установкой нескольких модулей зараз и отображает страницы конфигурации строго в соотвествии с зависимостями (зависимый модуль настраивается перед зависящим). Кроме того, модуль корректно работает и в случае если сам устанавливается вместе с модулями требующими настройки. В случае, если на каком-то шаге пост-настройка была прервана, пользователь будет возвращен к ней при следующем посещении страницы модулей (admin/modules). Настройка продолжиться с момента завершения.

Как работает?

Работает до безобразия просто. После установки модулей, PostInstall проверяет, есть ли в списке установленных модули, которым требуется пост-настройка. В случае, если таковые имеются, после завершения установки пользователь переносится в мастер настройки. Форма настройки для каждого модуля представляет отдельный этап работы мастера. Пользователю показывается на каком этапе он сейчас (какой модуль настраивается в данный момент) и сколько этапов всего. После завершения настройки пользователь возвращается на страницу admin/modules.

Как реализовать?

Для того чтобы позволить своему модулю настраиваться после установки, необходимо:

1. Поставить его в зависимость от модуля postinstall (добавить в файл modulename.info строчку «dependencies[] = postinstall»).
2. Реализовать в модуле hook_postinstall().

Ниже привожу руссифицированную версию файла postinstall.api.php с русифицированным описанием и примером как реализовать hook_postinstall().

/**
 * Хук позволяет модулям сразу после установки отображать
 * и обрабатывать собственные страницы настройки.
 * 
 * @param $action
 *   Принимает одно из следующих значений:
 *   - form: Необходимо вернуть обычный массив элементов формы как в drupal_get_form().
 *     В массиве вы НЕ должны возвращать никаких элементов типа submit. Модуль
 *     добавит кнопку отправки формы автоматически.
 *   - validate: Здесь вы можете проверить значения переданные в параметре $values
 *     и вернуть ошибки в масссиве $error_messages, если таковые возникнут. 
 *     $error_messages - это массив с следующими обязательными ключами:
 *     - name: Имя элемента формы (как в form_set_error()).
 *     - message: Сообщение об ошибке, которое будет показано пользователю.
 *   - submit: Submit callback вашей формы. Здесь вы можете сделать что-то с $values.
 * @param $values
 *   Значений которые должны быть проверены (если $action == 'validate') или отправлены
 *   (если $action == 'submit').
 */
function hook_postinstall($action, $values = array()) {
  switch ($action) {
    case 'form':
      $form = array();
      $form['test'] = array(
        '#type' => 'textfield',
        '#title' => 'Test textfield'
      );
      return $form;
      break;
    case 'validate':
      $error_messages = array();
      if (!is_numeric($values['test'])) {
        $error_messages[] = array(
          'name' => 'test',
          'message' => t('Переведенное сообщение об ошибке')
        );
      }
      return $error_messages;
      break;
    case 'submit':
      drupal_set_message($values['test']);
      break;
  }
}

Официальная страница проекта на Drupal.Org: drupal.org/project/postinstall
Репозиторий на GitHub: github.com/numesmat/drupal-postinstall (могу внезапно начать забывать обновлять)