include_once

L'istruzione PHP include_once

include_once include e valuta un file durante l'esecuzione, ma solo se quel file non è già stato incluso nella richiesta corrente. Se lo stesso file viene richiesto di nuovo con include_once, PHP lo ignora silenziosamente. Questo la rende la scelta sicura per i file che definiscono funzioni, classi o costanti — includere un tale file due volte causerebbe altrimenti un errore fatale di "cannot redeclare".

Questa pagina tratta la sintassi, le differenze tra include_once e include e require_once, il valore restituito e i casi comuni in cui viene effettivamente utilizzata.

Sintassi

include_once è un costrutto del linguaggio, quindi le parentesi sono facoltative:

include_once 'filename.php';
include_once('filename.php'); // also valid

PHP traccia il file tramite il suo percorso reale risolto. Quindi include_once 'lib.php' e include_once './lib.php' che puntano allo stesso file su disco vengono trattati come la stessa inclusione — il secondo viene ignorato.

Come include_once decide se includere

La regola è una-sola-inclusione-per-richiesta. L'esempio seguente usa tempnam() per creare un file reale in fase di esecuzione, scrivere una definizione di funzione al suo interno, quindi includerlo due volte. Includere una definizione di funzione due volte con il semplice include causerebbe un errore; include_once no.

<?php

// Create a real file that defines a function.
$libFile = tempnam(sys_get_temp_dir(), 'lib');
file_put_contents($libFile, '<?php function greet($name) { return "Hello, $name!"; }');

include_once $libFile; // file is loaded, function defined
echo greet('Ada'), "\n";

include_once $libFile; // already included -> skipped, no redeclare error
echo greet('Linus'), "\n";

unlink($libFile);

// Output:
// Hello, Ada!
// Hello, Linus!

Il secondo include_once non fa nulla perché il file era già stato caricato, quindi greet() non viene mai ridichiarata.

Valore restituito

include_once restituisce 1 per una nuova inclusione (quando il file non ha un return esplicito), e true se il file era già stato incluso. Se il file non viene trovato, emette un avviso e restituisce false (lo script non viene interrotto — questo è il comportamento di require_once).

<?php

$result = include_once 'this-file-does-not-exist.php';
var_dump($result); // bool(false), plus a warning

// Output:
// bool(false)

Un file può anche restituire un valore, il che è utile per i file di configurazione:

<?php

// config.php would contain: <?php return ['debug' => true];
$config = include_once 'config.php';

include_once vs gli altri tre

PHP dispone di quattro costrutti per l'inclusione di file. Differiscono su due dimensioni — una volta o ogni volta e avviso o errore fatale se il file manca:

Usa include_once quando il file è facoltativo ma non deve essere caricato due volte. Usa require_once quando il file è essenziale (una classe senza la quale il codice non può funzionare) e non deve essere caricato due volte.

Quando usarlo

• Librerie di funzioni e classi. Qualsiasi file che dichiara una funzione, una classe o un'interfaccia dovrebbe essere caricato con include_once (o require_once) in modo che un errore di ridichiarazione sia impossibile anche se più parti dell'applicazione lo importano.
• Intestazioni/piè di pagina condivisi. Un header.php che deve essere renderizzato una sola volta per pagina.
• Costanti e configurazione. File che usano define() per le costanti — ridefinire una costante genera un avviso.

Nel PHP moderno, l'autoloader di Composer di solito sostituisce l'inclusione manuale per le classi, ma include_once è ancora diffuso nel codice legacy, nei template e negli script semplici.

Errori comuni

• Protegge contro la doppia inclusione, non dall'ordine di caricamento. include_once non risolve magicamente le dipendenze tra file; impedisce solo che lo stesso file venga caricato due volte.
• Il controllo "once" è per richiesta, non persistente — ogni richiesta HTTP parte da zero.
• I symlink e i diversi percorsi relativi allo stesso file vengono deduplicati tramite il percorso reale, ma un file raggiungibile tramite due percorsi genuinamente diversi (ad es. mount diversi) potrebbe essere incluso due volte.

Conclusione

include_once include un file esattamente una volta per richiesta, prevenendo errori fatali di ridichiarazione e output duplicato. Usalo (o require_once) ogni volta che un file definisce funzioni, classi o costanti. Scegli tra le famiglie include_* e require_* in base al fatto che un file mancante debba essere un avviso recuperabile o un'interruzione definitiva.

Esercizio