Былина о том, как я Drupal и Яндекс.ПДД связывал

Некоторое время назад у меня была идея сделать городской сайт (естественно, очередной) для одного небольшого городка на базе Drupal. Как раз незадолго до этого Яндекс расширил функционал своей Почты для доменов и добавил возможность управлять ящиками через API. И в голове зародилась мысль: а почему бы и нет? Почему бы не предоставить пользователям возможность одновременно с регистрацией на городском портале получать почтовый ящик в городском домене? Сама по себе идея, конечно, не удивительна, однако готовых решений не было. Сайт я так и не запустил, а коду без дела лежать грех.

Как известно, Drupal позиционируется как CMS, ориентированная разработчиков и позволяющая благодаря обширной API разработать хоть систему для управления лунной базой. Я не буду вдаваться в своём посте в её восхваление и самые начальные основы разработки модулей под Drupal, однако начинающие Drupal-разработчики наверняка сочтут материал полезным, а опытным буду благодарен за советы и рекомендации.

Постановка задачи

Естественно, приступая к написанию модуля, нужно решить, каким функционалом он будет обладать. Модуль рассчитан на социальный сайт, где смогут регистрироваться пользователи. Следовательно, он должен:

• при регистрации пользователя предлагать ему возможность создать ящик на Яндексе;
• при подтверждении регистрации инициировать создание ящика;
• отображать авторизированному пользователю блок с информацией о количестве новых писем и возможностью перейти в ящик;
• создавать админ-часть для ввода необходимых параметров.

Конечно, можно было бы добавить ещё какие-нибудь плюшки (например, изменять пароль к ящику при изменении пароля в нашей системе, редактировать пользовательские данные, управлять переадресацией), но это скорее излишества.

.info-файл

Любой модуль Drupal должен содержать .info-файл со служебной информацией о модуле. Минимальный набор — название модуля, краткое описание и версия ядра, для которой он написан. Но в нашем случае необходимо указать ещё одно поле — зависимости. В логике модуля заложено создание ящиков, логин которых совпадает с логином пользователя. Но чтобы не лишать пользователей возможность создавать кириллические логины и не удивлять ими Яндекс, нам нужен модуль транслитерации. Таким образом, файлик yandex_pdd.info у нас будет выглядеть следующим образом:

name = Yandex PDD
description = Yandex PDD mailboxes autocreation.
core = 7.x
dependencies[] = transliteration

Естественно, перед установкой модуля нужно не забыть установить у себя этот самый transliteration.

Файл установки и удаления

Ещё один обязательный файл — .install (в нашем случае — yandex_pdd.install), который определяет используемые модулем базы данных и необходимые действия при установке и удалении модуля. Для работы нам понадобится одна база данных и две переменных. Для начала определим структуру базы (хук hook_schema())

function yandex_pdd_schema() {
  $schema['yandex_pdd'] = array(
    'fields' => array(
      'id' => array('type' => 'serial', 'not null' => TRUE), // Идентификатор строки
      'uid' => array('type' => 'int', 'unsigned' => TRUE, 'not null' => TRUE, 'default' => 0,), // Идентификатор пользователя
      'login' => array('type' => 'varchar', 'length' => 100, 'not null' => TRUE), // Транслитерированный логин для создания ящика
      'activated' => array('type' => 'varchar', 'length' => 1, 'not null' => TRUE) // Флаг активации ящика
    ),
   'primary key' => array('id'),
  );
  return $schema;
}

Первые две колонки, думаю, вопросов не вызывают. В третью колонку мы будем записывать логин самого электронного ящика. Четвёртую колонку стоит разобрать отдельно. В CMS Drupal для активации пользователя необходимо, чтобы он перешёл по ссылке, присланной ему на e-mail, и задал свой пароль. Известный факт, что часть учётных записей никогда не будет активирована (часть спам-ботов и просто странные люди), потому создавать ящик имеет смысл, когда пользователь задаёт новый пароль. Собственно, это заодно позволяет нам создать ящик с этим же паролем. Данный вопрос я ещё затрону ниже.

При удалении модуля описанные в схеме базы удаляются автоматически. А вот переменные, закешированные данные и т.п. следует за собой убрать с помощью hook_uninstall().

function yandex_pdd_uninstall() {
  variable_del('yandex_pdd_domain');
  variable_del('yandex_pdd_authtoken');
  cache_clear_all('yandex_pdd','cache',TRUE);
  menu_rebuild();
}

Параметры yandex_pdd_domain и yandex_pdd_authtoken задают домен, в котором будут создаваться ящики, и API-ключ соответственно. Расскажу о них подробнее немного позже.

Необходимый фундамент для работы модуля заложен, и мы можем приступать к написанию самого кода модуля. Храниться он у нас будет, как и полагается, в файле с расширением .module (yandex_pdd.module).

Элементы меню

Если модулю Drupal необходимо прописываться в меню, создавать какие-либо страницы и т.п., нам нужно описать всю структуру и необходимые действия при переходе по ссылкам с помощью хука hook_menu(). В нашем случае будет использоваться два URL-а: страница настройки модуля и переадресация в почтовый ящик.

function yandex_pdd_menu(){
	$items = array();
 
	$items['admin/config/content/yandex_pdd'] = array( // Ключ массива - системный путь к странице
		'title' => t('Yandex PDD'), // <title> страницы
		'page callback' => 'main_config', // Функция, которая отвечает за генерацию страницы
		'type' => MENU_NORMAL_ITEM, // Способ подвязки страницы в систему меню CMS
		'access callback' => TRUE, // Определяет возможность доступа к странице
	);
 
	$items['mailbox'] = array(
		'title' => 'Yandex PDD login',
		'page callback' => 'mailbox_login',
		'type' => MENU_CALLBACK, 
		'access callback' => TRUE, 
	);

	return $items;
}

Обратите внимание на использование системной функции t(). Она позволяет переводить элементы текста на текущий системный язык. И да, на странице mailbox нам такая возможность не понадобится.

Страница настройки

В предыдущем разделе мы рассказали нашей CMS, что страница для ввода необходимых модулю данных будет размещаться по пути admin/config/content/yandex_pdd и обрабатываться функцией main_config. Собственно, CMS на самом деле не в курсе, чем конкретно будет заниматься страница, но знает, что при обращении по данному пути нужно обратиться к данной функции.

function main_config(){
	$form = drupal_get_form('pdd_config_form'); // Получаем поля формы
	$form = drupal_render($form); // Рендерим форму
	return $form;
}

Для создания страницы мы получаем друпалопонятный массив полей формы обращением системной функции drupal_get_form() к пользовательской функции pdd_config_form.

function pdd_config_form($form, &$form_state){
	$form=array();
	$form['pdd_domain'] = array( // Ключ массива - имя поля в форме
		'#type'	=> 'textfield', // Тип поля
		'#title' => t('Domain zone'), // Название поля, понятное пользователю
		'#description' => t('A domain zone in which email should be created.'), // Описание поля
		'#default_value' => variable_get('yandex_pdd_domain'), // Значение по умолчанию
		'#required' => 1, // Флаг обязательности
	);
	$form['authtoken'] = array(
		'#type'	=> 'textfield',
		'#title' => t('Auth Token'),
		'#description' => t('Authorization token obtained at Yandex.PDD service.'),
		'#default_value' => variable_get('yandex_pdd_authtoken'),
		'#required' => 1,
	);
	$form['submit'] = array(
		'#type' => 'submit',
		'#value' => t('Submit'),
	);
	return $form;
}

Результат передаётся функции drupal_render(), которая собирает массив в готовый html-код страницы.

Форма содержит всего два поля:

• pdd_domain — подвязанный к Яндекс.ПДД домен, в котором будут создаваться ящики;
• authtoken — авторизационный токен, полученный в настройках API Почты для домена.

Естественно, результаты заполнения формы нам необходимо сохранить. За это отвечает функция pdd_config_form_submit, которая просто сохраняет значения полей в системные переменные.

function pdd_config_form_submit($form, &$form_state){
	variable_set('yandex_pdd_domain', $form_state['values']['pdd_domain']);
	variable_set('yandex_pdd_authtoken', $form_state['values']['authtoken']);
}

Ещё небольшой кусочек кода — реализация хука hook_help(), который выводит справочную информацию о модуле в соответствующем разделе админ-части. По поводу этой функции я не заморачивался и пошёл по пути минимализма.

function yandex_pdd_help($path, $arg) {
   switch ($path) {
     case "admin/help#yandex_pdd":
       return '<p>'. t("Yandex PDD mailboxes management module.") .'</p>';
       break;
   }
}

С административной частью разобрались. Пора заняться пользовательской, весь функционал которой можно разделить на этап создания и этап работы.

Создание ящика

Не всем нашим пользователям может понадобиться ещё один e-mail, пусть даже и в домене любимого сайта. Да и нам ни к чему плодить огромное количество неиспользуемых ящиков. Потому мы добавим в форму регистрации пользователя чекбокс, который позволит ему выбирать, создавать ящик или нет. Любую форму в Drupal можно изменить с помощью hook_form_alter(). С назначением некоторых элементов массива описания формы мы уже знакомы. Подробнее со всеми остальными можно познакомиться на справочной странице по формам.

function yandex_pdd_form_alter(&$form, &$form_state, $form_id){
	if($form_id=='user_register_form'){ // Идентификатор изменяемой формы
		$form['account']['createmail']=array( // Имя дополнительного поля
			'#type' => 'checkbox',
			'#title' => t('Create a mailbox'),
			'#description' => t('Check this box if you want to create a mailbox @'.variable_get('yandex_pdd_domain').'.'),
			'#required' => 0,
			'#access' => 1, // Доступно ли поле пользователям
			'#weight' => 10 // Вес (критерий сортировки)
		); 
	}
}

Много текста для одного маленького чекбокса.

При регистрации пользователя мы проверяем, отмечен ли чекбокс создания ящика в форме, и если да, вносим в таблицу данные о неактивном ящике.

function yandex_pdd_user_insert(&$edit, $account, $category){
	if($account->createmail){
		$transliterated = transliteration_get($account->name, '_'); // Транслитерируем логин
		$pattern = '/[^a-zA-Z0-9]/'; // Задаём шаблон для замены всего, кроме букв и цифер 
		$transliterated = preg_replace($pattern, '-', $transliterated); // Заменяем все не alphanumeric знаки на дефисы
		$newbox = db_insert('yandex_pdd'); // Инициируем вставку в базу данных
		$newbox->fields(array('uid' => $account->uid, 'login' => strtolower($transliterated), 'activated' => '0')); // Задаём данные для вставки
		$res = $newbox->execute(); // Выполняем запрос
		watchdog('yandex_pdd',print_r('Res: '.$res,1)); // Для отладки записываем в системный журнал CMS результат 
	}
}

Создание ящика подвязано к изменению формы с пользовательскими данными хуком hook_field_attach_submit(). Таким образом, до того, как пользователь впервые произведёт редактирование данных (изменение пароля), ящик не создаётся.

function yandex_pdd_field_attach_submit($entity_type, $entity, $form, &$form_state) {
	global $user;
	if($entity_type == 'user' and $user->uid > 0) { // Обработка при изменении сущности типа user
		$select = db_select('yandex_pdd','ypdd');
		$select->addField('ypdd', 'id');
		$select->addField('ypdd', 'login');
		$select->addField('ypdd', 'activated');
		$select->condition('uid', $user->uid);
		$entries = $select->execute()->fetchAssoc(); // Получаем логин для ящика и статус активации
		if (array_key_exists('login', $entries) and $entries['login'] != '' and $entries['activated'] == 0) { // Если пользователю нужен ящик и он не создан
			$mailboxcreate = simplexml_load_file('https://pddimp.yandex.ru/reg_user_token.xml?token='.variable_get('yandex_pdd_authtoken').'&u_login='.$entries['login'].'&u_password='.$form["#user"]->pass); // Создаём ящик и парсим XML-ответ
			if ($mailboxcreate->ok[0]) { // Если создался
				$num_updated = db_update('yandex_pdd');
				$num_updated->fields(array('activated' => '1'));
				$num_updated->condition('uid', $user->uid);
				$res = $num_updated->execute(); // Отмечаем флаг активации ящика
			} elseif ($mailboxcreate->error[0]) { // Если ошибка API
				foreach($mailboxcreate->error[0]->attributes() as $key => $value) {
					$mbc[$key] = (string)$value;
				}
				watchdog('yandex_pdd',"Can't create new mailbox. Reason: ".$mbc['reason']); // Записываем в лог сообщение
			} else { // Если вообще неясно что случилось
				watchdog('yandex_pdd','Unknown error while creating mailbox.'); // Так и запишем
			}
		}
	}
}

Наконец-то наш пользователь получил ящик, хотя не особо знает, как туда попасть. Осталось реализовать функционал перехода на почту.

Рабочий функционал

Собственно, пользовательских функций всего две: отобразить блок и авторизироваться на почте. Блок нужно в первую очередь описать хуком hook_block_info()

function yandex_pdd_block_info() {
  $blocks['mailbox_status'] = array( // Системное имя блока
    'info' => t('Mailbox status'), // Административное название блока
    'cache' => DRUPAL_CACHE_PER_ROLE, // Режим кеширования
  );
  return $blocks;
}

Для блока нам ещё понадобится задать темизацию и файл с шаблоном оформления. Темизация описывается хуком hook_theme(), описывающим системе реализацию оформления элементов модуля.

function yandex_pdd_theme() {
    return array(
        'yandex_pdd_block' => array( // Системное имя шаблона
            'variables' => array( // Используемые шаблоном переменные
                'newmail' => NULL
            ),
            'template' => 'yandex-pdd-block', // Имя файла шаблона
        )
    );
}

И, собственно, сам файл yandex-pdd-block.tpl.php.

<div class="yandexpdd"><?php print t('You have ').'<a href="/mailbox" target="_blank">'.$newmail.t(' new messages').'</a>.'; ?></div>

Для блока нам нужно получить по API одно-единственное значение — количество новых писем, после чего отрендерить сам блок хуком hook_block_view()

function yandex_pdd_block_view($delta = '') {
	global $user;
	if ($user->uid > 0) { // Проверяем, авторизирован ли пользователь
		$select = db_select('yandex_pdd','ypdd');
		$select->addField('ypdd', 'login');
		$select->condition('uid', $user->uid);
		$entries = $select->execute()->fetchAssoc(); // Получаем логин ящика
		$unreadmailxml = simplexml_load_file('https://pddimp.yandex.ru/get_mail_info.xml?token='.variable_get('yandex_pdd_authtoken').'&login='.$entries['login']); // Получаем от Яндекса информацию о ящике
		if ($unreadmailxml->ok[0]) { // Если запрос успешен
			foreach($unreadmailxml->ok[0]->attributes() as $key => $value) { // Парсим ответ
				$unreadmail[$key] = (string)$value;
			}
			$blocks = array();
			$blocks['subject'] = null;
			$blocks['content'] = theme('yandex_pdd_block', array('newmail' => $unreadmail['new_messages']));
			return $blocks; // Возвращаем блок
		} elseif ($unreadmailxml->error[0]) {
			foreach($unreadmailxml->error[0]->attributes() as $key => $value) {
				$unreadmail[$key] = (string)$value;
			}
			watchdog('yandex_pdd',"Can't get new mail info. Reason: ".$unreadmail['reason']);
		} else {
			watchdog('yandex_pdd','Unknown error while loading new mail info');
		}
	}
}

Сгенерированный блок будет выглядеть примерно так.



Завершающий штрих — системная ссылка mailbox, которая будет перебрасывать пользователя на страницу Яндекс.Почты и авторизировать по одноразовому токену. Как мы помним (или уже не помним), мы ранее задали, что эта ссылка должна обрабатываться функцией mailbox_login. Время жизни токена всего 30 секунд, потому после его получения пользователь тут же должен быть переадресован на страницу авторизации.

function mailbox_login(){
	global $user;
	global $base_url;
	if ($user->uid > 0) {
		$select = db_select('yandex_pdd','ypdd');
		$select->addField('ypdd', 'login');
		$select->condition('uid', $user->uid);
		$entries = $select->execute()->fetchAssoc();
		$tokenxml = simplexml_load_file('https://pddimp.yandex.ru/api/user_oauth_token.xml?token='.variable_get('yandex_pdd_authtoken').'&domain='.variable_get('yandex_pdd_domain').'&login='.$entries['login']); // Получаем одноразовый токен авторизации
		if ($tokenxml->xpath('status/success')) {
			$tokenarr = $tokenxml->xpath('domains/domain/email/oauth-token');
			header('Location: http://passport.yandex.ru/passport?mode=oauth&type=trusted-pdd-partner&error_retpath='.urlencode($base_url.'/').'&access_token='.(string)$tokenarr[0]); // Перебрасываем пользователя на Яндекс.Почту
			drupal_exit(); // Прекращаем любые другие действия CMS
		} elseif ($tokenxml->xpath('status/error')) {
			watchdog('yandex_pdd',"Can't get short-term auth token info. Reason: ".(string)$tokenxml->xpath('action/status/error'));
		}
	}
}

Заключение

Тут и сказу конец. Размещённые куски кода, собранные в соответствии с указанными именами файлов, должны дать Вам готовый модуль. Надеюсь, кому-то он будет полезен, и с удовольствием выслушаю замечания и рекомендации по коду.