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

Аннотации можно воспринимать как метаинформацию, описанную в комментах. Аннотации это еще одна новая технология, привнесенная в Drupal 8 версии. Аннотации могут предшествовать объявлению функции или класса.

В Symfony2 используются Аннотации для правил маршрутизации и в Doctrine, описываются метаданные, связанные с ORM. Звучит непонятно, но а самом деле ничего сложного, и быстро привыкаешь.

Аннотации в Drupal 8 используются в системе плагинов.

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

Исследование Плагина.

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

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

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

Самый распространенный тип плагинов это конечно же блоки, но это не единственный тип, плагины также включают:

  • Блоки
  • Форматтеры полей
  • Плагины вьюшек
  • Conditions(Условия видимости)
  • Источники миграции

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

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

Это пример Аннотации класса блока

Менеджер блоков сканирует файлы на наличие тега @Block и обнаруживает экземпляр блока. Это гарантирует доступность пользовательского блока и добавление его в регион. Далее следует объявление идентификатора или машинного имени блока и его админ описание, для отображения в списке интерфейса блоков.

Парсер Аннотации

Аннотации читаются и парсятся во время выполнения при помощи движка(engine) аннотаций. Drupal 8 использует парсер аннотаций Doctrine, который превращает их(аннотации) в объекты, которые затем могут использоваться PHP.

Какой похожий механизм использовался в Drupal 7?

Давайте взглянем на код пользовательского модуля в 7-ке:

<?php
/**
 * 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;
  }
}
?>

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

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

Улучшение производительности

Аннотации используют меньше памяти, чем подход в Drupal 7 и альтернативы D 8.

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

Аннотации tokinised и не используют много памяти. Они только загружаются в память и инстанцинируются тогда, когда этого требует функциональность. Также docblocks кешируется в opcode кеше.

Жизнь в том же файле

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

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

Синтаксис Аннотаций достаточно сильно заимствован из Doctrine, но это не совсем то же самое.

Аннотации состоят из вложенных друг в друга пар ключ-значение и поддерживают вложенности.

@Plugin

Аннотации в комментариях начинаются с @Plugin, где "Plugin" тип подключаемого модуля. В приведенном выше примере @Block использован потому, что аннотация плагина типа блок.

Ключи

Ключи корневого уровня должны либо быть в парных кавычках, либо не иметь кавычек вообще. Общая рекомендация в том, что не ставить кавычки, если имя ключа не содержит пробелы.

В примере оба ключа id и admin_label не имеют кавычек.

Ключи подуровня должны быть в кавычках.

Переводы

Строки с переводами должны быть обернуты в @Translation().

Значения

  • Строки - двойные кавычки
  • Списки - фигурные скобки
  • Кавычки в строке: используйте двойные кавычки
  • maps - используем фигурные скобки и знак равенства при отделении ключ=значение
  • Булев - TRUE и FALSE без кавычек
  • Цифры - без кавычек

Резюме

  • Большинство хуков info заменены аннотациями
  • Синтаксис заимствован из Doctrine
  • Может использоваться для различных целей, но в Drupal 8 используется для системы плагинов.
  • Находится в том же файле, где и класс, который реализует плагин, поэтому легче найти.
  • Использует меньше памяти чем методы Drupal 7 и raw PHP альтернативы в Drupal 8

Share this post

Leave a comment

Filtered HTML

  • Web page addresses and e-mail addresses turn into links automatically.
  • Allowed HTML tags: <a> <em> <strong> <cite> <blockquote> <code> <ul> <ol> <li> <dl> <dt> <dd>
  • To post pieces of code, surround them with <code>...</code> tags. For PHP code, you can use <?php ... ?>, which will also colour it based on syntax.
  • Lines and paragraphs break automatically.

Plain text

  • No HTML tags allowed.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Lines and paragraphs break automatically.