Drupal 8. Введение в аннотации

Аннотации – это еще одна из новых концепций в Drupal 8. Аннотации пишутся как комментарии к коду PHP над классом или функцией и содержат метаданные о функции или классе.

Аннотации используются другими проектами PHP. Например, Symfony2 использует аннотации для правил маршрутизации, а Doctrine использует их для метаданных, связанных с ORM.

Аннотации, используемые системой плагинов D8

В своем нынешнем виде аннотации используются только системой плагинов в Drupal 8. Они предоставляют механизм, для которого плагины обнаруживаются Drupal, и описывают их метаданные.

Открытие плагина

Одним из основных концептуальных изменений в Drupal 8 является то, что Drupal не знает о вашем коде, пока вы специально не сообщите ему о своем коде.

При разработке модуля вы рассказываете Drupal о модуле в файле info.yml. Вы говорите Drupal о конкретных маршрутах в файлах маршрута YAML. Вы сообщаете Drupal, какие ссылки меню добавить в систему меню в файлах меню YAML. Аннотации – это похожая концепция для плагинов. Вместо того, чтобы иметь файл YAML для каждого плагина, у вас есть аннотация, и Drupal автоматически найдет (обнаружит) плагин.

Примеры типов плагинов

Блоки – самый распространенный тип плагинов в Drupal 8. Но они ни в коем случае не являются единственным типом. Плагины включают в себя:

  • Блоки
  • Полевые форматеры
  • Плагины представлений
  • Миграции

Для получения дополнительной информации о плагинах на основе аннотаций Drupal.org.

Пример аннотации

Вот краткий пример аннотации для класса блока:

/**
* Provides a 'Welcome' Block
*
* @Block(
* id = "welcome_block",
* admin_label = "Welcome block",
* )
*/

Менеджер блоков сканирует файлы в поисках тега аннотации @Block, чтобы найти экземпляры блоков.
Аннотация @Block гарантирует, что менеджер блоков обнаружит этот пользовательский блок и сделает его доступным для добавления в регион. Идентификатор welcome_block – это машинное имя, а admin_label (блок Hello) появится в списке блоков.

Анализатор аннотаций

Аннотации читаются и анализируются во время выполнения механизмом аннотаций. Drupal 8 использует анализатор аннотаций Doctrine, который превращает его в объект, который может использовать PHP.
Как это отличается от Drupal 7?
В Drupal 7 метаданные живут в информационных хуках.
Давайте посмотрим на пользовательский блок в Drupal 7:

/**
* Implements hook_block_info().
*/
function first_module_block_info() {
$blocks = array();
$blocks['first_block'] = array(
'info' => t('First block'),
'cache' => DRUPAL_NO_CACHE,
);
return $blocks;
}
/**
* Implements hook_block_view().
*/
function first_module_block_view($block_name = '') {
if ($block_name == 'first_block') {
$content = variable_get('first_block_content', 'Some content');
$block = array(
'subject' => t('Sample block'),
'content' => t(‘Sample block content’),
);
return $block;
}
}

Блок зарегистрирован в Drupal как first_module_block_info (), которая реализует hook_block_info (). Без этого Drupal не знал бы, что блок существует, и он не появился бы на экране.
Проблема этого подхода заключается в том, что файлы .module необходимо читать и хранить в памяти во время выполнения, используя большой объем памяти.

Преимущества аннотаций

  • Улучшение производительности
  • Аннотации используют меньше памяти, чем способ D7 и альтернативы в D8.

В Drupal 7 файл каждого модуля .module считывается в память для каждого запроса. В Drupal 8 альтернативой аннотациям является наличие метода getInfo для каждого класса плагинов. Но это означает, что класс должен быть загружен в память, чтобы получить эту
информацию, и память не освобождается до конца запроса. Это увеличивает количество необходимой памяти.
Аннотации являются токенизированными и не занимают столько памяти. Они загружаются в память и создаются только тогда, когда требуется их функциональность. Кроме того, докблоки кешируются с помощью кеша операции.

В одном файле

Аннотации находятся в том же файле, что и класс, реализующий плагин, поэтому их легче найти.

Синтаксис аннотации Drupal

Синтаксис аннотаций в Drupal сильно заимствован из доктрин (но это не совсем то же самое).
Аннотации состоят из вложенных пар ключ-значение и поддерживают вложение.
@Plugin
Комментарий к аннотации должен начинаться с @Plugin, где «Plugin» – это тип плагина. В приведенном выше примере, @Block был использован, потому что аннотация для плагина типа блока.

Ключи

Ключи на корневом уровне должны иметь либо двойные кавычки, либо вообще не иметь кавычек. Общая рекомендация – пропускать кавычки, если имя ключа не содержит пробелов.
В приведенном выше примере блока есть два ключа: id и admin_label . Ни у одного из них нет кавычек.
Ключи подуровня должны использовать двойные кавычки.

Переводимый текст

Переводимые строки должны быть заключены в @Translation ().

Статья была полезной? Поделитесь с друзьями!
Метки: ,