trigger_error()

Introduzione

trigger_error() consente al tuo codice di generare un messaggio di errore PHP nello stesso modo in cui il motore genera quelli predefiniti. È il metodo standard per segnalare che una funzione è stata chiamata in modo errato — un argomento mancante, un valore fuori intervallo, una chiamata deprecata — senza lanciare un'eccezione o stampare un echo improvvisato. Poiché il messaggio scorre attraverso la normale pipeline degli errori di PHP, rispetta error_reporting, può essere registrato automaticamente e può essere intercettato da un gestore di errori personalizzato.

Questa pagina spiega cosa fa trigger_error(), la sua sintassi e i livelli di errore, e mostra un esempio eseguibile per ciascun livello oltre a un caso d'uso pratico di validazione dell'input.

Cos'è la funzione trigger_error()?

trigger_error() genera un errore a livello utente — un errore che il tuo programma genera intenzionalmente, al contrario di uno generato autonomamente dal motore PHP. Quando la chiami, PHP si comporta esattamente come se avesse incontrato quell'errore da solo: applica la maschera corrente di error_reporting, invia il messaggio al gestore di errori attivo (o a quello predefinito) e può interrompere lo script a seconda del livello.

Due cose sono facili da sbagliare:

• trigger_error() genera un errore, non un'eccezione. Non verrà catturata da try/catch a meno che un gestore personalizzato non la converta in un'eccezione (un pattern comune mostrato di seguito).
• La funzione restituisce sempre false, quindi return trigger_error(...) è raramente quello che si vuole.

Sintassi di trigger_error()

trigger_error(string $message, int $error_level = E_USER_NOTICE): bool

Il livello di errore deve essere uno tra:

• E_USER_ERROR — un errore fatale. Con il gestore predefinito interrompe immediatamente lo script. Con un gestore personalizzato lo script continua a meno che il gestore non lo fermi (restituisce false e lascia che PHP prosegua, oppure chiama exit()).
• E_USER_WARNING — un avviso non fatale. Lo script continua l'esecuzione.
• E_USER_NOTICE — un messaggio informativo. Lo script continua l'esecuzione. È il valore predefinito.

Passare qualsiasi altra costante (ad esempio E_WARNING) genera un E_USER_WARNING proprio e ignora il valore fornito.

trigger_error() rispetta il livello corrente di error_reporting: se il livello attivato è mascherato, non viene segnalato nulla. Quindi se è impostato error_reporting(E_ALL & ~E_USER_NOTICE), un notice che attivi viene eliminato silenziosamente.

Nota per PHP 8.4+: attivare E_USER_ERROR è deprecato. Lanciare un'eccezione è ora il metodo raccomandato per segnalare una condizione fatale a livello utente. Gli altri due livelli rimangono completamente supportati.

Un semplice notice con il gestore predefinito

L'utilizzo minimo di trigger_error() è una singola chiamata. Con il gestore di errori predefinito di PHP e la visualizzazione abilitata, stampa una riga formattata e l'esecuzione continua (i notice non sono fatali):

<?php
echo "Before\n";
trigger_error("Something worth noting", E_USER_NOTICE);
echo "After\n";

Output (con display_errors attivo):

Before

Notice: Something worth noting in /path/to/script.php on line 3
After

Lo script raggiunge l'echo finale perché un notice non interrompe l'esecuzione.

Distinguere i livelli con un gestore personalizzato

Un gestore di errori personalizzato ti dà il pieno controllo su come viene reso ciascun livello. Il gestore riceve il numero di livello come $errno, quindi puoi mapparlo a un'etichetta e decidere cosa fare.

<?php
function custom_error_handler($errno, $errstr, $errfile, $errline) {
  $label = match ($errno) {
    E_USER_ERROR   => 'ERROR',
    E_USER_WARNING => 'WARNING',
    E_USER_NOTICE  => 'NOTICE',
    default        => 'UNKNOWN',
  };
  echo "[$label] $errstr (line $errline)\n";
  // Returning true tells PHP we handled it, so the default handler is skipped.
  return true;
}

set_error_handler("custom_error_handler");

trigger_error("Disk is almost full", E_USER_NOTICE);
trigger_error("Cache miss, falling back to DB", E_USER_WARNING);

echo "Script finished\n";

Output:

[NOTICE] Disk is almost full (line 16)
[WARNING] Cache miss, falling back to DB (line 17)
Script finished

Il gestore restituisce true, indicando a PHP che l'errore è stato gestito, quindi il gestore predefinito viene saltato e lo script continua. Il ramo E_USER_ERROR è mantenuto nel match per completezza, ma tieni presente che con il gestore predefinito un E_USER_ERROR interromperebbe lo script prima di "Script finished" — e su PHP 8.4+ attivare quel livello è deprecato.

Utilizzo pratico: validazione degli argomenti di una funzione

L'uso più comune nel mondo reale di trigger_error() è proteggere una funzione da input non validi — emettendo un avviso quando un chiamante passa qualcosa di non valido, quindi restituendo un valore sicuro predefinito:

<?php
function divide($a, $b) {
  if ($b == 0) {
    trigger_error("divide(): division by zero, returning 0", E_USER_WARNING);
    return 0;
  }
  return $a / $b;
}

echo divide(10, 2), "\n";   // 5
echo divide(10, 0), "\n";   // warning + 0

Output (con display_errors attivo):

5

Warning: divide(): division by zero, returning 0 in /path/to/script.php on line 4
0

Questo pattern mantiene lo stack trace del chiamante e il numero di riga nel messaggio, il che rende molto più facile trovare la chiamata problematica rispetto a un semplice echo.

Convertire gli errori in eccezioni

Se preferisci gestire i problemi con try/catch, un gestore personalizzato può trasformare un errore attivato in un ErrorException. Questo è il ponte tra il sistema degli errori di PHP e il suo sistema delle eccezioni:

<?php
set_error_handler(function ($errno, $errstr, $errfile, $errline) {
  throw new ErrorException($errstr, 0, $errno, $errfile, $errline);
});

try {
  trigger_error("Recoverable problem", E_USER_WARNING);
} catch (ErrorException $e) {
  echo "Caught: " . $e->getMessage() . "\n";
}

Output:

Caught: Recoverable problem

Poiché il gestore lancia un'eccezione, l'avviso non raggiunge mai l'output degli errori predefinito — viene consegnato invece al tuo blocco catch.

Errori comuni

• Non è un'eccezione. Senza un gestore che lancia, try/catch non catturerà un errore attivato.
• error_reporting può nasconderlo. Se il livello è mascherato, il messaggio scompare senza alcuna indicazione. Controlla il livello corrente con error_reporting().
• E_USER_ERROR è deprecato in PHP 8.4+. Lancia un'eccezione (o chiama die()) per le condizioni fatali a livello utente.
• Il messaggio viene troncato a 1024 byte — mantienilo conciso.

Conclusione

trigger_error() è il metodo idiomatico per generare un E_USER_NOTICE, E_USER_WARNING o (legacy) E_USER_ERROR a livello utente. Inserisce i tuoi messaggi nella pipeline standard di PHP in modo che rispettino error_reporting, possano essere registrati e possano essere intercettati da un gestore di errori personalizzato — o convertiti in eccezioni quando vuoi la semantica try/catch. Per il nuovo codice a livello fatale, preferisci lanciare eccezioni piuttosto che usare E_USER_ERROR.

Pratica