README

本包扩展了我们 spatie/enum 包在 Laravel 中的支持。

安装

您可以通过 composer 安装此包

composer require spatie/laravel-enum

支持我们

我们投入了大量资源来创建一流的开放源代码包。您可以通过购买我们的付费产品之一来支持我们。

我们非常感激您从家乡寄来明信片，说明您正在使用我们哪个包。您可以在我们的联系页面上找到我们的地址。我们将所有收到的明信片发布在我们的虚拟明信片墙上。

用法

// a Laravel specific base class
use Spatie\Enum\Laravel\Enum;

/**
 * @method static self DRAFT()
 * @method static self PREVIEW()
 * @method static self PUBLISHED()
 * @method static self ARCHIVED()
 */
final class StatusEnum extends Enum {}

模型属性转换

如果您正在 Laravel 项目中工作，您可能会希望在模型中使用枚举。此包提供了两个自定义转换，并且 \Spatie\Enum\Laravel\Enum 也实现了 \Illuminate\Contracts\Database\Eloquent\Castable 接口。

use Illuminate\Database\Eloquent\Model;

class TestModel extends Model
{
    protected $casts = [
        'status' => StatusEnum::class,
        'nullable_enum' => StatusEnum::class.':nullable',
        'array_of_enums' => StatusEnum::class.':collection',
        'nullable_array_of_enums' => StatusEnum::class.':collection,nullable',
    ];
}

通过使用这些转换，转换的属性将始终是给定枚举的实例。

$model = new TestModel();
$model->status = StatusEnum::DRAFT();
$model->status->equals(StatusEnum::DRAFT());

验证规则

此包提供了一个验证规则，用于验证您的请求数据是否与给定的可枚举对象匹配。

use Spatie\Enum\Laravel\Rules\EnumRule;

$rules = [
    'status' => new EnumRule(StatusEnum::class),
];

此规则验证 status 的值是否是 StatusEnum 的任何可能表示。

但您也可以使用简单的字符串验证规则定义

$rules = [
    'status' => [
        'enum:'.StatusEnum::class,
    ],
];

如果您想自定义失败的验证消息，您可以发布翻译文件。

php artisan vendor:publish --provider="Spatie\Enum\Laravel\EnumServiceProvider" --tag="translation"

我们向翻译键传递了几个替换项，您可以使用。

attribute - 被验证的属性名称
value - 实际的验证值
enum - 想要的可枚举对象的完整类名
other - 所有可能值的逗号分隔列表 - 它们通过翻译文件中的 enums 数组进行翻译

请求数据转换

一个常见的场景是您将枚举值作为请求数据的一部分接收。为了让您将其作为真正的枚举对象处理，您可以通过类似模型属性转换的方式将请求数据转换为枚举。

请求宏

有一个请求宏可用，它是将请求数据转换为可枚举的其他可能方式的基础。

$request->transformEnums($enumCastRules);

这是所有可能的请求枚举转换的定义示例。在 Spatie\Enum\Laravel\Http\EnumRequest 上有三种预定义的键作为常量，用于仅将枚举转换为特定的请求数据集。所有其他键都将被视为独立的枚举转换，并应用于组合的请求数据集。

use Spatie\Enum\Laravel\Http\EnumRequest;

$enums = [
    // cast the status key independent of it's data set
    'status' => StatusEnum::class,
    // cast the status only in the request query params
    EnumRequest::REQUEST_QUERY => [
        'status' => StatusEnum::class,
    ],
    // cast the status only in the request post data
    EnumRequest::REQUEST_REQUEST => [
        'status' => StatusEnum::class,
    ],
    // cast the status only in the request route params
    EnumRequest::REQUEST_ROUTE => [
        'status' => StatusEnum::class,
    ],
];

您可以在代码的任何部分中调用此宏，只要您可以访问请求实例。通常，您将在控制器操作中这样做，如果您不想使用其他两种方法之一。

表单请求

表单请求是将数据转换为枚举的最简单方法。

use Illuminate\Foundation\Http\FormRequest;
use Spatie\Enum\Laravel\Http\Requests\TransformsEnums;
use Spatie\Enum\Laravel\Rules\EnumRule;

class StatusFormRequest extends FormRequest
{
    use TransformsEnums;

    public function rules(): array
    {
        return [
            'status' => new EnumRule(StatusEnum::class),
            'properties.level' => new EnumRule(LevelEnum::class),
        ];
    }

    public function enums(): array
    {
        return [
            'status' => StatusEnum::class,
            'properties.level' => LevelEnum::class,
        ];
    }
}

请求数据转换是在验证后通过 FormRequest::passedValidation() 方法完成的。如果您定义了自己的 passedValidation() 方法，您必须自己调用请求宏 transformEnums()。

protected function passedValidation()
{
    $this->transformEnums($this->enums());

    // ...
}

路由绑定

除了使用表单请求之外，您还可以使用路由绑定。类似于 Laravel 的路由模型绑定，它将自动将枚举实例注入到您的路由操作中。

隐式绑定

要使用隐式路由绑定，请确保添加 Spatie\Enum\Laravel\Http\Middleware\SubstituteBindings 中间件。例如，在您的 app\Http\Kernel.php 中添加它。

protected $middlewareGroups = [
    'web' => [
        // ...
        \Spatie\Enum\Laravel\Http\Middleware\SubstituteEnumBindings::class,
    ],
];

使用与路由段匹配的类型提示变量名以使用隐式路由绑定。

Route::get('/posts/{status}', function (StatusEnum $status) {
    return $status;
});

显式绑定

要使用显式绑定，有一个 Route::enum() 宏。重要的是您的路由/分组使用 \Illuminate\Routing\Middleware\SubstituteBindings 中间件。默认情况下，该中间件为 web 路由组启用。

Route::enum('status', StatusEnum::class);
Route::get('/posts/{status}', function (Request $request) {
    return $request->route('status');
});

枚举生成命令

我们提供了一个 artisan make 命令，允许您快速创建新的枚举。

php artisan make:spatie-enum StatusEnum

您可以使用 --method 选项预先定义一些枚举值 - 您可以多次使用它们。

Faker 提供者

您很可能会有一个具有枚举属性的模式，并且希望在您的模型工厂中生成随机枚举值。由于使用默认的 faker 进行此操作需要大量复制粘贴，我们提供了 Spatie\Enum\Laravel\Faker\FakerEnumProvider 提供者以供您使用。静态 register() 方法只是一个小的辅助程序 - 您当然可以以默认方式注册提供者，即 $faker->addProvider(new FakerEnumProvider)。

Faker 方法本身是从基础包 Faker Provider 继承的。

Livewire

您可以使用枚举作为 Livewire 组件的属性，如下所示

class ShowCustomer extends Component
{
    public StatusEnum $statusEnum;

    public function mount($id)
    {
        $customer = Customer::find($id);
        $this->statusEnum = $customer->status;
    }

    public function render()
    {
        return view('livewire.customer');
    }
}

为了使此操作正常工作，您需要在所有将要与 Livewire 一起使用的枚举上实现 \Livewire\Wireable：

use Livewire\Wireable;

/**
 * @method static self pending()
 * @method static self active()
 */
final class StatusEnum implements Wireable
{}

测试

composer test
composer test-coverage

变更日志

有关最近更改的更多信息，请参阅 CHANGELOG。

贡献

有关详细信息，请参阅 CONTRIBUTING。

安全

如果您发现了关于安全性的错误，请通过邮件 [email protected] 而不是使用问题跟踪器。

致谢

许可

MIT 许可证 (MIT)。请参阅许可文件了解更多信息。

spatie / laravel-enum

维护者

详情