getCode()

La méthode PHP getCode()

Lorsque vous interceptez une exception en PHP, vous avez souvent besoin de savoir quelle erreur s'est produite pour réagir différemment à chacune. La méthode Exception::getCode() vous donne exactement cela : elle retourne le code d'erreur entier qui a été associé à l'exception lors de sa création. Cette page explique ce qu'est ce code, comment le définir et le lire, comment il se comporte dans la hiérarchie standard des exceptions, et les pièges courants à éviter.

Si vous débutez avec la gestion des erreurs, commencez par les exceptions PHP et l'instruction try-catch, puis revenez ici.

Ce qu'est le code d'exception

Chaque objet exception PHP contient trois informations essentielles : un message (lu avec getMessage()), une ligne/fichier (lu avec getLine()), et un code. Le code est une valeur définie par le développeur que vous passez en tant que deuxième argument au constructeur de l'exception :

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

getCode() retourne simplement ce deuxième argument. C'est une étiquette que vous choisissez, et non quelque chose que PHP remplit automatiquement. Si vous ne passez pas de code, il vaut par défaut 0.

Syntaxe

public Exception::getCode(): mixed

• Paramètres : aucun.
• Valeur de retour : le code passé au constructeur. Pour la classe de base Exception, il s'agit d'un int (valeur par défaut 0).

Remarque : le type de retour est documenté comme mixed car ErrorException et certaines exceptions PDO utilisent des codes de type string (par exemple, des valeurs SQLSTATE). Pour une Exception ordinaire, attendez-vous à un entier.

Exemple de base

Ici, nous lançons une exception avec le code 100, puis nous le lisons dans le bloc catch :

<?php

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

Sortie :

Message: Database connection failed
Code: 100

Notez que getCode() retourne 100 — la valeur que nous avons passée — tandis que getMessage() retourne le texte. Les deux sont indépendants.

Bifurquer selon le code

L'intérêt d'un code est de permettre à un seul bloc catch de diriger différentes erreurs vers des traitements différents. Les codes ci-dessous sont des constantes arbitraires choisies pour l'application :

<?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();
    }
}

Sortie :

404: Invalid user id

Puisque nous avons appelé loadUser(0), la vérification $id < 1 lance en premier une exception avec ERR_NOT_FOUND (404), c'est donc ce case qui s'exécute.

Le code par défaut est 0

Si vous créez une exception sans code, getCode() retourne 0, et non null :

<?php

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

Sortie :

int(0)

Cela est important lorsque vous bifurquez sur le code : if ($e->getCode()) traite un code absent (0) comme falsy, ce qui est généralement ce que vous souhaitez, mais soyez délibéré à ce sujet.

Classes d'exception personnalisées

Un patron courant consiste à intégrer le code dans une classe d'exception dédiée, de sorte que les appelants n'aient jamais à se souvenir du nombre magique :

<?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();
}

Sortie :

404 User profile not found

Le constructeur de NotFoundException transmet 404 à parent::__construct(), donc getCode() retourne 404 même si le code appelant n'a jamais tapé ce nombre.

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

Ces méthodes sont complémentaires — la plupart des gestionnaires réels lisent les trois.

Pièges courants

• Le code doit être un entier pour Exception. Passer une string (ex. new Exception("x", "ABC")) lève une TypeError dans les versions modernes de PHP. Utilisez plutôt une constante.
• getCode() n'est pas le code de statut HTTP. Ce n'est un code de statut que si vous avez choisi d'en stocker un. PHP ne fait rien avec la valeur elle-même.
• Les exceptions intégrées définissent rarement un code significatif. La plupart des exceptions internes de PHP le laissent à 0 ; ne comptez pas sur une valeur renseignée à moins de l'avoir définie vous-même.
• Les codes de PDOException sont des string SQLSTATE. Lors de l'interception d'erreurs de base de données, getCode() peut retourner quelque chose comme "42S02" (une string), c'est pourquoi le type de retour est mixed.

Bonnes pratiques

1. Définissez des constantes nommées (ou des classes d'exception dédiées) pour les codes plutôt que de disperser des nombres bruts.
2. Gardez les codes stables — d'autres codes et journaux peuvent en dépendre.
3. Journalisez le code avec getMessage() et getLine() pour que les échecs soient traçables.
4. N'exposez pas les codes ou messages internes aux utilisateurs finaux ; mappez-les vers des réponses génériques et sûres.

Conclusion

Exception::getCode() retourne le code entier que vous avez associé lors de la création de l'exception, vous offrant un moyen fiable et lisible par la machine de distinguer une erreur d'une autre. Combinez-le avec getMessage() pour des détails lisibles par l'humain, préférez les constantes nommées ou les classes d'exception personnalisées aux nombres magiques, et n'oubliez pas que certains types d'exception (comme PDOException) utilisent des codes de type string.

Pratique