Come creare una modalità di manutenzione personalizzata per i temi a blocchi di WordPress

Perché personalizzare la modalità di manutenzione

Quando WordPress esegue aggiornamenti, mostra un messaggio di testo semplice: "Briefly unavailable for scheduled maintenance…". È funzionale, ma non rispecchia l’identità visiva di un brand. Con i temi a blocchi è possibile creare una pagina di manutenzione che utilizza gli stessi stili globali, i pattern e i template parts del sito, garantendo coerenza grafica e una migliore esperienza utente.

Il punto di partenza: aggiungere un hook al tema

L’unica operazione necessaria è inserire una funzione nel file functions.php del tema. Questa funzione intercetta la richiesta di template e, se esiste un template chiamato Maintenance, lo restituisce al posto del template normale. Ecco lo scheletro da copiare:

function mytheme_force_maintenance_template( $template ) {
    // Gli utenti loggati vedono il sito normale
    if ( is_user_logged_in() ) {
        return $template;
    }

    // Verifica che il tema supporti i block‑templates
    if ( ! current_theme_supports( 'block-templates' ) ) {
        return $template;
    }

    // Cerca un template con titolo esatto "Maintenance"
    $posts = get_posts([
        'post_type'   => 'wp_template',
        'title'       => 'Maintenance',
        'post_status' => ['publish', 'draft'],
        'posts_per_page' => -1,
        'no_found_rows' => true,
    ]);

    foreach ( $posts as $p ) {
        $themes = wp_get_post_terms( $p->ID, 'wp_theme', ['fields' => 'names'] );
        if ( in_array( get_stylesheet(), $themes, true ) ) {
            $slug = $p->post_name;
            return locate_block_template( $template, $slug, [$slug] );
        }
    }

    return $template;
}
add_filter( 'template_include', 'mytheme_force_maintenance_template', 99 );

Questa funzione è eseguita una sola volta; da quel momento il sito cercherà automaticamente il template Maintenance quando non è presente un utente loggato.

Opzione SEO: header 503 e Retry‑After

Se il sito riceve traffico da motori di ricerca, è consigliabile inviare una risposta 503 Service Unavailable con l’intestazione Retry-After. In questo modo i crawler comprendono che il downtime è temporaneo e non indicizzano la pagina di manutenzione come contenuto permanente.

if ( $maintenance_template = locate_block_template( $template, $slug, [$slug] ) ) {
    nocache_headers();
    status_header( 503 );
    header( 'Retry-After: 3600' ); // suggerisce di riprovare tra un'ora
    return $maintenance_template;
}

Le intestazioni vengono aggiunte solo quando il template di manutenzione è effettivamente servito, quindi non influenzano gli utenti normali.

Creare il template di manutenzione nel Site Editor

1. Vai su Aspetto → Editor.
2. Nella sezione Templates scegli Aggiungi nuovo.
3. Inserisci Maintenance come nome; WordPress assegnerà automaticamente lo slug maintenance.
4. Utilizza il builder a blocchi per comporre la pagina: aggiungi header, footer, logo, messaggio informativo, pulsante di ritorno alla home, ecc.
5. Salva. Il template viene salvato nel database e sarà riconosciuto dal hook.

Poiché il template eredita le Global Styles del tema, tutti i colori, i font e le spaziature saranno coerenti con il resto del sito.

Attivare e disattivare la modalità di manutenzione

• Attivazione: basta creare (o rinominare) il template Maintenance. Il hook lo individua e lo mostra a tutti gli utenti non loggati.
• Disattivazione: rinomina o elimina il template dal Site Editor. Non è necessario rimuovere o modificare il codice dell’hook.

Questo approccio elimina la necessità di gestire file statici o di intervenire sul server ogni volta che il messaggio di manutenzione deve cambiare.

Testare la configurazione

1. Crea il template Maintenance.
2. Esci dall’account amministratore e visita il sito in una nuova finestra o in modalità incognito.
3. Verifica che venga mostrata la pagina appena creata.
4. Rientra con le credenziali di amministratore: dovresti vedere il sito normale, confermando che gli utenti loggati bypassano la modalità.
5. Se hai implementato gli header 503, controlla la risposta HTTP con gli strumenti di sviluppo del browser o con curl -I https://tuosito.it.

Considerazioni finali

Una pagina di manutenzione ben curata migliora la percezione del brand durante gli aggiornamenti. Grazie al nuovo hook, la logica di attivazione rimane nel codice del tema, mentre la parte grafica è gestita interamente dal Site Editor, consentendo a chi si occupa dei contenuti di aggiornare il messaggio senza coinvolgere gli sviluppatori. Questo flusso riduce i tempi di intervento, elimina errori di sincronizzazione tra file e database e mantiene il sito pronto a tornare online con un solo click.

Fonti

• WordPress Developer Blog