Laravel Config Validator —— 项目中的配置验证工具

随着你的 Laravel 项目的变化和发展，你可能会添加新的配置字段并加入新的团队成员与你一起协作。特别是对于初级开发人员，第一次在本地开发机器上为每个项目设置配置和环境变量有时候（但并非总是）会非常混乱。

有时你会发现自己摸不着头脑想「我在这里放了正确的 API 密钥吗？」，或者「这是这个环境变量的正确 URL 吗？」，以及「这个配置有什么不同的值字段可以是？」。

当然，这些类型的问题可以通过编写良好和最新的文档来避免。但是，如果这些问题可以在运行你的应用程序之前以编程方式回答和强制执行，而不是通过眼睛或等到你的代码在运行失败时再发现，这不是更好吗？

什么是 Laravel 配置验证器?

Laravel Config Validator（Laravel 配置验证器） 是我构建的一个包，旨在通过为开发人员提供定义可用于验证配置字段的规则的能力来尝试解决这些问题。它允许你使用 Artisan 命令验证你的配置字段，以便你和其他开发人员可以确保他们设置了正确的配置。

使用这个包的好处是它鼓励将代码作为文档，因为你可以在每次配置更改时更新配置验证规则，而不是使用可能被你藏起来且从未有人主动去查阅的项目更新文档（例如那个每次看都很无聊的 Markdown 文件）。

它还允许你相对轻松地编写复杂的规则。例如，假设你有一个存储 Mailgun API 密钥的配置字段。你可以编写一个简单的规则来确保密钥存在并且是一个字符串。然而，你还可以更进一步，编写一个向 API 发出 HTTP 请求的规则，以确认密钥确实有效并且可用于在你的应用程序中发出请求。

为了更好地了解这在你的代码库中的效果，这里有一个基本示例，说明我们如何验证一个可验证的 services.mailchimp.api_key 字段：

use AshAllenDesign\ConfigValidator\Services\Rule;
use App\Rules\ValidMailchimpKey;

return [
    Rule::make('mailchimp.api_key')
        ->rules(['required', 'string', new ValidMailchimpKey()]),
];

在定义了上述规则之后，我们可以运行包提供的命令（php artisan config:validate）。如果 services.mailchimp.api_key 字段有效，则验证将通过。否则，该命令将返回错误列表，以便我们发现错误的配置值，类似于下面的示例截图：

这个包最好的部分（在我看来）是你不需要学习任何新的语法！在底层，这个包使用了 Laravel 提供的 Validator。因此，你可以使用通常在请求验证中使用的相同规则。

现在，让我们看看如何安装该软件包并开始在你的项目中使用它。

安装软件包

要开始使用该包，你需要确保你的 Laravel 项目至少使用 Laravel 8.0 和 PHP 8.0。

你可以使用以下命令通过 Composer 安装软件包：

composer require ashallendesign/laravel-config-validator

该软件包附带了一些方便的规则集，你可以使用它们来验证一些默认的 Laravel 配置字段。这些都是可选项，但它们可以为验证应用程序的配置提供一个很好的起点。如果要使用默认规则集，可以使用以下命令发布它们：

php artisan vendor:publish --tag=config-validator-defaults

上述命令将复制验证文件并将它们放在项目根目录下的 config-validation 文件夹中。这些规则只是为了让你入门，因此你的项目可能不需要一些规则。因此，一旦你发布了它们，请随意删除它们或尽可能多地编辑它们。

定义配置验证规则集

现在我们已经安装了扩展包，我们可以开始创建自己的规则集了。

使用扩展包提供的命令创建新规则集非常简单。例如，如果我们想创建一个规则集来验证 config/app.php 文件中的配置，我们可以运行以下命令：

php artisan make:config-validation app

运行上述命令将在 config-validation/app.php 中创建一个文件，供你添加配置验证。

请务必记住，你的配置验证文件的名称需要与你要验证的配置文件匹配。例如，如果你验证 config/mail.php 文件，则需要将验证文件存储为 config-validation/mail.php。

向规则集中添加规则

在 config-validation 目录中创建规则集文件后，我们就可以开始添加验证规则了。

在底层，该包使用 Laravel 附带的内置 Validator 类，并利用所有现有的 Laravel 中可用的验证规则，所以使用它应该看起来很熟悉。

让我们举一个基本示例，为 app/mail.php 文件中的 driver 字段创建一个新的验证规则。我们将定义一个规则，说明该字段必须是以下之一：smtp、sendmail、mailgun 、ses 或 postmark。为此，我们可以编写以下规则：

use AshAllenDesign\ConfigValidator\Services\Rule;

return [

    // ...

    Rule::make('driver')->rules(['in:smtp,sendmail,mailgun,ses,postmark']),

    // ...

];

正如你所看到的,制定一个规则就是如此简单

自定义验证错误信息

有时您可能想要覆盖特定验证规则的默认错误消息。 在定义规则集时，使用 Rule 对象上的 messages 方法很容易做到这一点。

举个例子,如果我们想要覆盖我们创建的“mail.driver”配置验证规则的错误消息，我们可以这样做：

use AshAllenDesign\ConfigValidator\Services\Rule;

return [

    // ...

    Rule::make('driver')
        ->rules(['in:smtp,sendmail,mailgun,ses,postmark'])
        ->messages(['in' => 'Our custom error message here']),

    // ...

];

仅运行在指定的app环境

您可能希望创建只应在特定环境中运行的规则。 例如，您可能希望为本地开发环境创建一组宽松的验证规则，并为生产环境制定一组更严格的规则。

要指定可以在其中运行规则的环境，你可以使用 Rule 对象上可用的 environments 方法。如果未定义环境，则默认情况下该规则将在所有环境中运行。

例如，让我们想象一下，当我们在本地处理我们的项目时，我们并不真正关心我们使用的是哪个邮件驱动程序。但是，在生产中，我们要确保我们只使用 mailgun。因此，我们可以创建一个在本地运行的宽松规则和一个在生产环境中运行的更严格的规则，如下所示：

use AshAllenDesign\ConfigValidator\Services\Rule;

return [
    Rule::make('driver')
        ->rules(['in:smtp,sendmail,mailgun,ses,postmark'])
        ->environments([Rule::ENV_LOCAL]),

    Rule::make('driver')
        ->rules(['in:mailgun'])
        ->environments([Rule::ENV_PRODUCTION]),
];

运行配置验证

现在我们已经学会了如何定义自己的配置验证规则集，让我们看看如何实际运行验证。

使用命令

运行配置验证的最常见（也是最简单）的方法是使用软件包附带的 Artisan 命令。

你可以通过运行以下命令来使用它：

php artisan config:validate

有时候，你可能并不总是希望验证应用程序中的所有配置值。因此，该命令允许你指定要验证的确切配置文件。为此，你可以使用 --files 选项。

例如，如果我们只想验证 config/auth.php 文件，我们可以运行以下命令：

php artisan config:validate --files=auth

同样，如果想显式的在单行命令中一次性验证多个文件，我们可以将多个名称传递给以逗号分隔的 --files 选项。例如，要验证 config/auth.php 和 config/services.php 文件，我们可以运行以下命令：

php artisan config:validate --files=auth,services

手动运行验证

有时你可能更愿意在代码中手动运行验证命令，而不是使用提供的命令。为此，你只需在 AshAllenDesign\ConfigValidator\Services\ConfigValidator 类上调用 run 方法，如下所示：

use AshAllenDesign\ConfigValidator\Services\ConfigValidator;

(new ConfigValidator())->run();

默认情况下，如果所有验证检查均通过，run 方法将返回 true。如果任何一项检查失败，则会抛出异常 AshAllenDesign\ConfigValidator\Exceptions\InvalidConfigValueException。

类似于我们如何定义应该使用命令运行的特定验证规则集，我们也可以对 ConfigValidator 对象执行相同的操作。为此，我们可以将一组配置文件名传递给 run 方法。

例如，如果我们只想对 config/auth.php 文件运行验证，我们可以使用以下代码：

use AshAllenDesign\ConfigValidator\Services\ConfigValidator;

(new ConfigValidator())->run(['auth']);

在 Service Provider（服务提供者）中运行

举一个很好的例子，你可能是希望在 Service Provider 中手动运行配置验证。这是在开发时在本地环境中运行配置验证规则的理想场所，以确保你拥有所有有效配置。如果你经常在包含具有不同所需配置字段的不同字段的 Git 分支之间跳转，这将特别有用。

以下是我们如何在 local 环境中对每个请求自动运行配置验证，并在 production 或 testing 中运行时忽略它：

namespace App\Providers;

use AshAllenDesign\ConfigValidator\Services\ConfigValidator;
use Illuminate\Support\Facades\App;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        if (App::environment() === 'local') {
            (new ConfigValidator())->run();
        }
    }
}

抛出和防止异常

正如我们上面提到的，默认情况下，如果验证失败，ConfigValidator 类会抛出AshAllenDesign\ConfigValidator\Exceptions\InvalidConfigValueException 异常。异常将包含第一个未通过验证的配置值的错误消息。

但是，有时你可能不想在第一次失败时抛出异常，而是希望一次运行所有规则。为此，你可以通过使用 throwExceptionOnFailure 方法来防止抛出异常，而不是依赖 run 方法的布尔返回值。如果我们禁止抛出异常，当出现任何验证检查失败时，run 方法将返回 false。

通过防止抛出任何异常，我们可以使用 errors 方法获取失败的验证错误，该方法会将它们作为数组返回。

下面的示例显示了如何防止引发任何异常，以便你可以捕获错误信息：

$configValidator = new ConfigValidator();

$errors = $configValidator->throwExceptionOnFailure(false)
    ->run()
    ->errors();

这实际上也是包的命令运行验证器的方式，以便它可以一次在输出中显示所有失败。

结语

希望这篇文章能让你大致了解如何在 Laravel 应用程序中使用 Laravel Config Validator（Laravel 配置验证器）扩展包来验证应用程序的配置值。如果你对扩展包的代码有兴趣，可以在 GitHub 仓库 中查看相关代码。

如果你喜欢阅读这篇文章，我很开心能帮助到你。同样，如果你有任何反馈可以改进未来的反馈，我也很乐意听到。

我将会继续打造很棒的作品！ 加油！🚀

本文中的所有译文仅用于学习和交流目的，转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议，如果我们的工作有侵犯到您的权益，请及时联系我们。

---

原文地址：https://laravel-news.com/config-validato...

译文地址：https://learnku.com/laravel/t/68322