declare

La parola chiave PHP declare

declare è una struttura di controllo PHP che imposta una direttiva di esecuzione per il codice che governa. A differenza della maggior parte delle istruzioni, una direttiva non esegue logica — cambia il modo in cui il motore interpreta il codice circostante. PHP supporta esattamente tre direttive: strict_types (applica le dichiarazioni di tipo), encoding (imposta la codifica dei caratteri dello script) e ticks (un hook di eventi legacy, rimosso in PHP 8.0).

Il motivo più comune per usare declare oggi è una singola riga in cima a un file: declare(strict_types=1);. Questa pagina tratta la sintassi, ogni direttiva e le insidie che possono sorprendere.

Sintassi

Esistono due forme. La forma statement applica la direttiva al resto del file:

declare(directive);

La forma a blocco applica la direttiva solo al codice all'interno delle parentesi graffe:

declare(directive) {
    // code block
}

La forma a blocco è valida solo per ticks. strict_types e encoding devono usare la forma statement e devono essere la prima istruzione nel file (solo <?php può precederle). Usare la forma a blocco con strict_types è un errore fatale.

strict_types: applicare le dichiarazioni di tipo

Per impostazione predefinita, PHP forza gli argomenti scalari per farli corrispondere alle dichiarazioni di tipo di una funzione. Con declare(strict_types=1); questo non avviene — passare il tipo sbagliato lancia un TypeError. Questa è la direttiva che si userà realmente ogni giorno.

Due regole da ricordare:

• Deve essere la prima istruzione nel file. Qualunque cosa la preceda — anche output di spazio bianco o un'altra istruzione — è un errore fatale.
• È per file. La modalità strict si applica alle chiamate effettuate da questo file, in base a dove si trova la chiamata, non a dove è definita la funzione. Una funzione di libreria chiamata da un file strict viene verificata in modo strict; la stessa funzione chiamata da un file non-strict non lo è.

Senza la direttiva, add(2, "3") convertirebbe silenziosamente "3" in 3 e restituirebbe 5 — esattamente il tipo di bug nascosto che strict_types è progettato per portare alla luce.

encoding: dichiarare il set di caratteri dello script

declare(encoding='ISO-8859-1');

Questo indica al motore come interpretare i byte del file script. È raramente necessario sui sistemi moderni, che usano UTF-8 ovunque, ma può essere rilevante per file legacy o configurazioni server specifiche. Ha effetto solo quando PHP è compilato con supporto multibyte.

ticks: un hook di eventi legacy

Un tick è un evento attivato ogni N istruzioni di basso livello eseguite all'interno del blocco declare. Veniva utilizzato per collegare semplici callback (gestione dei segnali, profilazione) a codice altrimenti sincrono. Questa è l'unica direttiva in cui la forma a blocco è significativa:

declare(ticks=1) {
    function tick_handler() {
        echo "tick" . PHP_EOL;
    }
    register_tick_function('tick_handler');

    $a = 1;
    $a += 2;
}

Il numero esatto di tick dipende da quante istruzioni vengono eseguite. La direttiva ticks è stata rimossa in PHP 8.0 — evitarla nel nuovo codice; le alternative moderne includono pcntl_signal per la gestione dei segnali.

Quando usare ciascuna direttiva

• strict_types=1 — inserirla in cima a ogni nuovo file. È l'uso più prezioso di declare e una convenzione quasi universale nel PHP moderno. Vedere PHP Data Types e PHP Functions per capire come funzionano le dichiarazioni di tipo.
• encoding — solo quando si ha effettivamente un file sorgente non-UTF-8 e il supporto multibyte è compilato.
• ticks — da non usare; è stato rimosso a partire da PHP 8.0.

Conclusione

declare imposta direttive di esecuzione per uno script. In pratica significa una sola riga — declare(strict_types=1); — che trasforma la coercizione silenziosa dei tipi in errori espliciti e rende significative le firme delle funzioni. Le direttive encoding e ticks sono rispettivamente di nicchia e legacy, ma conoscerle tutte e tre evita che la sintassi (forma statement vs. forma a blocco) possa sorprendere.

Pratica