include

L'istruzione PHP include

include inserisce il contenuto di un altro file PHP nello script corrente e lo esegue nel punto in cui compare l'istruzione. Concettualmente, PHP copia il file incluso al suo posto, lo valuta nello stesso scope e prosegue. È così che si evita di ripetere markup e logica condivisi — intestazioni, piè di pagina, navigazione, configurazione e funzioni riutilizzabili — su molte pagine.

Questa pagina tratta la sintassi, il funzionamento dello scope, ciò che include restituisce, le differenze rispetto a require e gli errori comuni da evitare.

Sintassi

include 'filename.php';

Il percorso può essere relativo o assoluto. include è un costrutto del linguaggio, non una funzione, quindi le parentesi sono opzionali — sia include 'file.php'; che include('file.php'); funzionano.

Quando PHP esegue un include, cerca il file nel seguente ordine: il percorso indicato (se relativo, risolto rispetto alla directory di lavoro corrente e all'impostazione include_path), poi la directory dello script in esecuzione. Per rendere gli include robusti indipendentemente da dove viene chiamato lo script di ingresso, ancorali al file corrente:

include __DIR__ . '/partials/header.php';

__DIR__ è la directory del file che contiene l'istruzione, quindi l'include si risolve correttamente anche quando lo script viene eseguito da un'altra directory.

Un esempio funzionante

Poiché include opera su file separati, il modo più chiaro per vederlo in azione è creare quei file a runtime. Il frammento seguente scrive un piccolo partial, lo include e stampa il risultato — è completamente eseguibile come script singolo:

<?php
// Create a reusable partial on disk.
file_put_contents(__DIR__ . '/greeting.php', '<?php echo "Hello, " . $name . "!"; ?>');

// Variables defined here are visible inside the included file (shared scope).
$name = "Ada";

echo "Page top\n";
include __DIR__ . '/greeting.php';   // runs greeting.php here
echo "\nPage bottom\n";

// Output:
// Page top
// Hello, Ada!
// Page bottom

Il file incluso può leggere $name perché include condivide lo scope circostante. Questa è la cosa più importante da capire su include: non è un sistema a moduli isolati. Tutte le variabili esistenti prima dell'include sono disponibili nel file incluso, e qualsiasi variabile definita dal file incluso torna disponibile nel chiamante.

Restituire un valore da un file incluso

Un file incluso può eseguire return con un valore, che diventa il risultato dell'espressione include. Questo è il modo idiomatico per caricare la configurazione:

<?php
// Write a config file that returns an array.
file_put_contents(__DIR__ . '/config.php', '<?php return ["env" => "prod", "debug" => false];');

$config = include __DIR__ . '/config.php';

echo $config["env"];        // prod
echo "\n";
var_export($config["debug"]); // false

// Output:
// prod
// false

Se il file incluso non esegue return, l'espressione include restituisce 1 in caso di successo.

include vs require (e le varianti _once)

PHP dispone di quattro istruzioni correlate. Tutte includono un file; si distinguono per cosa accade in caso di errore e se gli include duplicati vengono ignorati.

Regole pratiche:

• Usa require per i file senza i quali lo script non può funzionare (un file di configurazione, una definizione di classe, una connessione al database). Fallire rapidamente con un errore fatale è più sicuro che continuare in uno stato non integro.
• Usa include per elementi opzionali, come un widget nella barra laterale o un blocco pubblicitario, dove un file mancante non dovrebbe far cadere l'intera pagina.
• Usa le varianti _once quando re-includere un file causerebbe errori — più comunemente quando dichiara funzioni o classi, poiché ridichiarare queste ultime è un errore fatale.

Errori comuni

• Fidarsi dell'input dell'utente in un percorso. Non passare mai dati di richiesta non filtrati a include (ad esempio include $_GET['page'] . '.php';). Apre la porta ad attacchi di local file inclusion. Valida invece rispetto a un elenco di file noti consentiti.
• Percorsi relativi che si rompono. Un semplice include 'header.php'; dipende dalla directory di lavoro corrente e può fallire quando lo script viene invocato da altrove. Preferisci percorsi ancorati con __DIR__.
• Ridichiarare funzioni o classi. Se un file che definisce funzioni viene incluso due volte tramite un semplice include, PHP genera un errore fatale "Cannot redeclare". Usa include_once per tali file.
• Assumere isolamento. Poiché lo scope è condiviso, un file incluso può sovrascrivere le tue variabili. Mantieni gli include mirati e prevedibili.

Perché usare include

• Riutilizzabilità — definisci markup o logica condivisi una volta sola e includili in ogni pagina che ne ha bisogno.
• Manutenibilità — modifica la navigazione in un partial e ogni pagina si aggiorna.
• Struttura — suddividi un'applicazione di grandi dimensioni in file piccoli e mirati invece di un unico monolite.

Argomenti correlati

• PHP require e require_once — le controparti che falliscono in modo definitivo.
• PHP include_once — include un file al massimo una volta.
• PHP Functions — ciò che di solito si inserisce nei file condivisi inclusi.
• PHP File Handling — lettura e scrittura di file a runtime.

Pratica