Informare Drupal 8 del vostro modulo tramite il file .info.yml

04/10/2025, by Ivan

Tema principale: metadati del progetto

Il file .info.yml (chiamato anche “file info yaml”) è una parte importante di un modulo, tema o profilo di installazione di Drupal 8 per memorizzare i metadati sul progetto.

Questi file .info.yml sono necessari per:

Informare Drupal dell’esistenza del modulo, del tema o del profilo di installazione.
Differenziare un tema da un modulo per tipo.
Fornire informazioni per le pagine di amministrazione della UI Web di Drupal.
Indicare i criteri per la gestione dell’attivazione e disattivazione del modulo e la compatibilità con la versione di Drupal.
Scopi amministrativi generali in altri contesti.

Per ulteriori informazioni, consultare l’ultimo API su InfoParserInterface.php. (Fare clic su Visualizza sorgente.)

Hello World

Di seguito è riportato il file hello_world.info.yml che utilizzeremo. Se state seguendo la guida, create un nuovo file hello_world.info.yml nella cartella principale del vostro modulo e incollate questo codice.

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

type: module
core: 8.x

Esaminiamo ogni riga per vedere cosa fa.

Le prime tre righe sono utilizzate principalmente nell’interfaccia di amministrazione, quando gli utenti possono abilitare o disabilitare il modulo. Le chiavi name e description forniscono il testo visualizzato nella pagina di amministrazione del modulo, mentre la chiave package consente di raggruppare moduli simili. Ad esempio, Core utilizza package: Core per raggruppare tutti i moduli forniti con Drupal 8, e potete usare package: Custom per raggruppare tutti i vostri moduli personalizzati, facilitandone la ricerca e l’attivazione.

La chiave type, nuova in Drupal 8, indica il tipo di estensione, come modulo, tema o profilo.

Per i moduli distribuiti su drupal.org, il numero di versione sarà aggiunto automaticamente dallo script di packaging. Non dovete specificarlo manualmente, ma escludere completamente la riga della versione.

La chiave core indica con quale versione del core di Drupal il vostro modulo è compatibile.

name, type e core sono chiavi obbligatorie.

Specificare core_version_requirement
Attenzione
Attualmente DrupalCI non supporta patch di test che modificano core_version_requirement.

Vi serve core_version_requirement?

Quando si definiscono i vincoli della versione core, viene utilizzato il seguente ordine di priorità:

Se composer.json specifica un requisito per il core, questo ha la priorità più alta.
Se in composer.json non è presente alcun requisito per il core, core_version_requirement in info.yml ha priorità sul successivo.
Se core_version_requirement non è impostato in info.yml, verrà utilizzata qualsiasi versione indicata nel modulo principale nella sezione delle dipendenze di info.yml.

Specificare core_version_requirement quando necessario

La nuova chiave core_version_requirement nei file *.info.yml per moduli, temi e profili supporta ora il versionamento semantico, implementato in Composer. Questo consente a moduli, temi e profili di indicare compatibilità con più versioni principali del core di Drupal.

Ad esempio, un modulo compatibile con Drupal 8 e Drupal 9 può avere un file info.yml come questo:

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

Ciò indica che il modulo è compatibile con tutte le versioni di Drupal 8 e 9. core è richiesto qui perché le versioni di Drupal Core fino alla 8.7.7 non riconoscono la chiave core_version_requirement.

Tuttavia la maggior parte dei moduli dovrà rimuovere codice deprecato per essere compatibile con Drupal 9. Per questo non potranno essere compatibili con tutte le versioni di Drupal 8.

Ad esempio, un modulo compatibile con le versioni di Drupal 8 successive a Drupal 8.8.0 e anche con Drupal 9 avrà bisogno di un file info.yml simile:

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

La chiave core non deve essere usata qui, per assicurarsi che le versioni di Drupal precedenti alla 8.7.7 non installino il modulo. Aggiungere sia core che core_version_requirement con qualcosa di diverso da core_version_requirement: ^8 || ^9 genererà un’eccezione.

core_version_requirement non può essere utilizzato per limitare la versione del core a 8.7.7 o precedenti. Ad esempio, core_version_requirement: ^8.7 || ^9 causerà un errore di parsing: non è valido, perché ^8.7 includerebbe versioni come 8.7.0, che non riconoscono la chiave core_version_requirement.

È importante sapere che usando il nuovo core_version_requirement con qualcosa di diverso da core_version_requirement: ^8 || ^9, il modulo deve essere testato su Drupal 8.7.7 o successivo.

Esempio completo

Oltre alle proprietà principali mostrate nell’esempio precedente, ci sono anche diverse proprietà aggiuntive. Questo è un esempio completo:

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: do not add the 'version' or 'project' properties yourself.
# They will be added automatically by the packager on drupal.org.
# version: 1.0
# project: 'hello_world'

dependencies: elenco di altri moduli da cui il vostro modulo dipende. Le dipendenze dal core di Drupal o dai moduli contrib devono essere nello spazio dei nomi nel formato {project}:{module}, dove {project} è il nome del progetto come appare nell’URL di Drupal.org (ad esempio drupal.org/project/views) e {module} è il machine name del modulo. Le dipendenze possono anche includere vincoli di versione, ad esempio webform:webform (>= 8.x-5.x). Se il vostro modulo ha dipendenze da altri moduli o librerie, devono essere dichiarate anche nel file composer.json del modulo. Se avete moduli personalizzati locali che dipendono l’uno dall’altro, potete usare {module}:{module} (o {module}:{submodule} per i sottomoduli).
test_dependencies: elenco di altri moduli (nello stesso formato delle dipendenze) necessari per eseguire alcuni test automatici del vostro modulo su DrupalCI, ma non richiesti come dipendenze generali. Tenete presente che dovete effettuare il commit della modifica test_dependencies nel vostro repository Git prima di avviare un test che ne dipende — non potete semplicemente includere la modifica a info.yml nello stesso patch di un nuovo test. In alternativa, potete usare Composer per gestire le dipendenze dei test — vedere la documentazione relativa per ulteriori informazioni.
configure: se il vostro modulo offre un form di configurazione, potete specificare qui la route a quel form. Verrà quindi mostrato come link nella pagina «Estensioni» (/admin/modules), quando l’utente espande i dettagli.
php: 5.6: definisce la versione minima di PHP richiesta per il modulo. Gli utenti non potranno attivarlo se utilizzano una versione più vecchia. Può essere usato per evitare errori se il modulo utilizza funzionalità introdotte in versioni più recenti di PHP.
hidden: true: nasconde il modulo dall’elenco nella pagina Estensioni. Utile per moduli che contengono solo test o destinati come esempio per sviluppatori che devono implementare API del core. Potete renderli visibili aggiungendo $settings['extension_discovery_scan_tests'] = TRUE nel file settings.php.
required: true: significa che il modulo deve essere attivato e non può essere rimosso.
Proprietà limitate, aggiunte dal sistema di packaging Drupal. Non aggiungetele manualmente in info.yml nel vostro repository: version e project.

Debug dei file .info.yml

Il modulo non compare in admin/modules

Assicuratevi che il file info si chiami {machine_name}.info.yml e sia nella root della cartella del modulo.
Assicuratevi che il file sia formattato correttamente. Ad esempio, non devono esserci spazi prima dei due punti (:) ma deve esserci uno spazio dopo. La formattazione deve essere come nell’esempio seguente.
Assicuratevi che il file contenga la seguente riga:

type: module

Assicuratevi che il machine name del modulo inizi con una lettera o un underscore. Di seguito un estratto dalla documentazione PHP sui nomi di funzione validi.

I nomi delle funzioni seguono le stesse regole delle altre etichette in PHP. Un nome di funzione valido inizia con una lettera o un underscore, seguito da qualsiasi numero di lettere, cifre o underscore. Come espressione regolare, sarà: [a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*.

Il modulo compare in admin/modules ma la casella è disattivata

Assicuratevi che la compatibilità del core sia impostata su 8.x

core: 8.x

Assicuratevi che tutte le dipendenze del modulo siano disponibili. Potete espandere le informazioni del modulo per vedere quali requisiti mancano.

expand_requirements

Notate che alcuni moduli sono stati spostati fuori dal core di Drupal 8, mentre altri moduli aggiunti sono stati spostati nel core o sostituiti da nuovi moduli core.

La descrizione del modulo è vuota

Ricordate che il valore di description è usato come descrizione.

description: Example Module description.

Aggiunta del file composer.json

Oltre a dichiarare le dipendenze da altri moduli nel file .info.yml, se il modulo è un modulo contrib su Drupal.org che vuole testare modifiche alle dipendenze con DrupalCI, deve avere un composer.json che esprima tali dipendenze (DrupalCI può rilevare modifiche alle dipendenze solo nei patch dentro composer.json, non nei file .info o .info.yml).

Extra Block Types (EBT) - Nuova esperienza con Layout Builder❗

❗Extra Paragraph Types (EPT) - Nuova esperienza con Paragraphs