Лучшие практики обработки ошибок в PHP для поддерживаемого кода

Вы только что развернули новую функцию, и вдруг ваше PHP-приложение выдает фатальную ошибку. Пользователи видят пустую страницу, а ваши логи пусты. Знакомо? Плохая обработка ошибок — одна из самых распространенных причин, по которой PHP-код становится неподдерживаемым. В этой статье мы рассмотрим практические лучшие практики обработки ошибок в PHP, которые сделают ваш код более надежным, простым для отладки и поддержки.

Почему обработка ошибок в PHP важна

PHP по умолчанию снисходителен: он часто продолжает выполнение после предупреждения, а ошибки могут быть молча проигнорированы. Эта гибкость — палка о двух концах. Без правильной обработки ошибки могут:

• Раскрыть конфиденциальную информацию пользователям (например, учетные данные базы данных в трассировках стека).
• Повредить данные или оставить приложение в несогласованном состоянии.
• Сделать отладку кошмаром, потому что ошибки разбросаны или подавлены.

Хорошая обработка ошибок гарантирует, что когда что-то пойдет не так, вы узнаете об этом, сможете быстро исправить, а ваши пользователи получат достойный опыт.

1. Установите подходящие уровни отчетов об ошибках

Первый шаг — правильно настроить отчеты об ошибках PHP для вашей среды. В разработке вы хотите видеть все ошибки; в production вы хотите их логировать, но не отображать.

// Development
ini_set('display_errors', 1);
ini_set('display_startup_errors', 1);
error_reporting(E_ALL);

// Production
ini_set('display_errors', 0);
ini_set('log_errors', 1);
ini_set('error_log', '/path/to/php-error.log');
error_reporting(E_ALL & ~E_DEPRECATED & ~E_STRICT);

Используйте переменные окружения или конфигурационные файлы для автоматического переключения между этими настройками. Никогда не полагайтесь на ручное редактирование php.ini на production-серверах.

2. Используйте исключения вместо кодов ошибок

Возврат кодов ошибок (например, false или -1) — это устаревший шаблон, который загромождает код и позволяет легко игнорировать сбои. Исключения заставляют вас явно обрабатывать ошибки и сохраняют ваш основной путь чистым.

// Bad: error code
function getUser($id) {
    $user = db_find($id);
    if (!$user) {
        return false; // caller must check
    }
    return $user;
}

// Good: exception
function getUser($id) {
    $user = db_find($id);
    if (!$user) {
        throw new UserNotFoundException("User $id not found");
    }
    return $user;
}

Создавайте пользовательские классы исключений для разных типов ошибок. Это упрощает перехват конкретных ошибок и их правильную обработку.

3. Перехватывайте исключения на правильном уровне

Распространенная ошибка — перехватывать исключения слишком рано или слишком широко. Перехватывайте исключения только тогда, когда вы действительно можете что-то с ними сделать — залогировать, повторить попытку или показать понятное пользователю сообщение.

try {
    $user = getUser($id);
    $order = createOrder($user, $items);
} catch (UserNotFoundException $e) {
    // Handle missing user specifically
    return response('User not found', 404);
} catch (PaymentFailedException $e) {
    // Handle payment failure
    return response('Payment failed: ' . $e->getMessage(), 400);
} catch (Throwable $e) {
    // Catch-all for unexpected errors
    log_error($e);
    return response('Something went wrong', 500);
}

Используйте Throwable (PHP 7+), чтобы перехватывать как исключения, так и ошибки. Избегайте пустых блоков catch — если перехватываете, делайте что-то осмысленное.

4. Логируйте ошибки с контекстом

Логирование — ваш лучший друг для отладки проблем в production. Но сообщение в логе типа "Error occurred" бесполезно. Включайте контекст: ID пользователя, параметры запроса, трассировку стека и временные метки.

try {
    processPayment($order);
} catch (PaymentException $e) {
    error_log(sprintf(
        "Payment failed for order %d: %s in %s:%d\nStack trace: %s",
        $order->id,
        $e->getMessage(),
        $e->getFile(),
        $e->getLine(),
        $e->getTraceAsString()
    ));
    throw $e; // re-throw after logging
}

Рассмотрите использование библиотеки логирования, такой как Monolog, для структурированных логов. Она поддерживает различные обработчики (файл, syslog, Slack) и уровни логирования (debug, info, warning, error).

5. Создайте пользовательский обработчик ошибок

Стандартный обработчик ошибок PHP выводит ошибки на экран, что не подходит для production. Пользовательский обработчик ошибок позволяет преобразовывать ошибки в исключения, логировать их или отображать дружественную страницу ошибки.

set_error_handler(function ($severity, $message, $file, $line) {
    if (!(error_reporting() & $severity)) {
        return false; // respect error_reporting settings
    }
    throw new ErrorException($message, 0, $severity, $file, $line);
});

set_exception_handler(function ($e) {
    log_error($e);
    http_response_code(500);
    include 'views/error.php';
});

register_shutdown_function(function () {
    $error = error_get_last();
    if ($error && in_array($error['type'], [E_ERROR, E_PARSE, E_CORE_ERROR, E_COMPILE_ERROR])) {
        log_error(new ErrorException($error['message'], 0, $error['type'], $error['file'], $error['line']));
    }
});

Эта настройка гарантирует, что все ошибки — включая фатальные — логируются и обрабатываются корректно.

6. Проверяйте входные данные и рано завершайте работу

Многие ошибки происходят из-за неверных входных данных. Проверяйте данные на границах вашего приложения (контроллеры, API-эндпоинты) и немедленно выбрасывайте исключения, если валидация не проходит. Это предотвращает распространение ошибок глубоко в ваш код.

function createUser(array $data) {
    if (empty($data['email'])) {
        throw new InvalidArgumentException('Email is required');
    }
    if (!filter_var($data['email'], FILTER_VALIDATE_EMAIL)) {
        throw new InvalidArgumentException('Invalid email format');
    }
    // ... proceed with confidence
}

Используйте функции фильтрации PHP или библиотеку валидации (например, Respect\Validation) для поддержания согласованности валидации.

7. Не подавляйте ошибки с помощью @

Оператор @ заглушает ошибки, усложняя отладку. Заманчиво использовать его при вызове функций, которые могут выдавать предупреждения (например, file_get_contents), но он скрывает реальные проблемы. Вместо этого проверяйте предварительные условия или используйте try-catch с исключениями.

// Bad
$content = @file_get_contents($url);

// Good
if (!is_readable($url)) {
    throw new RuntimeException("Cannot read $url");
}
$content = file_get_contents($url);

Если вам все же нужно подавить ошибку, делайте это только для хорошо понятных случаев и документируйте причину.

8. Используйте централизованное промежуточное ПО для обработки ошибок

В таких фреймворках, как Laravel или Symfony, обработка ошибок часто централизована в промежуточном ПО или обработчике исключений. Если вы создаете свой собственный, создайте единую точку входа, которая перехватывает все исключения и преобразует их в HTTP-ответы.

// In your front controller (index.php)
try {
    $response = $router->dispatch($request);
} catch (HttpException $e) {
    $response = new Response($e->getMessage(), $e->getStatusCode());
} catch (Throwable $e) {
    log_error($e);
    $response = new Response('Internal Server Error', 500);
}
$response->send();

Это держит логику обработки ошибок в одном месте и обеспечивает согласованность.

Сравнение: Подходы к обработке ошибок

FAQ

В чем разница между ошибками и исключениями в PHP?

Ошибки — это низкоуровневые проблемы, такие как синтаксические ошибки или ошибки типов, в то время как исключения — это выбрасываемые объекты, представляющие исключительные ситуации. В PHP 7+ оба реализуют интерфейс Throwable, поэтому вы можете перехватывать их одним блоком catch.

Стоит ли использовать try-catch для каждого вызова функции?

Нет, это приводит к чрезмерно защитному коду. Перехватывайте исключения только тогда, когда вы можете осмысленно их обработать — залогировать, повторить попытку или показать понятное пользователю сообщение. Позвольте исключениям всплывать к центральному обработчику для неожиданных случаев.

Как логировать ошибки, не раскрывая конфиденциальные данные?

Очищайте сообщения логов, удаляя пароли, токены и персональные данные. Используйте структурированное логирование с полями контекста и настройте библиотеку логирования для редактирования чувствительных ключей. Также убедитесь, что файлы логов хранятся безопасно и доступ к ним ограничен.

Готовы оптимизировать обработку ошибок в PHP? Начните с аудита текущих настроек отчетов об ошибках и внедрения пользовательского обработчика ошибок. Для быстрой отладки JSON-полезных нагрузок или логов попробуйте наш JSON Formatter, чтобы проверить и отформатировать ваши данные.