README

Laravception 在 Laravel 中标准化错误响应，确保所有异常都有唯一的代码、清晰的提示信息和元数据。它支持错误消息翻译，促进特定的异常类，并根据环境调整细节。

安装

Laravception 需要 PHP 8.2。要获取最新版本，只需使用 Composer 需求项目。

composer require vaened/laravception

现在。发布配置文件。

php artisan vendor:publish --tag='laravception'

用法

Laravception 捕获应用程序抛出的异常并标准化它们的结构。统一的结构如下

{
  "code": "Exception error code",
  "message": "Exception message",
  "params": {
    "Exception parameters"
  },
  "meta": [
    "Metadata that the exception might export"
  ],
  "exception": "Exception name",
  "file": "File where exception was thrown",
  "line": "Line that threw the exception",
  "trace": [
    "Full stack trace of the exception"
  ]
}

此结构将根据环境是否设置为开发或生产来隐藏某些详细信息。

翻译

要启用异常翻译，实现接口 TranslatableException。这足以开始翻译子异常。

final class InvalidCreditCardException extends RuntimeException implements TranslatableException
{  
  // this is enough
}

建议为每个错误创建一个自定义异常类，以便进行更具体的翻译。例如，对于异常 “InvalidCreditCardException”，您可以在 exceptions 文件中添加一个翻译条目：exceptions

[
  "invalid_credit_card_exception" => "La tarjeta de credito ingresada no es válida".
]

此功能默认启用。任何未实现 Codeable 的异常都将以相同的方式处理，将类名转换为 snake_case 并将这种转换用作错误代码和翻译的键。

为了更好地管理错误代码，您可以实现 Codeable。在异常 "InvalidCreditCardException" 中，您可以返回自定义错误代码，例如 payments.invalid_credit_card，并在您的翻译文件中

[
  "payments" => [
    "invalid_credit_card" => "La tarjeta de crédito ingresada no es válida".
  ]
]

您还可以通过实现 Parametrizable 接口来添加参数。返回一个包含要使用属性的数组，您的翻译文件将如下所示

[
  "payments" => [
    "invalid_credit_card" => "La tarjeta de crédito <:card_number> no es válida".
  ]
]

我们最终可以拥有以下实现

final class InvalidCreditCardException extends RuntimeException 
	implements TranslatableException, Codeable, Parametrizable  
{  
    public function __construct(private readonly string $cardNumber)  
    {  
        parent::__construct("The credit card number <$cardNumber> is invalid");  
    }  
  
    public function errorCode(): string  
    {  
        return 'payments.invalid_credit_card';  
    }  
  
    public function parameters(): array  
    {  
        return [  
            'card_number' => $this->cardNumber,  
        ];  
    }  
}

配置

要了解各种配置选项，请参阅配置文件 laravception.php 中的注释。

原则

这个库背后的核心思想是在 Laravel 项目中标准化错误消息，确保所有异常都遵循共同的结构。

特定异常

为了改进 API 组织和文档，建议创建具有特定用途的自定义异常，例如 "PaymentFailedException" 或 "ClientNotFoundException"。这允许更精确、更有效地处理异常。

消息翻译

有了特定的异常，可以使用唯一代码自动呈现错误消息。这使得翻译和装饰错误消息更容易，确保它们对开发人员和最终用户来说都清晰且有用地。

许可证

此库根据 MIT 许可证授权。有关更多信息，请参阅 license 文件。