Creare un modulo custom per Drupal 11

Drupal 11 mantiene la struttura dei moduli custom introdotta con Drupal 8 e consolidata nelle versioni successive: un file .info.yml, un controller, un file di routing e, dove serve, un form o un servizio. La novità principale rispetto al passato è che PHP 8.1 è il minimo richiesto, e alcune deprecazioni di Drupal 10 sono diventate rimozioni definitive. Questo tutorial crea un modulo funzionante che espone una pagina con una rotta personalizzata, punto di partenza sufficiente per qualsiasi estensione successiva.

Struttura della cartella

Tutti i moduli custom vanno in web/modules/custom/. Creare la directory hello_blue con i file seguenti:

web/modules/custom/hello_blue/
├── hello_blue.info.yml
├── hello_blue.routing.yml
└── src/
    └── Controller/
        └── HelloBlueController.php

Il file .info.yml

name: Hello Blue Drop
type: module
description: Modulo dimostrativo per The Blue Drop.
package: Custom
core_version_requirement: ^11

core_version_requirement sostituisce definitivamente core: da Drupal 9.3. Usare ^10 o ^11 a seconda del progetto; non usare entrambi sulla stessa riga.

Il routing

hello_blue.hello: 
	path: '/hello-blue' 
	defaults: 
		_controller: '\Drupal\hello_blue\Controller\HelloBlueController::hello' 
		_title: 'Hello Blue Drop' 
	requirements: 
		_permission: 'access content'

Il file si chiama esattamente hello_blue.routing.yml. Il nome della rotta segue la convenzione nome_modulo.nome_rotta. _permission accetta qualsiasi permission stringa registrata nel sistema; access content è la più permissiva disponibile senza configurazioni aggiuntive.

Il controller

<?php
 namespace Drupal\hello_blue\Controller;
 use Drupal\Core\Controller\ControllerBase;
 class HelloBlueController extends ControllerBase {
   public function hello(): array {
    return [
      '#markup' => $this->t('Benvenuto su The Blue Drop.'),
    ];
  }
 }

ControllerBase fornisce accesso a $this->t() per le traduzioni e ad altri servizi comuni tramite metodi statici come currentUser() o entityTypeManager(). Non è obbligatorio estenderlo, ma è la scelta corretta per i controller che interagiscono con il container di Drupal.

Abilitazione

drush en hello_blue -y
drush cr

La pagina è raggiungibile all'indirizzo /hello-blue. Se la rotta non risponde, verificare che il cache rebuild sia andato a buon fine e che non ci siano errori di sintassi nello YAML, che non ammette tab come indentazione.

Quando questo non basta

Un modulo con un solo controller non ha stato, non persiste dati, non espone configurazione. Per qualsiasi logica più complessa, il passo successivo è introdurre un service registrato in hello_blue.services.yml e iniettarlo nel controller tramite dependency injection, abbandonando i metodi statici di ControllerBase. Questo tutorial non lo copre, ma è il punto di estensione naturale.