include()

L'istruzione include() include e valuta il file specificato.

La documentazione seguente si applica anche a require(). I due costrutti sono identici in ogni aspetto eccetto per come essi trattano gli errori. include() produce un Warning mentre require() restituisce un Fatal Error. In altre parole, usate require() se volete che un file mancante fermi l'esecuzione della pagina. include() non si comporta in questo modo, lo script continuerà nonostante tutto. Assicuratevi di avere un appropriato include_path impostato a dovere.

Quando un file viene incluso, il codice che esso contiene eredita lo scope delle variabili della riga in cui si verifica l'inclusione. Qualsiasi variabile disponibile in quella riga nella chiamata al file sarà disponibile all'interno del file chiamato, da quel punto in avanti.

Esempio 16-3. Esempio di base con include() vars.php <?php $colore = 'verde'; $frutto = 'mela'; ?> test.php <?php echo "Una $frutto $colore"; // Una include 'vars.php'; echo "Una $frutto $colore"; // Una mela verde ?>

Se l'inclusione si verifica dentro una funzione all'interno del file chiamato, allora tutto il codice contenuto nel file chiamato si comporterà come se esso sia stato definito all'interno di una funzione. Così, esso seguirà lo scope delle variabili di quella funzione.

Esempio 16-4. Inclusione all'interno di funzioni <?php function foo() { global $frutto;     include 'vars.php';     echo "Una $frutto $colore"; } /* vars.php è nello scope di foo() così    * * $colore NON è disponibile fuori di      * * questo scope. $frutto si perchè è stato * * dichiarato globale.                     */ foo();                        // Una mela verde echo "Una $frutto $colore";   // Una mela ?>

Quando un file viene incluso, il parsing esce dalla modalità PHP e entra in modalità HTML all'inizio del file incluso, e riprende alla fine. Per questa ragione, qualunque codice all'interno del file incluso che dovrebbe essere eseguito come codice PHP deve essere incluso all'interno dei tag PHP validi di apertura e chiusura.

Se "URL fopen wrappers" nel PHP sono abilitati (come nella configurazione di default), potete specificare il file da includere usando un URL (via HTTP) invece che un percorso locale. Se il server chiamato interpreta il file incluso come codice PHP, le variabili possono essere passate al file incluso usando una stringa di richiesta URL come con l'utilizzo di HTTP GET. Non è proprio parlare della stessa cosa includere il file e averlo ereditato dallo scope di variabili del file chiamante; lo script è stato attualmente eseguito su un server remoto e il risultato è poi stato incluso nello script locale.

Esempio 16-5. include() attraverso HTTP <?php /* Questo esempio assume che www.example.com è configurato per eseguire file * * .php e non file .txt. Anche, 'Funziona' qui significa che le variabili    * * $foo e $bar sono disponibili all'interno del file incluso.                */ // Non funzionerà; file.txt non è stato trattato da www.example.com come PHP include 'http://www.example.com/file.txt?foo=1&bar=2'; // Non funzionerà; cercare un file chiamato'file.php?foo=1&bar=2' nel // filesystem locale. include 'file.php?foo=1&bar=2'; // Funziona. include 'http://www.example.com/file.php?foo=1&bar=2'; $foo = 1; $bar = 2; include 'file.txt';  // Funziona. include 'file.php';  // Funziona. ?>

Vedere anche Remote files, fopen() e file() per informazioni correlate.

Poichè include() e require() sono speciali costrutti di linguaggio, dovete includerli all'interno di blocchi di istruzioni se si trovano in un blocco condizionale.

Esempio 16-6. include() e i blocchi condizionali <?php // Questo NON VA BENE e non funzionerà come desiderato. if ($condizione)     include $file; else     include $un_altro; // Questo è CORRETTO. if ($condizione) {     include $file; } else {     include $un_altro; } ?>

Trattamento dei valori restituiti: È possibile eseguire un'istruzione return() in un file incluso per terminare l'esecuzione di quel file e restituirlo allo script che l'ha chiamato. È anche possibile restituire valori dai file inclusi. Potete prendere il valore di una chiamata di inclusione come fareste con una normale funzione.

Esempio 16-7. include() and the return() statement return.php <?php $var = 'PHP'; return $var; ?> noreturn.php <?php $var = 'PHP'; ?> testreturns.php <?php $foo = include 'return.php'; echo $foo; // stampa 'PHP' $bar = include 'noreturn.php'; echo $bar; // stampa 1 ?>

$bar ha valore 1 perchè l'inclusione è stata eseguita con successo. Notare la differenza tra gli esempi sopra. Il primo usa return() all'interno di un file incluso mentre l'altro no. Pochi altri modi di "includere" file in variabili sono con fopen(), file() o usando include() insieme con Output Control Functions.

Vedere anche require(), require_once(), include_once(), readfile(), virtual(), e include_path.