require

L'istruzione PHP require

In PHP, require prende il contenuto di un altro file PHP, lo inserisce nel punto in cui compare require e lo valuta come se fosse scritto lì. È il modo in cui i progetti PHP suddividono il codice in più file: configurazione, funzioni di supporto, definizioni di classi e template risiedono ciascuno nel proprio file e vengono inclusi con require.

L'elemento chiave che distingue require dalla sua variante include è come reagisce a un file mancante. Se il file di destinazione non può essere trovato, require interrompe lo script con un errore fatale, mentre include emette solo un avviso e continua l'esecuzione. Questo rende require la scelta giusta per i file senza i quali lo script non può funzionare.

Questa guida tratta la sintassi, esempi eseguibili, la differenza tra require e include, quando usare require_once e le insidie più comuni.

Sintassi

require è un costrutto del linguaggio, non una funzione, quindi può essere scritto con o senza parentesi:

require '/path/to/file.php';
require('/path/to/file.php'); // also valid, but parentheses are unnecessary

In pratica si vogliono quasi sempre percorsi relativi allo script corrente anziché alla directory di lavoro di PHP. La costante magica __DIR__ contiene la directory del file in cui compare, quindi costruire i percorsi a partire da essa mantiene require funzionante indipendentemente da dove viene eseguito lo script:

require __DIR__ . '/config.php';

Un esempio eseguibile

Lo snippet seguente crea un piccolo file helper, lo richiede e poi chiama la funzione che definisce. Puoi incollarlo in un singolo file .php ed eseguirlo — l'helper viene scritto nella stessa directory in fase di esecuzione, quindi l'esempio è autosufficiente.

<?php

// Create a helper file next to this script.
file_put_contents(__DIR__ . '/greet.php', <<<'PHP'
<?php
function greet($name) {
    return "Hello, $name!";
}
PHP);

// Pull the helper in. After this line greet() is available.
require __DIR__ . '/greet.php';

echo greet('Ada'); // Hello, Ada!

Output:

Hello, Ada!

Una volta che un file viene richiesto, tutto ciò che dichiara — funzioni, classi e qualsiasi variabile di primo livello — diventa parte dello scope corrente, esattamente come se lo si fosse digitato inline.

require vs include

Entrambe le istruzioni caricano e valutano un file. L'unica differenza comportamentale è ciò che accade quando il file è mancante o illeggibile:

Usa require per elementi come un file di connessione al database o un autoloader, dove continuare senza di essi non ha senso. Ricorri a include solo quando un file mancante deve essere tollerato — ad esempio, un override opzionale del tema.

require_once: evitare il doppio caricamento

Richiedere lo stesso file due volte causa problemi: ridichiarare una funzione o una classe è di per sé un errore fatale. require_once risolve questo problema ricordando quali file sono già stati caricati e ignorando qualsiasi richiesta ripetuta.

<?php
require_once __DIR__ . '/User.php'; // loads the file
require_once __DIR__ . '/User.php'; // already loaded — does nothing

Come regola generale, usa require_once per i file che definiscono elementi (classi, librerie di funzioni) e il semplice require per i file che intendi eseguire più di una volta, come un template renderizzato in un ciclo. La stessa distinzione once/non-once esiste per include come include_once.

Pattern comuni

Un file di configurazione condiviso caricato all'inizio di uno script di ingresso:

<?php
require __DIR__ . '/config.php';

// $dbHost, $dbUser, etc. defined in config.php are now available.
$pdo = new PDO("mysql:host=$dbHost", $dbUser, $dbPass);

Un file richiesto può anche restituire un valore tramite return, che require valuta. Questo è un modo pulito per caricare un array di configurazione:

// config.php
<?php
return [
    'host' => 'localhost',
    'port' => 3306,
];

// index.php
<?php
$config = require __DIR__ . '/config.php';
echo $config['port']; // 3306

Insidie comuni

• Costruisci i percorsi da __DIR__, non da stringhe relative. require 'config.php' viene risolto rispetto alla directory di lavoro corrente di PHP, che può differire dalla posizione dello script e causare errori silenziosi con server web o invocazioni CLI diverse.
• require viene eseguito nel punto in cui compare. Inserirlo all'interno di una funzione (come nell'esempio sopra) differisce il caricamento fino alla chiamata di quella funzione e limita eventuali variabili di primo livello del file allo scope di quella funzione.
• Preferisci un autoloader per le classi. Richiedere manualmente decine di file di classe è soggetto a errori. I progetti moderni usano vendor/autoload.php di Composer (caricato una volta con require) e lasciano all'autoloading PSR-4 il compito di includere le classi su richiesta.

Conclusione

require è il fondamento dell'organizzazione del codice in PHP: suddivide un programma in file mirati e carica quelli da cui uno script dipende, fallendo in modo evidente se qualcuno manca. Costruisci i percorsi da __DIR__, scegli require_once per le definizioni per evitare il doppio caricamento, e usa include solo quando un file mancante è accettabile. Per le librerie di classi, un autoloader Composer è il moderno sostituto delle liste require scritte a mano.

Esercitazione