Drupal 8 : Les annotations

Cet article est extrait de notre formation drupal 8 "de Drupal 7 à Drupal 8" à destination des développeurs. N'hésitez pas à nous contacter pour en savoir plus !

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 élément 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. Dans Drupal 8, 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 sous 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.


Votre commentaire

Le contenu de ce champ sera maintenu privé et ne sera pas affiché publiquement.
Votre adresse servira à afficher un Gravatar et à vous notifier des réponses. Votre commentaire sera anonymisé si ce billet est dépublié pendant plus de 3 mois.
Pour lutter contre le spam notre système enregistre votre adresse IP et votre adresse e-mail si vous la partagez.
Nous vous invitons à consulter notre politique de confidentialité pour comprendre les traitements faits de ces données et comment les rectifier.

À propos de Julien

Co-fondateur - Scrum master & Expert technique

Utilisateur de Drupal depuis 2008, j’ai fait mes armes comme développeur chez Commerce Guys puis me suis mis à encadrer les nouveaux arrivants avant de donner des formations, participer aux avant ventes et accompagner les équipes au passage à Scrum.

Je suis impliqué dans la communauté française de Drupal depuis 2009, j’ai été tour à tour président puis vice-président de l’association Drupal France et francophonie entre 2011 et 2013.