getCode()

Il metodo PHP getCode()

Quando si cattura un'eccezione in PHP, spesso è necessario sapere quale errore si è verificato per poter reagire in modo diverso a ciascuno. Il metodo Exception::getCode() fornisce esattamente questo: restituisce il codice di errore intero che era stato associato all'eccezione al momento della sua creazione. Questa pagina illustra cos'è il codice, come impostarlo e leggerlo, come si comporta nella gerarchia standard delle eccezioni e i tranelli in cui è facile cadere.

Se sei alle prime armi con la gestione degli errori, inizia con le eccezioni PHP e l'istruzione try-catch, poi torna qui.

Cos'è il codice di eccezione

Ogni oggetto eccezione PHP porta tre informazioni fondamentali: un messaggio (letto con getMessage()), una riga/file (letta con getLine()) e un codice. Il codice è un valore definito dallo sviluppatore che si passa come secondo argomento al costruttore dell'eccezione:

new Exception(string $message = "", int $code = 0, ?Throwable $previous = null)

getCode() restituisce semplicemente quel secondo argomento. È un'etichetta che tu scegli, non qualcosa che PHP inserisce automaticamente. Se non passi un codice, il valore predefinito è 0.

Sintassi

public Exception::getCode(): mixed

• Parametri: nessuno.
• Valore restituito: il codice passato al costruttore. Per la classe base Exception è un int (valore predefinito 0).

Nota: il tipo restituito è documentato come mixed perché ErrorException e alcune eccezioni PDO usano codici string (ad esempio, i valori SQLSTATE). Per un Exception semplice, aspettati un intero.

Esempio di base

Qui lanciamo un'eccezione con il codice 100, poi lo leggiamo nel blocco catch:

<?php

try {
    throw new Exception("Database connection failed", 100);
} catch (Exception $e) {
    echo "Message: " . $e->getMessage() . "\n";
    echo "Code: " . $e->getCode() . "\n";
}

Output:

Message: Database connection failed
Code: 100

Si noti che getCode() restituisce 100 — il valore che abbiamo passato — mentre getMessage() restituisce il testo. I due sono indipendenti.

Ramificazione sul codice

Lo scopo principale di un codice è consentire a un singolo blocco catch di instradare errori diversi a gestori diversi. I codici qui sotto sono costanti arbitrarie scelte per l'applicazione:

<?php

const ERR_DB        = 100;
const ERR_NOT_FOUND = 404;

function loadUser(int $id): string
{
    if ($id < 1) {
        throw new Exception("Invalid user id", ERR_NOT_FOUND);
    }
    // ...imagine a DB lookup that fails...
    throw new Exception("Could not reach the database", ERR_DB);
}

try {
    echo loadUser(0);
} catch (Exception $e) {
    switch ($e->getCode()) {
        case ERR_NOT_FOUND:
            echo "404: " . $e->getMessage();
            break;
        case ERR_DB:
            echo "500: " . $e->getMessage();
            break;
        default:
            echo "Unknown error: " . $e->getMessage();
    }
}

Output:

404: Invalid user id

Poiché abbiamo chiamato loadUser(0), il controllo $id < 1 lancia per primo l'eccezione con ERR_NOT_FOUND (404), quindi viene eseguito quel case.

Il codice predefinito è 0

Se si crea un'eccezione senza un codice, getCode() restituisce 0, non null:

<?php

try {
    throw new Exception("Something went wrong");
} catch (Exception $e) {
    var_dump($e->getCode());
}

Output:

int(0)

Questo è importante quando si ramifica sul codice: if ($e->getCode()) tratta un codice mancante (0) come falsy, che di solito è ciò che si desidera, ma sii consapevole di questo comportamento.

Classi di eccezioni personalizzate

Un pattern comune è incorporare il codice in una classe di eccezione dedicata, così chi chiama non deve ricordare il numero magico:

<?php

class HttpException extends Exception {}

class NotFoundException extends HttpException
{
    public function __construct(string $message = "Not Found")
    {
        parent::__construct($message, 404);
    }
}

try {
    throw new NotFoundException("User profile not found");
} catch (HttpException $e) {
    echo $e->getCode() . " " . $e->getMessage();
}

Output:

404 User profile not found

Il costruttore di NotFoundException passa 404 a parent::__construct(), quindi getCode() restituisce 404 anche se il codice chiamante non ha mai scritto quel numero.

getCode() vs. getMessage() vs. getPrevious()

Questi metodi sono complementari — la maggior parte dei gestori reali li legge tutti e tre.

Tranelli comuni

• Il codice deve essere un intero per Exception. Passare una string (ad es. new Exception("x", "ABC")) genera un TypeError nelle versioni moderne di PHP. Usa invece una costante.
• getCode() non è il codice di stato HTTP. È un codice di stato solo se tu hai scelto di memorizzarne uno. PHP non fa nulla con il valore in sé.
• Le eccezioni built-in raramente impostano un codice significativo. La maggior parte delle eccezioni PHP native lascia il valore a 0; non farci affidamento a meno che non lo abbia impostato tu.
• I codici di PDOException sono string SQLSTATE. Quando si catturano errori di database, getCode() può restituire qualcosa come "42S02" (una string), ed è per questo che il tipo restituito è mixed.

Buone pratiche

1. Definire costanti con nome (o classi di eccezioni) per i codici invece di disseminare numeri grezzi nel codice.
2. Mantenere i codici stabili — altro codice e i log potrebbero dipendere da essi.
3. Registrare il codice insieme a getMessage() e getLine() in modo che i fallimenti siano tracciabili.
4. Non esporre codici o messaggi interni agli utenti finali; mappali a risposte sicure e generiche.

Conclusione

Exception::getCode() restituisce il codice intero che hai associato quando l'eccezione è stata creata, offrendoti un modo affidabile e leggibile dalla macchina per distinguere un errore dall'altro. Abbinalo a getMessage() per dettagli leggibili dall'uomo, preferisci costanti con nome o classi di eccezioni personalizzate rispetto ai numeri magici, e ricorda che alcuni tipi di eccezione (come PDOException) usano codici string.

Esercizio