Vous êtes ici

Déclarer un module Drupal 8 : le fichier .info.yml

Vous avez 30 secondes ?
S'abonner au flux d'actualités
Rubrique: 
Technique
Difficultée: 
Facile
Nous avions vu dans notre tutoriel "Créer un module Hello World" comment déclarer son module auprès de Drupal 8 au moyen d'un fichier .info.yml. Dans ce tutoriel, nous reprendrons les points importants du fichier .info.yml et détaillerons ces différentes options.
 
Drupal est un CMS modulaire : il permet à des modules d'étendre les fonctionnalités de Drupal afin de créer des sites et des fonctionnalités toujours plus complexes. Un module se présente sous la forme d'un simple dossier, regroupant différents fichiers contenant son code informatique. Si vous lisez cet article, c'est que vous avez certainement déjà utilisé Drupal 8 et vous savez donc que le dossier du module doit se placer dans un répertoire modules de Drupal : à la racine ou dans sites/monsite.url pour les installations multi-sites.
 
Pour qu'un tel dossier soit reconnu comme un module compatible par Drupal 8, un certain nombre de conventions doivent être respectées :
  • Le nom donné au dossier contenant le module doit être le nom_machine_du_module.
  • Le dossier doit contenir un fichier nom_machine_du_module.module : un fichier contenant du code PHP (qui peut être vide si votre module ne fait rien).
  • Le dossier doit contenir un fichier nom_machine_du_module.info.yml : un fichier respectant la syntaxe YAML et definissant le module.
La présence de ce fichier descriptif .info.yml permet :
  • De notifier à Drupal l'exitence de votre module.
  • De fournir à Drupal les informations essentielles de votre module, en vue de son administration via l'interface de gestion des modules de votre site Drupal.
  • De fournir les conditions d'activation / désactivation de votre module (en terme de dépendances par exemple).

Choisir le nom du module

Le nom_machine du module est un nom unique - et propre à chaque module - qui permettra à Drupal de disciminer les modules les uns des autres. Ce nom doit être écrit en minuscule et ne doit pas comporter d'espaces, de ponctuations ou de caractères spéciaux à l'exception de l'underscore (le symbole "_"). De plus, ce nom doit être unique et propre à chaque module, c'est à dire que vous devez être certain qu'aucun autre module Drupal ne possède déjà ce nom là : ceci est important pour assurer la compatibilité entre les modules.
 
Astuce pour choisir un nom de module :
  • Choisissez un nom significatif pour votre module, en rapport avec ce qu'il fait.
  • Transformez ce nom en nom_machine en l'écrivant en minuscule, en remplaçant les espaces par des "_" et en enlevant les accents.
  • Pour vérifier que ce nom n'existe pas déjà, rendez-vous à l'URL: http://drupal.org/project/le_nom_choisi. Si cette page existe, c'est que le_nom_choisi existe déjà. Sinon, vous pouvez le prendre !

Décrire le module

Les informations de base du module doivent être placées à la racine du module dans un fichier dont l'extension est .info.yml, et dont le nom sera le nom machine choisi pour le module. Si votre module a pour nom machine mon_super_module, ce fichier de description se nommera donc mon_super_module.info.yml. Il utilisera la syntaxe dite YAML pour décrire les informations pertinentes à Drupal à propos du module. Dans cette syntaxe, les informations sont représentées par le couple clef : valeur.
 
Ci-dessous se trouve la liste des informations prises en compte par Drupal pour un module :
  • name (obligatoire)
  • description (recommandé)
  • core (obligatoire)
  • type (obligatoire)
  • dependencies
  • package
  • php
  • configure
  • required
  • hidden
  • project status url (à éviter : seulement pour les modules contributeurs non proposés via Drupal.org)
Voici une description détaillée de chacun de ces champs :

name (obligatoire)

Ce champ définit le nom du module tel qu'il apparaîtra sur la page d'administration des modules de votre site Drupal. Il s'agit d'un nom pour les humains et non d'un nom machine (donc pas mon_super_module). En tant que nom, la convention Drupal est d'utiliser des majuscules à chaque mot (Mon Super Module au lieu de Mon super module). Evidemment, si le titre de votre module contient des acronymes (CSS, XML, WYSIWYG) ou des références à des librairies ou technologies existantes (JQuery, JavaScript) celles-ci seront écrites selon leur convention habituelle.

name: Mon Super Module

description (recommandé)

Une courte description - de préférence d'une ligne - indique à l'administrateur d'un site Drupal ce que ce module permet. Ce champ est limité à 255 caractères, mais rappelez-vous : plus les descriptions sont longues, plus la page d'administration des modules est surchargée. Gardez donc cette description concise. Notez aussi que cette description peut contenir des liens, par exemple vers une documentation en ligne plus complète.

description: Ce module affiche l'heure sur chaque page de votre site (<a href="http://mon-super-module.com">plus d'infos</a>).

core (obligatoire)

Ce champ définit le numéro de version de Drupal pour laquelle est fait ce module. Par exemple pour Drupal 8, la valeur de ce champ sera 8.x. Le numéro mineur de version n'est pas à préciser ; 8.1 n'est donc pas une valeur correcte.

core: 8.x

type (obligatoire)

Ce champ est nouveau dans Drupal 8. Il définit le type d'extension décrite par le fichier actuel : les trois valeurs possibles sont donc module, theme ou profile. Vous l'avez compris : dans le cadre d'un module, ce sera la valeur module qu'il faudra choisir !

type: module

dependencies (optionnel)

Ce champ facultatif liste les modules dont dépend éventuellement ce module. Si ces dépendances ne sont pas présentes, le module ne pourra pas être activé. Dans le cas où les dépendances sont présentes mais non activées, l'administrateur sera notifié de la liste des dépendances qui seront automatiquement activées durant l'installation de ce module et pourra choisir d'annuler son installation s'il le souhaite.
Chaque nouvelle dépendance doit être notée à la ligne derrière un tiret indenté, conformément à la syntaxe YAML. Chaque dépendance doit être un nom machine de module : les accents, espaces et ponctuations sont donc interdits.
dependencies:
  - taxonomy
  - comment
Il est possible d'indiquer des dépendances vers une version particulière d'un module. Ces numéros de versions sont optionnels et ont pour syntaxe (majeur.mineur). La lettre x peut être utilisée pour remplacer n'importe quelle version mineure. Voici quelques exemples :
dependencies:
 - module_1 (1.x)
 - module_2 (>8.x-2.15)
Notez que les numéros de versions peuvent être précédés d'un symbole de test parmi les suivants :
  • = ou == : pour imposer un version particulière. Ce symbole optionnel est la valeur par défaut du test.
  • > : plus grand que
  • >= : plus grand ou égal à
  • < : inférieur à
  • <= : inférieur ou égal à
  • != : différent de
Plusieurs tests peuvent être précisés en les séparant par des espaces. Dans l'exemple ci-dessous, notre module dépendra du module exampleapi de n'importe quelle version après la 1.0 et jusqu'à la version 3.2 incluse, à l'exception de la 3.0 :
dependencies:
  - exampleapi (>1.0, <=3.2, !=3.0)
Enfin, notons qu'il est possible pour un module de dépendre d'une version particulière de Drupal Core. Dans ce cas, le mot-clef system est utilisé pour symboliser Drupal. Dans l'exemple ci-dessous, le module dépend d'une fonctionnalité apparue dans la version 8.2 de Drupal :
dependencies:
  - system (>=8.2)

package (optionnel)

Si votre module fait partie d'un ensemble de plusieurs modules ou s'il étend un ensemble cohérent de modules, le mot clef package peut être utilisé pour les rassembler au sein d'un même groupe. Si l'option n'est pas utilisée, le module sera placé dans la catégorie Other (Autre) sur la page d'administration des modules. Cette option n'est à utiliser que par des ensembles importants de modules, ou par des modules étendant les fonctionnalités de groupes existants tels que Fields, Views, Commerce, Organic Groups, Voting, etc... Dans les autres cas, cette option ne doit pas être utilisée. A titre indicatif, un groupement de quatre modules (ou plus) est un bon début pour songer à créer un package.
Notez que la casse est importante : le package fields n'est pas le même que Fields. A ce titre il convient d'utiliser les conventions de nommage Drupal en ajoutant une majuscule à chaque mot comme par exemple Organic Group. N'utilisez pas de signe de ponctuation.

package: Organic Group

Voici quelques exemples de groupes existants :
  • Administration
  • Commerce
  • Development
  • Fields
  • Media
  • User interface
  • Views
  • Voting (si votre module requière VotingAPI)
Un listing (non officiel) tentant de référencer les packages existants est disponible sur cette page : https://groups.drupal.org/node/97054.

php (optionnel)

Pour un module donné, il est possible de spécifier la version minimale de PHP requise pour son fonctionnement. Cela s'explique par certains modules nécessitant des capacités de PHP apparues dans des versions ultérieures à celle officiellement compatible avec Drupal. Cette option ne doit être utilisée que si votre module à besoin d'une version PHP plus récente que la version officiellement supportée par Drupal. Dans les autres cas, cette option ne doit pas être présente.

php: 5.4

configure (optionnel)

Cette option indique la route vers la page de configuration principale de votre module. Lorsqu'un module est activé, des liens contextuels lui sont automatiquement crées sur la page d'administration des modules. Ces liens sont : "droits" dans le cas où le module utilise le système de permissioninfo-icon de Drupal pour son fonctionnement, "configuration" dans le cas où le module définie via cet option un lien vers sa page de configuration. En ne remplissant pas cette option, le lien "configuration" ne sera pas crée pour ce module.
Notez que depuis Drupal 8, ce n'est plus le lien en terme d'url mais le nom de la route - telle qu'elle apparaît dans le fichier .routing.yml du module - qui doit être utilisé.

configure: action.admin

required (optionnel)

Cette option définit que ce module ne devrait jamais être désactivé. Une fois installé, il ne peut donc plus être désinstallé. Cette option est généralement utilisée pour des modules Core de Drupal.
Notez que vous devez utilisez cette option uniquement pour la passer à TRUE. Dans ce cas inverse, vous n'en avez tout simplement pas besoin.

required: TRUE

hidden (optionnel)

Cette option permet de cacher son module aux yeux de Drupal. En passant cette option à TRUE, le module ne s'affichera pas sur la page de configuration des modules de Drupal. Par conséquent, un utilisateur lambda ne pourra pas l'installer. N'utilisez cette option que pour la passer à TRUE et ainsi cacher le module : elle n'est pas nécessaire dans le cas inverse. De manière générale, cette option peut permettre de cacher des sous-modules de tests éventuels afin de ne pas encombrer et embrouiller l'affichage d'administration des modules.

hidden: TRUE

project status url (seulement pour les modules non contribués)

Cette option permet de définir une URL personnalisée pour la vérification de mises à jour du module, par le mécanisme du module core Update Status. Ceci est automatiquement ajouté pour tous les modules proposés sur drupal.org. Cette option n'est donc à utiliser que si vous maintenez votre propre dépôt de mises à jour. Dans ce cas, l'URL que vous définissez doit pointer vers un domaine acceptant les requêtes de la forme : http://my.domain.com/projects/{project}/{core}. Avec cet exemple, l'URL à définir serait : http://my.domain.com/projects.

project status url: http://my.domain.com/projects

Notation: 
Average: 4 (5 votes)
Vous avez aimé: