Informer Drupal 8 de votre module avec un fichier .info.yml

05/07/2025, by Ivan

Sujet principal : métadonnées du projet

Le fichier .info.yml (également appelé « fichier info yaml ») est une partie essentielle d’un module, thème ou profil d’installation Drupal 8 pour stocker les métadonnées du projet.

Ces fichiers .info.yml sont nécessaires pour :

Informer Drupal de l’existence du module, thème ou profil d’installation.
Différencier le type de projet : thème, module, etc.
Fournir des informations pour les pages d’administration de l’interface web Drupal.
Indiquer les critères de gestion de l’activation, désactivation et compatibilité avec la version de Drupal.
Répondre à des objectifs administratifs généraux dans d’autres contextes.

Pour plus d’informations, consultez la dernière API sur InfoParserInterface.php (cliquez sur Voir la source).

Hello World

Voici un fichier hello_world.info.yml que nous utiliserons. Si vous suivez ce guide, créez un nouveau fichier hello_world.info.yml à la racine de votre module et collez-y ce code :

name: Hello World Module
description: Creates a page showing "Hello World".
package: Custom

type: module
core: 8.x

Regardons chaque ligne pour comprendre leur rôle.

Les trois premières lignes sont principalement utilisées dans l’interface d’administration lorsque les utilisateurs activent ou désactivent votre module. Les clés name et description fournissent le texte affiché sur la page d’administration des modules, et la clé package permet de grouper des modules similaires ensemble. Par exemple, le Core utilise package: Core pour grouper tous les modules fournis avec Drupal 8. Vous pouvez utiliser package: Custom pour grouper tous vos modules personnalisés, ce qui facilite leur recherche et activation.

La clé type, nouvelle dans Drupal 8, indique le type d’extension, par exemple module, thème ou profil.

Pour les modules hébergés sur drupal.org, le numéro de version est ajouté automatiquement par le packager. Vous ne devez donc pas le renseigner manuellement, et éviter d’inclure une ligne version.

La clé core indique avec quelle version majeure de Drupal votre module est compatible.

name, type et core sont des clés obligatoires.

Faut-il utiliser core_version_requirement ?

Lors de la définition des contraintes de version majeure du noyau, l’ordre de priorité est le suivant :

Si une exigence principale est définie dans composer.json, elle a la priorité maximale.
Si aucune exigence de noyau n’est définie dans composer.json, core_version_requirement dans info.yml prend le pas.
Si core_version_requirement n’est pas défini dans info.yml, alors la version indiquée dans la section dépendances du module principal dans info.yml est utilisée.

Définir core_version_requirement si nécessaire

La nouvelle clé core_version_requirement dans les fichiers *.info.yml pour modules, thèmes et profils prend désormais en charge la gestion sémantique des versions implémentée par Composer. Elle permet à ces extensions d’indiquer leur compatibilité avec plusieurs versions majeures de Drupal.

Par exemple, un module compatible Drupal 8 et 9 pourrait avoir un fichier info.yml comme :

name: My Module
type: module
core: 8.x
core_version_requirement: ^8 || ^9

Cette configuration indique que le module est compatible avec toutes les versions de Drupal 8 et 9. La clé core est nécessaire ici car les versions de Drupal Core antérieures à 8.7.7 ne reconnaissent pas core_version_requirement.

Cependant, la plupart des modules doivent retirer le code obsolète pour être compatibles Drupal 9, et ne seront donc pas compatibles avec toutes les versions de Drupal 8.

Un module compatible avec Drupal 8 à partir de la version 8.8.0 et avec Drupal 9 aura besoin d’un fichier info.yml comme :

name: My Module
type: module
core_version_requirement: ^8.8 || ^9

La clé core ne doit pas être utilisée ici pour éviter l’installation sur des versions Drupal antérieures à 8.7.7. Ajouter à la fois core et core_version_requirement (avec autre chose que ^8 || ^9) entraînera une exception.

core_version_requirement ne peut pas être utilisé pour restreindre la version du noyau à une version antérieure à 8.7.7. Par exemple, core_version_requirement: ^8.7 || ^9 provoquera une erreur lors de l’analyse, car ^8.7 inclut des versions telles que 8.7.0 qui ne reconnaissent pas cette clé.

Il est important que lors de l’utilisation de cette nouvelle clé core_version_requirement avec autre chose que ^8 || ^9, le module soit testé sur Drupal 8.7.7 ou supérieur.

Exemple complet

En plus des propriétés de base montrées précédemment, plusieurs autres propriétés sont possibles. Voici un exemple complet :

name: Hello World Module
description: Creates a page showing "Hello World".
package: Custom

type: module
core: 8.x

dependencies:
  - drupal:link
  - drupal:views
  - paragraphs:paragraphs
  - webform:webform (>=8.x-5.x)

test_dependencies:
  - drupal:image

configure: hello_world.settings

php: 5.6

hidden: true
required: true

# Note : ne pas ajouter manuellement les propriétés 'version' ou 'project'.
# Elles sont automatiquement ajoutées par le packager sur drupal.org.
# version: 1.0
# project: 'hello_world'

dependencies : liste des autres modules dont dépend votre module. Les dépendances core ou contrib doivent être sous la forme {projet}:{module}, où {projet} est le nom du projet tel qu’affiché dans l’URL Drupal.org (par exemple drupal.org/project/views) et {module} est le nom machine du module. Les dépendances peuvent aussi inclure des contraintes de version, comme webform:webform (>=8.x-5.x). Si votre module dépend d’autres modules ou bibliothèques, ces dépendances doivent aussi être déclarées dans le fichier composer.json du module. Si vous avez des modules personnalisés locaux dépendants entre eux, vous pouvez utiliser {module}:{module} (ou {module}:{sous-module} pour les sous-modules).
test_dependencies : liste des modules nécessaires pour exécuter certains tests automatisés DrupalCI, mais pas pour le fonctionnement général du module. Ces dépendances doivent être enregistrées dans votre dépôt Git avant de lancer le test. En alternative, Composer peut gérer les dépendances de test - voir la documentation correspondante.
configure : si votre module propose un formulaire de configuration, vous pouvez indiquer la route ici pour qu’un lien apparaisse sur la page Extensions (/admin/modules) lorsque les détails sont déployés.
php: 5.6 : définit la version minimale de PHP requise pour activer le module, afin d’éviter des erreurs si votre module utilise des fonctions absentes des versions plus anciennes.
hidden: true : masque le module dans la liste des modules sur la page Extensions. Utile pour les modules de test ou d’exemple destinés aux développeurs. Vous pouvez rendre ces modules visibles en ajoutant $settings['extension_discovery_scan_tests'] = TRUE; dans settings.php.
required: true : signifie que le module doit être activé et ne peut pas être désinstallé.
Propriétés gérées par le packager Drupal : ne les ajoutez pas manuellement dans info.yml (version et project).

Débogage des fichiers .info.yml

Le module n’apparaît pas sur la page admin/modules

Vérifiez que le fichier a pour nom {machine_name}.info.yml et qu’il se trouve à la racine du dossier du module.
Assurez-vous que la syntaxe est correcte, notamment pas d’espace avant les deux-points (:), mais un espace après. Le format doit ressembler à l’exemple.
Vérifiez que le fichier contient la ligne :

type: module

Assurez-vous que le nom du module commence par une lettre ou un underscore. Selon la documentation PHP sur les noms valides :

Les noms de fonctions suivent les mêmes règles que les autres identifiants PHP. Un nom valide commence par une lettre ou un underscore, suivi de lettres, chiffres ou underscores. En expression régulière : [a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*.

Le module apparaît sur admin/modules mais la case est décochée

Vérifiez que la compatibilité core est bien définie à 8.x :

core: 8.x

Assurez-vous que toutes les dépendances sont disponibles. Vous pouvez étendre les informations du module pour voir les dépendances manquantes.

expand_requirements

Notez que certains modules ont été déplacés hors du noyau Drupal 8, tandis que d’autres modules ajoutés ont été incorporés dans le noyau ou remplacés par de nouveaux modules de base.

La description du module est vide

Souvenez-vous que la clé description est utilisée pour la description.

description: Description du module exemple.

Ajouter un fichier composer.json

En plus de déclarer les dépendances dans le fichier .info.yml, si votre module est un module contribué sur Drupal.org et que vous souhaitez tester les changements de dépendances avec DrupalCI, vous devez disposer d’un composer.json qui exprime ces dépendances Drupal (DrupalCI ne détecte les changements que dans composer.json, pas dans les fichiers .info ou .info.yml).

Types de blocs supplémentaires (EBT) – Nouvelle expérience de Layout Builder❗

❗Types de paragraphes supplémentaires (EPT) – Nouvelle expérience Paragraphes