萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP 異常處理完整指南:錯誤捕獲、致命錯誤處理、日志記錄、自定義異常體系

PHP 有兩套錯誤機制:**錯誤** 和 **異常**。錯誤不可捕獲 (除非設置錯誤處理器),異常可 try-catch。本文構建完整異常處理體系:統一錯誤轉異常、捕獲致命錯誤、分級日志、自定義異常層級、生產環境友好錯誤頁面。

核心概念對比

特性Error (錯誤)Exception (異常)
可被 try-catch 捕獲否 (PHP 7 前)是
觸發方式引擎內部、trigger_errorthrow new Exception
類型E_ERROR, E_WARNING, E_NOTICE...Exception, LogicException, RuntimeException...
腳本繼續執行致命錯誤停止,非致命繼續捕獲後可繼續
PHP 7+ 變化大多數錯誤變為 Error 異常 (實現 Throwable)統一實現 Throwable 接口

統一錯誤處理架構

1. 自定義異常層級

<?php
namespace App\Exception;

abstract class AppException extends \Exception
{
    protected int $httpCode = 500;
    protected string $errorCode = 'INTERNAL_ERROR';
    protected array $context = [];

    public function __construct(string $message = '', int $code = 0, \Throwable $previous = null, array $context = [])
    {
        parent::__construct($message, $code, $previous);
        $this->context = $context;
    }

    public function getHttpCode(): int { return $this->httpCode; }
    public function getErrorCode(): string { return $this->errorCode; }
    public function getContext(): array { return $this->context; }
    public function toArray(): array
    {
        return [
            'error' => $this->errorCode,
            'message' => $this->getMessage(),
            'context' => $this->context,
            'trace' => $this->getTraceAsString(),
        ];
    }
}

// 業務異常
class ValidationException extends AppException
{
    protected $httpCode = 400;
    protected $errorCode = 'VALIDATION_FAILED';
}

class NotFoundException extends AppException
{
    protected $httpCode = 404;
    protected $errorCode = 'NOT_FOUND';
}

class UnauthorizedException extends AppException
{
    protected $httpCode = 401;
    protected $errorCode = 'UNAUTHORIZED';
}

class ForbiddenException extends AppException
{
    protected $httpCode = 403;
    protected $errorCode = 'FORBIDDEN';
}

// 系統異常
class DatabaseException extends AppException
{
    protected $httpCode = 500;
    protected $errorCode = 'DATABASE_ERROR';
}

class ExternalServiceException extends AppException
{
    protected $httpCode = 502;
    protected $errorCode = 'EXTERNAL_SERVICE_ERROR';
}

2. 全局錯誤/異常處理器 (Bootstrap 階段註冊)

<?php
// bootstrap/exceptions.php
use App\Exception\AppException;
use Psr\Log\LoggerInterface; // 假設用 Monolog 或框架 logger

class ExceptionHandler
{
    private LoggerInterface $logger;
    private bool $debug;

    public function __construct(LoggerInterface $logger, bool $debug = false)
    {
        $this->logger = $logger;
        $this->debug = $debug;
    }

    public function register(): void
    {
        // 1. 設置異常處理器
        set_exception_handler([$this, 'handleException']);

        // 2. 設置錯誤處理器 (將錯誤轉為異常)
        set_error_handler([$this, 'handleError']);

        // 3. 註冊關閉函數捕獲致命錯誤
        register_shutdown_function([$this, 'handleShutdown']);
    }

    /** 將 PHP 錯誤轉為 ErrorException 異常 */
    public function handleError(int $severity, string $message, string $file, int $line): bool
    {
        // 錯誤報告級別過濾
        if (!(error_reporting() & $severity)) {
            return false; // 標準處理器處理
        }

        // 非致命錯誤轉為異常拋出
        throw new \ErrorException($message, 0, $severity, $file, $line);
    }

    /** 捕獲致命錯誤 (E_ERROR, E_PARSE, E_CORE_ERROR 等) */
    public function handleShutdown(): void
    {
        $error = error_get_last();
        if ($error && in_array($error['type'], [E_ERROR, E_PARSE, E_CORE_ERROR, E_COMPILE_ERROR, E_USER_ERROR])) {
            // 構造 ErrorException 模擬異常
            $exception = new \ErrorException(
                $error['message'],
                $error['type'],
                $error['type'],
                $error['file'],
                $error['line']
            );
            $this->handleException($exception);
        }
    }

    /** 統一異常處理入口 */
    public function handleException(\Throwable $exception): void
    {
        // 1. 記錄日志
        $this->logException($exception);

        // 2. 根據環境輸出
        if ($this->debug) {
            $this->renderDebug($exception);
        } else {
            $this->renderProduction($exception);
        }

        // 3. 確保腳本結束
        exit(1);
    }

    private function logException(\Throwable $e): void
    {
        $context = [
            'code' => $e->getCode(),
            'file' => $e->getFile(),
            'line' => $e->getLine(),
            'trace' => $e->getTraceAsString(),
        ];

        if ($e instanceof AppException) {
            $context['error_code'] = $e->getErrorCode();
            $context['http_code'] = $e->getHttpCode();
            $context = array_merge($context, $e->getContext());
            $this->logger->warning($e->getMessage(), $context);
        } else {
            $this->logger->error($e->getMessage(), $context);
        }
    }

    private function renderDebug(\Throwable $e): void
    {
        // 發送 HTTP 狀態碼
        $code = $e instanceof AppException ? $e->getHttpCode() : 500;
        http_response_code($code);

        // 詳細錯誤頁面 (Whoops 風格簡易版)
        header('Content-Type: text/html; charset=UTF-8');
        echo 'Error';
        echo '';
        echo '';
        echo '

' . get_class($e) . '

'; echo '

Message: ' . htmlspecialchars($e->getMessage()) . '

'; echo '

File: ' . $e->getFile() . ':' . $e->getLine() . '

'; echo '

Code: ' . $e->getCode() . '

'; if ($e instanceof AppException) { echo '

Error Code: ' . $e->getErrorCode() . '

'; echo '

Context:

' . htmlspecialchars(json_encode($e->getContext(), JSON_PRETTY_PRINT)) . '

'; } echo '
Stack Trace:
' . htmlspecialchars($e->getTraceAsString()) . '
'; echo ''; } private function renderProduction(\Throwable $e): void { $code = $e instanceof AppException ? $e->getHttpCode() : 500; http_response_code($code); // 返回 JSON (API) 或友好錯誤頁 (Web) if (str_contains($_SERVER['HTTP_ACCEPT'] ?? '', 'application/json') || str_starts_with($_SERVER['REQUEST_URI'] ?? '', '/api/')) { header('Content-Type: application/json; charset=UTF-8'); echo json_encode([ 'error' => $e instanceof AppException ? $e->getErrorCode() : 'INTERNAL_ERROR', 'message' => $this->debug ? $e->getMessage() : '服務器內部錯誤', ], JSON_UNESCAPED_UNICODE); } else { // 靜態錯誤頁 include __DIR__ . "/../templates/errors/{$code}.php"; } } }

3. 業務代碼中拋出異常

<?php
// Service 層
class UserService
{
    public function getUser(int $id): User
    {
        $user = User::find($id);
        if (!$user) {
            throw new NotFoundException("User {$id} not found", 0, null, ['user_id' => $id]);
        }
        return $user;
    }

    public function transfer(int $from, int $to, float $amount): void
    {
        if ($amount <= 0) {
            throw new ValidationException('Amount must be positive', 0, null, ['amount' => $amount]);
        }
        // ... 事務邏輯
        if ($dbError) {
            throw new DatabaseException('Transfer failed', 0, $dbError, ['from'=>$from, 'to'=>$to, 'amount'=>$amount]);
        }
    }
}

// Controller 層
class UserController
{
    public function show(int $id)
    {
        try {
            $user = $this->userService->getUser($id);
            return response()->json($user);
        } catch (NotFoundException $e) {
            return response()->json($e->toArray(), $e->getHttpCode());
        } catch (AppException $e) {
            return response()->json($e->toArray(), $e->getHttpCode());
        } catch (\Throwable $e) {
            // 未預期異常,交給全局處理器
            throw $e;
        }
    }
}

四、日志最佳實踐 (Monolog)

// composer require monolog/monolog
use Monolog\Logger;
use Monolog\Handler\RotatingFileHandler;
use Monolog\Handler\StreamHandler;
use Monolog\Formatter\LineFormatter;
use Monolog\Processor\IntrospectionProcessor;

$logger = new Logger('app');

// 生產:按天輪轉,保留 30 天
$handler = new RotatingFileHandler(__DIR__ . '/logs/app.log', 30, Logger::DEBUG);
$handler->setFormatter(new LineFormatter(
    "[%datetime%] %channel%.%level_name%: %message% %context% %extra%\n",
    "Y-m-d H:i:s.u"
));
$handler->pushProcessor(new IntrospectionProcessor(Logger::DEBUG, ['App\\']));
$logger->pushHandler($handler);

// 錯誤單獨文件
$errorHandler = new RotatingFileHandler(__DIR__ . '/logs/error.log', 30, Logger::ERROR);
$errorHandler->setFormatter(new LineFormatter(
    "[%datetime%] %channel%.%level_name%: %message% %context% %extra%\n"
));
$logger->pushHandler($errorHandler);

五、常見陷阱與避坑

  1. 不要吞掉異常: catch (Exception $e) { } 空 catch 是大忌,至少記錄日志或重新拋出。
  2. 捕獲順序: 子類異常在前,父類在後。catch (ValidationException) {} 在 catch (AppException) {} 之前。
  3. finally 必執行: 資源清理 (關閉連接、釋放鎖) 放在 finally 塊,即使有 return/throw 也會執行。
  4. 異常不控制業務流程: 正常分支用返回值/狀態機,異常只處理「異常情況」。
  5. 生產環境關閉 display_errors: ini_set('display_errors', 0); 防止敏感信息洩露。
  6. Error vs Exception: PHP 7+ Error 實現 Throwable,catch (Throwable $e) 可同時捕獲兩者。

總結

構建健壯 PHP 應用的異常處理體系三步走:

  1. 定義分層異常類 (業務/系統、HTTP 碼、錯誤碼、上下文)。
  2. 註冊全局處理器 (錯誤轉異常 + 致命錯誤捕獲 + 統一日志 + 環境感知輸出)。
  3. 業務代碼拋出具體異常,控制器捕獲已知異常轉為響應,未知拋給全局。

配合 Monolog 分級日志、錯誤追蹤系統,實現「開發期可見細節、生產期用戶友好、運維期可追蹤定位」的完美平衡。

copyright © 萬盛學電腦網 all rights reserved