require_once

La keyword PHP require_once

require_once include e valuta un file PHP esterno nel punto in cui è scritto l'istruzione — ma solo la prima volta che quel file viene richiesto. Se lo stesso file viene richiesto di nuovo nella stessa richiesta, PHP lo ignora. Questo rende require_once il metodo più sicuro per includere file che definiscono funzioni, classi, trait o costanti, poiché caricarli una seconda volta causerebbe un crash dello script.

Questa pagina tratta la sintassi, il funzionamento della garanzia "once", esempi eseguibili e le differenze tra require_once, require, include e include_once.

Sintassi

La keyword require_once include e valuta un file PHP esterno, assicurando che venga elaborato una sola volta. Ecco la sintassi di base:

La sintassi PHP di require_once

require_once 'path/to/file.php';

Questo include e valuta il contenuto di path/to/file.php, ma solo se non è già stato incluso durante questa richiesta. Poiché è un costrutto del linguaggio (non una funzione), le parentesi sono opzionali — require_once 'file.php'; e require_once('file.php'); si comportano allo stesso modo.

Nota: Se il file specificato non viene trovato, require_once genera un errore fatale e interrompe lo script. La sua controparte include_once emette solo un avviso e lascia continuare lo script.

Come funziona la garanzia "solo una volta"

PHP mantiene un elenco interno dei file già caricati (risolti nei loro percorsi assoluti). Quando incontra un require_once, controlla prima quell'elenco:

• Se il file non è nell'elenco, PHP lo carica ed esegue, quindi lo aggiunge all'elenco.
• Se il file è già nell'elenco, PHP non fa nulla e prosegue.

Questo è ciò che rende require_once sicuro per i file che definiscono elementi. I due file seguenti lo dimostrano. helpers.php definisce una funzione e stampa una riga in modo da poter vedere quando viene effettivamente eseguita:

<?php
// helpers.php
echo "helpers.php is being loaded\n";

function greet($name)
{
    return "Hello, $name!";
}

<?php
// main.php
require_once 'helpers.php';
require_once 'helpers.php'; // second request is silently skipped

echo greet("World") . "\n";

L'esecuzione di main.php stampa:

helpers.php is being loaded
Hello, World!

La riga "helpers.php is being loaded" appare solo una volta, anche se il file è stato richiesto due volte — e la seconda richiesta non ha ri-dichiarato greet(), il che sarebbe altrimenti un errore fatale.

Esempi

Vediamo alcuni esempi pratici di come può essere utilizzata la keyword require_once:

Esempi di PHP require_once

<?php

// Example 1
require_once 'config.php';

// Example 2
function myFunction()
{
  require_once 'helpers.php';
  // Code block here
}

Entrambi gli esempi includono e valutano file esterni esattamente una volta. Ciò previene gli errori che si verificano quando un file viene caricato due volte — più comunemente la ridichiarazione di una funzione o di una classe.

Nota: Sebbene require_once possa essere inserito all'interno di una funzione, il tracciamento delle inclusioni di PHP è globale per l'intera richiesta. Il posizionamento a livello superiore è generalmente preferito; ricorrere all'inclusione all'interno di funzioni solo quando il caricamento deve essere condizionale.

require_once vs le altre keyword di inclusione

PHP dispone di quattro costrutti di inclusione. Differiscono su due assi indipendenti: cosa succede in caso di errore e se il file può essere caricato più di una volta.

Le varianti _once esistono proprio per evitare di rieseguire un file. Con il semplice require, richiedere helpers.php due volte lo esegue due volte — e la seconda esecuzione fallisce fatalmente cercando di ridichiarare greet():

PHP Fatal error: Cannot redeclare function greet() ...

Regola pratica: usa require_once per i file che definiscono elementi (librerie di funzioni, classi, configurazioni che non devono essere eseguite due volte); usa include per i file che producono solo output, come un'intestazione di pagina riutilizzabile che si vuole renderizzare più volte intenzionalmente.

Vantaggi

L'utilizzo della keyword require_once presenta diversi vantaggi, tra cui:

• Prevenzione degli errori: Garantisce che un file venga elaborato una sola volta, evitando errori fatali derivanti dalla ridichiarazione di funzioni, classi o trait.
• Uso efficiente delle risorse: Previene il caricamento e il parsing ridondanti dei file. (Nota: PHP mantiene un piccolo overhead di tracciamento per i file inclusi, ma questo è tipicamente compensato dal costo del re-parsing di file di grandi dimensioni.)

Conclusione

In conclusione, require_once è uno strumento affidabile per includere file PHP esterni prevenendo l'elaborazione duplicata e gli errori fatali. Usalo quando un file deve essere caricato esattamente una volta, e scegli require o include quando hai bisogno di una gestione degli errori diversa o vuoi evitare l'overhead di tracciamento. Speriamo che questa guida ti aiuti a scrivere codice PHP più robusto.

Pratica