Comprensione degli hook di aggiornamento e post aggiornamento per aggiornamenti riusciti del sito Drupal

Durante gli aggiornamenti principali o gli aggiornamenti dei moduli, è fondamentale garantire la stabilità e l'integrità del tuo sito Web Drupal. Fortunatamente, il modulo API di aggiornamento e gli hook di aggiornamento/post aggiornamento sono qui per aiutarti.

Il modulo Update API fornisce gli hook necessari per l'aggiornamento del codice e dei moduli sul tuo sito Drupal. Questi ganci non sono altro che ganci di aggiornamento e post-aggiornamento che consentono agli sviluppatori di personalizzare gli aggiornamenti in base alle proprie esigenze.

In questo articolo, discuteremo dell'API di aggiornamento, di cosa sono gli hook di aggiornamento e post-aggiornamento e quando e come dovrebbero essere usati. Comprendendo entrambi i tipi di hook, puoi aggiornare con successo il tuo sito Drupal con il minimo sforzo. Iniziamo!

L'API di aggiornamento

Mentre si lavora su un sito esistente, quando si aggiorna il codice in un modulo, potrebbe essere necessario aggiornare i dati archiviati in modo che siano compatibili con il nuovo codice. Potresti aver notato errori come "Il sito web ha riscontrato un errore imprevisto" lampeggiare davanti a te. Spaventoso vero!? Lo so! È qui che l'API di aggiornamento di Drupal viene in nostro soccorso.

Se l'aggiornamento è tra due versioni secondarie del tuo modulo all'interno della stessa versione principale di Drupal core, puoi utilizzare l'API di aggiornamento per aggiornare i dati. L'API di aggiornamento consente di fornire il codice che esegue un aggiornamento dei dati archiviati ogni volta che il modulo apporta una modifica al proprio modello di dati. La modifica del modello di dati si riferisce a qualsiasi modifica che rende i dati archiviati su un sito esistente incompatibili con la codebase aggiornata di tale sito. Queste modifiche al modello di dati riguardano:

Aggiornamento dello schema di configurazione

• Aggiunta/rimozione/rinomina di una chiave di configurazione.
• Modifica del tipo di dati della chiave di configurazione.
• Modifica del valore predefinito previsto di una chiave di configurazione, ecc.

Aggiornamento dello schema del database

• Aggiunta/modifica/rimozione di una tabella o di un campo del database.
• Spostare i dati archiviati in un campo o in una tabella diversi.
• Modifica del formato dei dati memorizzati, ecc.

Aggiornamento delle entità e dei campi

• Aggiunta di un nuovo campo base a un tipo di entità esistente.
• Aggiornamento di un campo da un tipo obsoleto a un nuovo tipo, ecc.

Aggiornamento dei dati

• Manipolare i dati memorizzati su un sito esistente.

Utilizzo degli hook di aggiornamento

Hook hook_update_N() è usato per introdurre un aggiornamento tra versioni minori di un modulo. Questi hook vengono posizionati all'interno del modulo nel file *.install .

hook_update_N() è scritto nella forma di (nome modulo)_update_(numero). Qui N comprende:

• 1 o 2 cifre si riferiscono alla compatibilità del core Drupal (Drupal 8, 9, 10, ecc.)
• La cifra successiva è per la versione principale del tuo modulo
• Le ultime 2 cifre per il conteggio sequenziale, a partire da 01

Esempio:

example_update_9201(): il primo aggiornamento per le versioni 9.x-2.x.
Dove 'example' è il nome del modulo, la prima cifra si riferisce alla versione core di Drupal '9', il numero '2' si riferisce alla versione principale del modulo e le ultime due cifre '01' indicano la prima funzione di aggiornamento scritta per modulo 'esempio'.

La parte numerica della funzione di implementazione dell'hook (ad esempio, 9201 nell'esempio precedente) viene memorizzata nel database per tenere traccia di quali aggiornamenti sono già stati eseguiti. Quindi non dovresti mai rinumerare le funzioni di aggiornamento.
Per conoscere la versione corrente dello schema di un modulo "esempio memorizzato nel database", utilizzare:

drush php-eval "echo drupal_get_installed_schema_version('example');"

Per reimpostare manualmente la versione corrente dello schema di un modulo 'example' su '9201', utilizzare:

drush php-eval "echo drupal_set_installed_schema_version('example', '9201');"

Nota: cerca di evitare di utilizzare la funzione drupal_set_installed_schema_version() sui siti di produzione poiché aggiorna direttamente il tuo database. Puoi usarlo negli ambienti di test locali o inferiori durante lo sviluppo per reimpostare la versione dello schema.

Aggiungi una descrizione appropriata nel commento del blocco del documento prima della funzione di hook di aggiornamento in quanto verrà stampata per gli utenti durante l'esecuzione.

 Structure of hook_update_N(): /** * A aimple hook_update_N() hook. */ function example_update_9201() { // Code goes here. }

Questi hook vengono eseguiti in ordine ordinato, ad esempio l'hook example_update_9201() viene eseguito prima di example_update_9202(), il successivo è 9203, 9204 e così via.

Puoi anche cambiare l'ordine ordinato di questi hook, introducendo dipendenze tra gli hook. Usa l'hook hook_update_dependencies() per eseguire gli aggiornamenti tra due hook di aggiornamento.

Tutti gli hook di aggiornamento vengono eseguiti in batch e supportano anche l'elaborazione in batch degli elementi. Tutti gli hook di aggiornamento hanno accesso a un parametro $sandbox che può essere utilizzato per creare processi batch negli hook di aggiornamento al fine di elaborare dati enormi contemporaneamente senza causare il timeout di PHP.

Un semplice esempio di hook di aggiornamento per aggiungere una nuova chiave di configurazione:

Attualmente, il file example_module.settings.yml contiene:

Per aggiungere una nuova chiave 'descrizione' alla configurazione:

• Aggiungi la chiave 'descrizione' al file delle impostazioni

• Aggiungi l'update_hook nel file example_module.install:

• Usa drush updb per eseguire l'hook.

• Controlla la configurazione aggiornata, la nuova chiave 'descrizione' è aggiornata.

Lavorare con gli hook post aggiornamento

Hook hook_post_update_NAME(), simile all'hook di aggiornamento, viene utilizzato per introdurre un aggiornamento. Ma questo hook ha principalmente lo scopo di aggiornare i dati, come le entità. Questi hook vengono eseguiti dopo che tutti gli hook hook_update_N() sono stati eseguiti. In questa fase, Drupal è già completamente riparato, quindi puoi utilizzare qualsiasi API all'interno del sito.

Questi hook sono inseriti in un file *.post_update.php nel tuo modulo.

hook_post_update_NAME() è scritto nella forma di (nome modulo)_post_update_(qualsiasi nome). Qui NAME può essere qualsiasi nome di macchina arbitrario. Questa denominazione alfanumerica delle funzioni nel file è l'unica cosa che garantisce l'ordine di esecuzione di questo hook.

Simile agli hook di aggiornamento, aggiungi una descrizione appropriata nel commento docblock prima dell'hook post_update. Inoltre, non riutilizzare lo stesso nome hook.

Struttura di hook_post_update_NAME():

 /** * A aimple hook_post_update_NAME() hook. */ function example_post_update_test() { // Code goes here. }

Proprio come con gli hook di aggiornamento, utilizza il parametro $sandbox per indicare che l'API Batch deve essere utilizzata per i tuoi hook post_update.

Un semplice esempio sull'utilizzo dell'hook post-aggiornamento per aggiornare il termine dati:

• Attualmente, tutti i termini nel vocabolario dei tag hanno un campo "Esempio di prova" disabilitato.

• Aggiungi un post_update hook nel file example_module.post_update.php per abilitare il campo 'Test example' per tutti i termini esistenti.

• Usa drush updb per eseguire l'hook.

• Verificare i dati del termine aggiornati, la casella di controllo 'Esempio di prova' deve essere abilitata.

Come eseguire questi ganci!

Puoi utilizzare il comando Drush per eseguire questi hook, drush updb. Costruisce il batch nei seguenti passaggi:

• Vengono scoperti tutti gli hook di aggiornamento.
• Risolve la dipendenza e ordina il loro ordine.
• Gli hook vengono posizionati per l'elaborazione batch.
• Successivamente, vengono scoperti tutti i ganci Post.
• Se sono presenti hook post_update e se update_hook è stato eseguito in precedenza, le cache vengono cancellate.
• Quindi, inserisci ciascun hook post_update nel batch.
• Eseguire il batch.

Uno dei principali vantaggi dell'hook post-aggiornamento rispetto all'hook di aggiornamento è che Drupal è completamente funzionante al momento dell'esecuzione dell'aggiornamento post-aggiornamento. Ciò consente agli sviluppatori di utilizzare qualsiasi servizio Drupal durante l'utilizzo dell'hook post-aggiornamento. Con l'hook di aggiornamento, non si deve presumere che Drupal sia completamente riparato ed evitare di invocare altri hook, API di entità, ecc.

Pensieri finali

Quando provi a riparare il tuo sito aggiornando lo schema di configurazione/database, prova a utilizzare gli hook di aggiornamento. Quando si tratta di manipolare i dati archiviati, salvare nuovamente le configurazioni, aggiornare le entità di contenuto, svuotare la cache, ecc., gli hook post-aggiornamento sono più appropriati da usare.

Ad essere onesti, non esiste una documentazione chiara su Drupal.org riguardo a quando usare quale hook! C'è un problema aperto che richiede di migliorare la documentazione sull'uso di questi due hook a cui puoi contribuire se vuoi.

Ma in base all'esperienza degli sviluppatori e guardando i moduli principali di Drupal 9 e 10 come esempio, utilizzare gli hook di aggiornamento per eseguire operazioni CRUD su configurazioni o database (ad esempio riparare il sito) e utilizzare gli hook post-aggiornamento per le entità di contenuto CRUD ( quindi correggi i dati sul sito aggiornato), poiché gli hook di post-aggiornamento vengono eseguiti dopo gli hook di aggiornamento.

Ti è piaciuto leggere questo articolo? Mostraci un po' d'affetto e iscriviti oggi stesso alla nostra newsletter settimanale!