getCode()

Метод PHP getCode()

Когда вы перехватываете исключение в PHP, часто нужно знать, какая именно ошибка произошла, чтобы по-разному реагировать на каждую из них. Метод Exception::getCode() даёт именно это: он возвращает целочисленный код ошибки, который был прикреплён к исключению при его создании. На этой странице рассматривается, что представляет собой код, как его задавать и читать, как он ведёт себя в стандартной иерархии исключений, и какие ловушки могут вас подстерегать.

Если вы только знакомитесь с обработкой ошибок, начните с исключений PHP и оператора try-catch, а затем вернитесь сюда.

Что такое код исключения

Каждый объект исключения PHP содержит три ключевых элемента информации: сообщение (читается с помощью getMessage()), строку/файл (читается с помощью getLine()) и код. Код — это значение, определяемое разработчиком, которое передаётся вторым аргументом в конструктор исключения:

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

getCode() просто возвращает этот второй аргумент. Это метка, которую вы выбираете, — PHP не заполняет её автоматически. Если код не передан, по умолчанию используется 0.

Синтаксис

public Exception::getCode(): mixed

• Параметры: отсутствуют.
• Возвращаемое значение: код, переданный в конструктор. Для базового класса Exception это int (по умолчанию 0).

Примечание: возвращаемый тип задокументирован как mixed, потому что ErrorException и некоторые исключения PDO используют string-коды (например, значения SQLSTATE). Для обычного Exception следует ожидать целое число.

Базовый пример

Здесь мы бросаем исключение с кодом 100, а затем читаем его в блоке catch:

<?php

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

Вывод:

Message: Database connection failed
Code: 100

Обратите внимание: getCode() возвращает 100 — значение, которое мы передали, — а getMessage() возвращает текст. Эти два метода независимы друг от друга.

Ветвление по коду

Весь смысл кода в том, чтобы позволить одному блоку catch направлять разные ошибки в разные обработчики. Приведённые ниже коды — произвольные константы, выбранные для приложения:

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

Вывод:

404: Invalid user id

Поскольку мы вызвали loadUser(0), проверка $id < 1 бросает исключение первой с ERR_NOT_FOUND (404), и выполняется соответствующий case.

Код по умолчанию равен 0

Если создать исключение без кода, getCode() вернёт 0, а не null:

<?php

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

Вывод:

int(0)

Это важно учитывать при ветвлении по коду: if ($e->getCode()) воспринимает отсутствующий код (0) как ложное значение, что обычно и требуется, — но стоит делать это осознанно.

Пользовательские классы исключений

Распространённый паттерн — встраивать код в специальный класс исключений, чтобы вызывающий код не запоминал «магические числа»:

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

Вывод:

404 User profile not found

Конструктор NotFoundException передаёт 404 в parent::__construct(), поэтому getCode() возвращает 404, даже если вызывающий код никогда явно не указывал это число.

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

Эти методы дополняют друг друга — большинство реальных обработчиков читают все три.

Типичные ловушки

• Код должен быть целым числом для Exception. Передача string (например, new Exception("x", "ABC")) вызывает TypeError в современном PHP. Используйте константы.
• getCode() — это не HTTP-код статуса. Это код статуса только в том случае, если вы решили хранить его там. PHP никак не использует это значение само по себе.
• Встроенные исключения редко устанавливают значимый код. Большинство базовых PHP-исключений оставляют его равным 0 — не полагайтесь на него, если не задали его явно.
• Коды PDOException — это SQLSTATE-string. При перехвате ошибок базы данных getCode() может вернуть что-то вроде "42S02" (string), поэтому возвращаемый тип и является mixed.

Рекомендации

1. Определяйте именованные константы (или классы исключений) для кодов вместо того, чтобы разбрасывать по коду «магические числа».
2. Держите коды стабильными — другой код и логи могут зависеть от них.
3. Логируйте код вместе с getMessage() и getLine(), чтобы ошибки можно было отследить.
4. Не передавайте внутренние коды или сообщения конечным пользователям — преобразовывайте их в безопасные, универсальные ответы.

Заключение

Exception::getCode() возвращает целочисленный код, прикреплённый к исключению при его создании, предоставляя надёжный, машиночитаемый способ различать одну ошибку от другой. Сочетайте его с getMessage() для получения понятных человеку деталей, предпочитайте именованные константы или пользовательские классы исключений «магическим числам» и помните, что некоторые типы исключений (например, PDOException) используют string-коды.

Практика