PHP验证异常怎么统一处理

本文目录导读：

1. 自定义验证异常类
2. 全局异常处理器
3. 使用 Laravel 框架（推荐）
4. 使用 Symfony 框架
5. 手动验证并抛出自定义异常
6. 中间件方式处理
7. 完整示例：入口文件统一处理

在PHP中统一处理验证异常的最佳实践是通过异常处理机制结合框架特性来实现,以下是几种主流方案：

自定义验证异常类

<?php
// 自定义验证异常
class ValidationException extends \RuntimeException
{
    private array $errors;
    public function __construct(array $errors, string $message = '验证失败')
    {
        $this->errors = $errors;
        parent::__construct($message, 422);
    }
    public function getErrors(): array
    {
        return $this->errors;
    }
    public function toArray(): array
    {
        return [
            'message' => $this->getMessage(),
            'errors' => $this->getErrors()
        ];
    }
}

全局异常处理器

使用 try-catch 统一处理

<?php
class ExceptionHandler
{
    public function handle(\Throwable $e): void
    {
        // 设置响应格式
        http_response_code($this->getStatusCode($e));
        header('Content-Type: application/json');
        // 根据不同异常类型返回不同格式
        if ($e instanceof ValidationException) {
            echo json_encode([
                'success' => false,
                'message' => $e->getMessage(),
                'errors' => $e->getErrors()
            ]);
        } elseif ($e instanceof \InvalidArgumentException) {
            echo json_encode([
                'success' => false,
                'message' => $e->getMessage()
            ]);
        } else {
            // 其他异常
            echo json_encode([
                'success' => false,
                'message' => '服务器内部错误'
            ]);
        }
        // 记录日志
        $this->logError($e);
    }
    private function getStatusCode(\Throwable $e): int
    {
        return match (true) {
            $e instanceof ValidationException => 422,
            $e instanceof \InvalidArgumentException => 400,
            $e instanceof \RuntimeException => 500,
            default => 500
        };
    }
    private function logError(\Throwable $e): void
    {
        error_log(sprintf(
            "[%s] %s in %s:%d\n%s",
            get_class($e),
            $e->getMessage(),
            $e->getFile(),
            $e->getLine(),
            $e->getTraceAsString()
        ));
    }
}

使用 Laravel 框架（推荐）

Laravel 内置了强大的验证异常处理：

<?php
namespace App\Exceptions;
use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;
use Illuminate\Validation\ValidationException;
use Throwable;
class Handler extends ExceptionHandler
{
    public function render($request, Throwable $e)
    {
        // 处理验证异常
        if ($e instanceof ValidationException) {
            return response()->json([
                'success' => false,
                'message' => '验证失败',
                'errors' => $e->errors()
            ], 422);
        }
        return parent::render($request, $e);
    }
    protected function invalidJson($request, ValidationException $e)
    {
        return response()->json([
            'message' => '给定的数据无效。',
            'errors' => $e->errors(),
        ], $e->status);
    }
}

使用 Symfony 框架

<?php
namespace App\EventListener;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpKernel\Event\ExceptionEvent;
use Symfony\Component\Validator\Exception\ValidationFailedException;
class ValidationExceptionListener
{
    public function onKernelException(ExceptionEvent $event): void
    {
        $exception = $event->getThrowable();
        if ($exception instanceof ValidationFailedException) {
            $violations = $exception->getViolations();
            $errors = [];
            foreach ($violations as $violation) {
                $errors[$violation->getPropertyPath()][] = $violation->getMessage();
            }
            $response = new JsonResponse([
                'success' => false,
                'message' => '验证失败',
                'errors' => $errors
            ], 422);
            $event->setResponse($response);
        }
    }
}

手动验证并抛出自定义异常

<?php
class Validator
{
    public function validate(array $data, array $rules): array
    {
        $errors = [];
        foreach ($rules as $field => $ruleSet) {
            $value = $data[$field] ?? null;
            $rules = explode('|', $ruleSet);
            foreach ($rules as $rule) {
                if (!$this->validateRule($value, $rule)) {
                    $errors[$field][] = $this->getErrorMessage($field, $rule);
                }
            }
        }
        if (!empty($errors)) {
            throw new ValidationException($errors);
        }
        return $data;
    }
    private function validateRule($value, string $rule): bool
    {
        // 实现具体的验证逻辑
        return match ($rule) {
            'required' => !empty($value),
            'email' => filter_var($value, FILTER_VALIDATE_EMAIL) !== false,
            default => true
        };
    }
    private function getErrorMessage(string $field, string $rule): string
    {
        return match ($rule) {
            'required' => "{$field} 字段是必填的",
            'email' => "{$field} 必须是有效的邮箱地址",
            default => "{$field} 验证失败"
        };
    }
}
// 使用示例
$validator = new Validator();
try {
    $validated = $validator->validate($_POST, [
        'email' => 'required|email',
        'name' => 'required'
    ]);
} catch (ValidationException $e) {
    // 由全局异常处理器处理
    throw $e;
}

中间件方式处理

<?php
class ValidationMiddleware
{
    public function handle(callable $next): void
    {
        try {
            $next();
        } catch (ValidationException $e) {
            // 统一返回验证错误
            http_response_code(422);
            header('Content-Type: application/json');
            echo json_encode([
                'success' => false,
                'message' => '输入验证失败',
                'errors' => $e->getErrors()
            ]);
            // 或者重定向回表单页面
            // header('Location: /form/error?' . http_build_query(['errors' => $e->getErrors()]));
        }
    }
}

完整示例：入口文件统一处理

<?php
// index.php - 应用入口
require_once 'vendor/autoload.php';
// 注册全局异常处理器
set_exception_handler(function (\Throwable $e) {
    $handler = new ExceptionHandler();
    $handler->handle($e);
    exit;
});
// 业务代码
try {
    $validator = new Validator();
    $validated = $validator->validate($_POST, [
        'username' => 'required|min:3',
        'email' => 'required|email',
        'password' => 'required|min:6'
    ]);
    // 处理业务逻辑...
} catch (\Throwable $e) {
    // 会由全局异常处理器处理
    throw $e;
}

1. 统一异常类：创建自定义的 ValidationException 类
2. 集中处理：在入口文件或框架的异常处理器中统一处理
3. 适当状态码：使用 422 状态码表示验证失败
4. 友好的错误信息：返回结构化的错误信息
5. 记录日志：记录详细的错误信息便于调试
6. 区分环境：开发环境返回详细错误，生产环境返回通用信息

选择哪种方案取决于你的项目架构，如果是新项目，建议使用成熟的框架（如 Laravel、Symfony）,它们已经提供了完善的验证异常处理机制。