PHP Include

Introduzione

Le istruzioni include e require di PHP permettono di inserire il contenuto di un file PHP in un altro prima che il server lo esegua. Questo è il fondamento del riutilizzo del codice in PHP: invece di copiare una barra di navigazione, una connessione al database o un insieme di funzioni di supporto in ogni pagina, lo scrivi una volta in un file separato e lo includi ovunque sia necessario.

Questo capitolo tratta tutte e quattro le istruzioni di inclusione (include, require, include_once, require_once), le loro differenze, il comportamento di variabili e funzioni nei file inclusi, gli errori più comuni e le best practice per mantenere i progetti più grandi.

Perché usare l'inclusione di file

Suddividere il codice in file riutilizzabili offre tre vantaggi concreti:

1. Meno ripetizioni. Scrivi un'intestazione, un piè di pagina o un blocco di configurazione una volta sola e includilo in tutte le pagine necessarie. Modificalo in un unico punto e tutte le pagine si aggiornano.
2. Manutenzione più semplice. Una correzione di bug o una modifica al markup condiviso avviene in un singolo file anziché in decine di pagine.
3. Migliore organizzazione. Suddividere uno script di grandi dimensioni in file più piccoli con nomi che ne indicano lo scopo (header.php, db.php, functions.php) rende il codice più facile da leggere e navigare.

Le quattro istruzioni di inclusione

PHP offre quattro istruzioni. Tutte copiano il contenuto di un file nello script corrente, ma differiscono nel modo in cui gestiscono un file mancante e nel fatto che permettano la re-inclusione.

Regola generale: usa require (o require_once) per i file senza i quali la pagina non può funzionare — una connessione al database o una definizione di classe. Usa include per elementi opzionali, come un blocco pubblicitario o una barra laterale che è utile avere ma non critica.

Sintassi di base

<?php
// Include a file relative to the current script
include __DIR__ . '/header.php';

// Stop the page if a critical file is missing
require __DIR__ . '/db.php';

// Guarantee a file is loaded at most once
require_once __DIR__ . '/functions.php';
?>

__DIR__ è una costante magica che si risolve nella directory del file corrente. Costruire i percorsi a partire da essa fa sì che le inclusioni funzionino indipendentemente dalla directory da cui viene eseguito lo script — vedi PHP Constants per ulteriori informazioni sulle costanti magiche.

Perché _once è importante

Se includi due volte un file che definisce una funzione o una classe, PHP genera un errore fatale "Cannot redeclare" al secondo passaggio. include_once e require_once tengono traccia dei file già caricati e ignorano silenziosamente i duplicati, quindi sono la scelta sicura predefinita per qualsiasi file che dichiari funzioni o classi.

<?php
require_once __DIR__ . '/functions.php'; // loads it
require_once __DIR__ . '/functions.php'; // skipped — no redeclare error
?>

Scope delle variabili nei file inclusi

Un file incluso viene eseguito nell'ambito della riga in cui è stato incluso. Le variabili definite prima dell'include sono disponibili all'interno del file incluso, e le variabili che il file incluso definisce diventano disponibili in seguito.

<?php
// config.php
$siteName = "My Site";
$year = 2026;

<?php
// index.php
include __DIR__ . '/config.php';
echo "Welcome to $siteName ($year)";
// Output: Welcome to My Site (2026)
?>

All'interno di una funzione, tuttavia, le variabili di un file incluso sono locali a quella funzione. Questo inganna spesso gli sviluppatori — un file di configurazione incluso all'interno di una funzione non trasferirà le sue variabili all'ambito globale.

Restituire un valore da un file incluso

Un file incluso può usare return per restituire un valore, il che è utile per gli array di configurazione:

<?php
// settings.php
return [
    'debug'   => true,
    'timezone' => 'UTC',
];

<?php
// app.php
$config = include __DIR__ . '/settings.php';
echo $config['timezone']; // Output: UTC
?>

Gestire i file mancanti correttamente

Con include, un file mancante genera solo un avviso, quindi il resto della pagina viene comunque visualizzato. Se un file è opzionale, verificarne prima l'esistenza:

<?php
$sidebar = __DIR__ . '/sidebar.php';

if (file_exists($sidebar)) {
    include $sidebar;
} else {
    echo "<!-- sidebar unavailable -->";
}
?>

Per i file di cui la pagina ha realmente bisogno, preferisci require in modo che lo script fallisca rapidamente e in modo evidente anziché produrre output non valido.

Best practice

1. Usa require_once per il codice, include per l'output opzionale. Le definizioni di funzioni/classi non dovrebbero mai essere caricate due volte; i frammenti di interfaccia opzionali possono degradarsi con grazia.
2. Costruisci i percorsi a partire da __DIR__. Evita percorsi relativi come include 'header.php', che dipendono dalla directory di lavoro corrente e si interrompono inaspettatamente.
3. Nomina i file in base allo scopo. header.php, footer.php, db.php, auth.php — il nome del file dovrebbe indicare subito cosa contiene.
4. Mantieni i file inclusi focalizzati. Una sola responsabilità per file li rende facili da riutilizzare e da comprendere.
5. Non includere mai un percorso costruito dall'input dell'utente (es. include $_GET['page']). Questo apre una vulnerabilità di tipo Local/Remote File Inclusion. Usa invece una whitelist di valori consentiti.

Conclusione

La famiglia di istruzioni include e require è il modo in cui i progetti PHP rimangono DRY: markup condiviso, configurazione e logica risiedono in file singoli e vengono inclusi nelle pagine all'occorrenza. Usa require/require_once quando un file è obbligatorio, include/include_once quando è opzionale, ancora sempre i percorsi con __DIR__ e non includere mai un percorso controllato dall'utente. Successivamente, consulta PHP Functions per organizzare la logica riutilizzabile che di solito inserirai nei file inclusi.

Diagramma

graph TD;
A[PHP Page]-->B[Included File];

Pratica