Drupal 10 : Les annotations

Une partie des hooks déclaratifs de Drupal 7 ont disparu avec Drupal 8 (les hook_quelque_chose_info() par exemple). Certains ont été remplacés par l’utilisation des fichiers YAML (hook_menu() ou hook_permission()). Pour d’autres, c’est le principe d’annotations qui a été choisi.

Une annotation est un concept de programmation permettant d’ajouter des méta-données à une structure à l'aide d'un code descriptif. Avec PHP, cela passe par l’utilisation des Docblocks. Les annotations sont pour le moment essentiellement utilisées par les plugins, elles sont à placer juste avant la déclaration de la classe du plugin.
Voilà à quoi ressemble la déclaration d’un bloc depuis Drupal 8 :

# Plugin/Block/CustomBlock.php
/**
 * Declare a block.
 *
 * @Block(
 *   id = "custom_block",
 *   admin_label = @Translation("Custom block"),
 * )
 */

La déclaration du même block en Drupal 7 passait par un hook_block_info().

/**
 * Implements hook_block_info().
 */
function mymodule_core_block_info() {
  $blocks['custom_block'] = array(
    'info' => t('Custom block'),
  );
}

Bien que les annotations soient des Docblocks leur syntaxe est précise et cela pourra entraîner des erreurs si elle n’est pas valide. Une annotation est composée du nom de la classe définissant l’annotation précédé d’un @ et d’un ensemble de clés / valeurs.

Il existe quelques règles concernant les valeurs, il faut retenir que :

• les chaînes doivent être entre guillemets : “chaînes”
• les nombres tel quel : 42
• les listes sont représentées par des accolades : { }
• les booléens par : TRUE ou FALSE

Il est possible de connaître l'ensemble des propriétés d'une annotation en regardant la classe qui définie cette annotation. Par exemple, l’annotation @Block est définie dans la classe \Drupal\Core\Block\Annotation\Block se trouvant dans le fichier /core/lib/Drupal/Core/Block/Annotation/Block.php.

# Block.php
class Block extends Plugin {
  /**
   * The plugin ID.
   *
   * @var string
   */
  public $id;
  /**
   * The administrative label of the block.
   *
   * @var \Drupal\Core\Annotation\Translation
   *
   * @ingroup plugin_translatable
   */
  public $admin_label = '';

  /**
   * The category in the admin UI where the block will be listed.
   *
   * @var \Drupal\Core\Annotation\Translation
   *
   * @ingroup plugin_translatable
   */
  public $category = '';

  /**
   * Class used to retrieve derivative definitions of the block.
   *
   * @var string
   */
  public $derivative = '';
}

On remarquera alors que chaque propriété de la classe correspond à une ligne de l'annotation pouvant être déclarée.