README

枚举对于任何与 PHP 打交道的开发者来说都是一项无价的工具。它们提供了一种轻松且高效的方式来定义一组可以在整个项目中使用的常量。枚举还有助于使代码更易于维护和扩展。例如，它们可以帮助定义一组在整个项目中必须保持一致性的值，如权限列表或状态列表。这有助于确保在代码的各个相关部分中使用相同的值，并且任何更改都只在一个地方进行。此外，枚举有助于减少所需的手动测试量，因为值已经定义。此外，枚举还为开发人员提供了一种快速检查有效值的方法，使更容易在代码中找出错误并确保应用程序按预期运行。最后，枚举是强类型的，这意味着它们可以帮助确保在应用程序的每个部分都使用正确的数据类型，这有助于提高整体代码质量。

受包 BenSampo/laravel-enum 的启发，这个包使用了 PHP 中的新原生枚举类。原生函数被扩展以轻松且无缝地与 Laravel 系统中的它们一起工作。

欢迎所有人贡献。

享受这个包！

安装

安装 PHP Composer 包

Laravel Native PHP 8.1 Enums 是一个强大的包，可以帮助您构建和维护强大的、可扩展的 Laravel 系统。

要求

Laravel 9 或更高版本
PHP 8.1 或更高版本

Composer 安装

在开始之前，请确保您已安装所需的要求，并且系统上已安装 Composer。您可以在此处找到有关如何操作的说明。

安装 Composer 后，您可以通过在项目目录中运行以下命令来安装 "Laravel Native PHP 8.1 Enums"：

composer require mindtwo/native-enum

安装完成后，您现在可以开始在项目中使用原生枚举。祝您玩得开心！

创建枚举

Artisan 命令

您可以使用以下 Artisan 命令在项目中生成新的原生枚举类：

// Default:
php artisan make:enum UserRole

// Localized:
php artisan make:enum UserRole --localized

手动创建枚举

您还可以手动创建新的原生枚举。结构应如下所示：

namespace App\Enums;

enum UserRole: int
{
    use BaseEnum;
    
    case ADMIN = 10;
    case CUSTOMER = 50;
}

用法

基本用法

UserRole::getRandomValue();
UserRole::getRandomName();
UserRole::getRandomInstance();
UserRole::asSelectArray();
UserRole::asArray();
UserRole::getValues();
UserRole::getNames();
UserRole::hasValue(50);
UserRole::hasName('ADMIN');

获取特定枚举值

UserRole::getValues('ADMIN');
UserRole::getValues(UserRole::ADMIN);
UserRole::getValues([UserRole::ADMIN]);
UserRole::getValues('CUSTOMER');
UserRole::getValues(UserRole::CUSTOMER);
UserRole::getValues([UserRole::CUSTOMER]);

获取特定枚举名称

UserRole::getNames(10);
UserRole::getNames(50);
UserRole::getNames([10,50]);

使用静态调用获取原始值

UserRole::ADMIN(); // 10
UserRole::CUSTOMER(); // 50

验证

枚举值

您可以使用 EnumValue 规则验证传递给控制器的枚举值是否为给定枚举的有效值。

use mindtwo\NativeEnum\Rules\EnumValue;

public function store(Request $request)
{
    $this->validate($request, [
        'user_role' => ['required', new EnumValue(UserRole::class)],
    ]);
}

默认情况下，类型检查设置为严格，但您可以通过将 false 传递给 EnumValue 类的可选第二个参数来绕过此设置。

new EnumValue(UserRole::class, false) // Turn off strict type checking.

枚举名称

您还可以使用 EnumName 规则进行名称验证。如果您将枚举名称用作 URL 参数进行排序或筛选，这很有用。

use mindtwo\NativeEnum\Rules\EnumKey;

public function store(Request $request)
{
    $this->validate($request, [
        'user_role' => ['required', new EnumName(UserRole::class)],
    ]);
}

枚举实例

此外，您还可以验证参数是否是给定枚举的实例。

use mindtwo\NativeEnum\Rules\Enum;

public function store(Request $request)
{
    $this->validate($request, [
        'user_role' => ['required', new Enum(UserRole::class)],
    ]);
}

本地化枚举

枚举必须实现 LocalizedEnum 接口

namespace App\Enums;

enum UserRole: int implements LocalizedEnum
{
    use BaseEnum;
    
    case ADMIN = 10;
    case CUSTOMER = 50;
}

翻译文件可以放置在此处 lang/en/enums.php，如下所示：

use \App\Enums;

return [

    Enums\UserRole::class => [
        Enums\UserRole::ADMIN->name => 'Administrator',
        Enums\UserRole::CUSTOMER->name => 'Customer',
    ],

];

获取所选枚举值的翻译名称

Enums\UserRole::ADMIN->name(); // Returns "Administrator"

Eloquent 模型中的类型转换

laravel的Eloquent ORM提供了一种强大且易于表达的方式来处理数据库中的数据。当处理自定义数据类型，如枚举时，通常需要定义这些值在与数据库交互时的转换方式。这就是转换机制发挥作用的地方。

在模型中使用EnumCast

如果您想在Eloquent模型中使用枚举，可以利用EnumCast功能确保枚举值在从数据库读取或写入时正确转换。这对于处理具有特定允许值的属性，如用户角色、状态或类型特别有用。

以下是如何在模型中应用EnumCast

namespace App\Models;

use App\Enums\UserRole;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    protected $casts = [
        'role' => UserRole::class,
    ];
}

在上面的例子中，User模型的role属性被转换成UserRole枚举。这意味着每次访问role属性时，Eloquent都会自动将原始数据库值转换为UserRole的实例。同样，当您将UserRole枚举实例分配给role属性时，Eloquent会在将其保存到数据库时处理转换为其底层值。

处理可空值

在某些情况下，一个属性可能是可选的，并在数据库中可能具有null值。如果您需要为枚举转换支持null值，可以在转换定义中添加:nullable。

使用:nullable修饰符定义转换

protected $casts = [
    'role' => UserRole::class . ':nullable',
];

确保枚举类实现了Illuminate\Contracts\Database\Eloquent\Castable接口。

namespace App\Enums;

use Illuminate\Contracts\Database\Eloquent\Castable;

enum UserRole: int implements Castable
{
    use BaseEnum;
    
    case ADMIN = 10;
    case CUSTOMER = 50;
}

重要：要支持Eloquent模型中的可空枚举值，需要实现Illuminate\Contracts\Database\Eloquent\Castable接口。请确保您的枚举类实现了此接口，以避免在使用:nullable修饰符时出错。

在此配置下，role属性可以是null，Eloquent将正确处理它而不会引发错误。这在枚举值可能未设置或稍后可以删除的情况下非常有用。

枚举集合的转换

有时，您可能有一个存储枚举值数组或集合的模型属性。例如，一个用户可能有多个角色，这些角色以数组的形式存储在数据库中。您可以使用:collection修饰符将这些数组转换为枚举实例的集合。

使用:collection修饰符定义转换

protected $casts = [
    'roles' => UserRole::class . ':collection',
];

确保枚举类实现了Illuminate\Contracts\Database\Eloquent\Castable接口。

namespace App\Enums;

use Illuminate\Contracts\Database\Eloquent\Castable;

enum UserRole: int implements Castable
{
    use BaseEnum;
    
    case ADMIN = 10;
    case CUSTOMER = 50;
}

重要：要支持Eloquent模型中枚举值的集合转换，需要实现Illuminate\Contracts\Database\Eloquent\Castable接口。请确保您的枚举类实现了此接口，以避免在使用:collection修饰符时出错。

在此配置下，roles属性将被转换为UserRole枚举实例的集合。当您检索此属性时，Eloquent将返回一个集合，其中每个项目都是UserRole的实例。同样，当您将UserRole实例的集合或数组分配给roles属性时，Eloquent将适当地转换并存储数据库中的底层值。

变更日志

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

测试

$ composer test

贡献

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

安全

如果您发现任何安全相关的问题，请通过info@mindtwo.de发送电子邮件，而不是使用问题跟踪器。

鸣谢

许可

MIT许可（MIT）。有关更多信息，请参阅许可文件。

mindtwo / native-enum

维护者

详细信息