{"id":22678281,"url":"https://github.com/hyperf-ext/enum","last_synced_at":"2025-04-12T14:40:57.726Z","repository":{"id":56987677,"uuid":"295757311","full_name":"hyperf-ext/enum","owner":"hyperf-ext","description":"Simple, extensible and powerful enumeration implementation for Hyperf.","archived":false,"fork":false,"pushed_at":"2021-07-30T18:01:11.000Z","size":49,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-26T09:11:58.832Z","etag":null,"topics":["enum","hyperf","php"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyperf-ext.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-09-15T14:39:58.000Z","updated_at":"2024-12-16T06:02:01.000Z","dependencies_parsed_at":"2022-08-21T12:50:26.161Z","dependency_job_id":null,"html_url":"https://github.com/hyperf-ext/enum","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperf-ext%2Fenum","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperf-ext%2Fenum/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperf-ext%2Fenum/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperf-ext%2Fenum/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyperf-ext","download_url":"https://codeload.github.com/hyperf-ext/enum/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248582510,"owners_count":21128394,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["enum","hyperf","php"],"created_at":"2024-12-09T18:14:39.703Z","updated_at":"2025-04-12T14:40:57.702Z","avatar_url":"https://github.com/hyperf-ext.png","language":"PHP","readme":"# Hyperf 枚举组件\n\n## 关于\n\n简单、可扩展且强大的枚举实现。\n\n* 枚举键值对即类常量\n* 功能完备的方法集\n* 枚举实例化\n* 位标志/位移枚举\n* 类型提示\n* 属性转换\n* 枚举命令生成器\n* 用于将枚举键或值作为输入参数传递的验证规则\n* 本地化支持\n* 可通过宏扩展\n\n\u003e 移植自 [`bensampo/laravel-enum`](https://github.com/BenSampo/laravel-enum) 。\n\n## 索引\n\n* [安装](#安装)\n* [基本使用](#基本使用)\n    * [枚举定义](#枚举定义)\n    * [实例化](#实例化)\n    * [实例属性](#实例属性)\n    * [实例类型转换](#实例类型转换)\n    * [实例相等性比较](#实例相等性比较)\n    * [类型提示](#类型提示)\n* [位标志/位移枚举](#位标志位移枚举)\n* [属性转换](#属性转换)\n* [数据库迁移](#数据库迁移)\n* [验证器](#验证器)\n* [本地化](#本地化)\n* [重写 getDescription 方法](#重写-getdescription-方法)\n* [扩展枚举基类](#扩展枚举基类)\n* [PHPStan 集成](#phpstan-集成)\n* [命令列表](#命令列表)\n* [Enum 类参考](#enum-类参考)\n\n## 安装\n\n```shell script\ncomposer require hyperf-ext/enum\n```\n\n## 基本用法\n\n### 枚举定义\n\n可以使用一些命令来生成新的枚举类：\n\n```shell script\nphp bin/hyperf.php gen:enum UserType\n```\n\n现在只需将所有可能值作为常量添加到枚举类即可。\n\n```php\n\u003c?php\n\ndeclare(strict_types=1);\n\nnamespace App\\Enum;\n\nuse HyperfExt\\Enum\\Enum;\n\nfinal class UserType extends Enum\n{\n    const Administrator = 0;\n    const Moderator = 1;\n    const Subscriber = 2;\n    const SuperAdministrator = 3;\n}\n```\n\n这样就完成了。注意，由于枚举值被定义为常量，你可以像使用其他类常量一样简单地使用它们。\n\n```php\nUserType::Administrator // 值为 `0`\n```\n\n### 实例化\n\n实例化枚举有助于在传递它们时带来类型提示的益处。\n\n此外，由于无效的值不能被实例化，因此可以确保传递的值是始终有效的。\n\n为了方便，枚举可以通过多种方式来实例化：\n\n```php\n// 标准的 PHP 实例化方式，将期望的枚举值作为参数进行传递\n$enumInstance = new UserType(UserType::Administrator);\n\n// 与使用构造函数一样，用值来实例化\n$enumInstance = UserType::fromValue(UserType::Administrator);\n\n// 使用枚举的键名作为参数来实例化\n$enumInstance = UserType::fromKey('Administrator');\n\n// 以键名作为方法名来静态调用，利用 __callStatic 魔术方法\n$enumInstance = UserType::Administrator();\n\n// 尝试使用给定的键名或值实例化一个枚举。如果无法实例化，则返回 `null`\n$enumInstance = UserType::coerce($someValue);\n```\n\n如果要使用 IDE 的自动完成，则可以通过命令生成 PHPDoc 注释。\n\n默认情况下，`app/Enum` 目录中的所有枚举都会被添加相关注释（可以通过将目录路径传递给 `--folder` 选项来更改目录）。\n\n```shell script\nphp bin/hyperf.php enum:annotate\n```\n\n也可以通过指定类名来为某个类添加注释。\n\n```shell script\nphp bin/hyperf.php enum:annotate \"App\\Enum\\UserType\"\n```\n\n### 实例属性\n\n有了枚举实例后，可以将 `key`、`value` 和 `description` 作为属性来访问。\n\n```php\n$userType = UserType::fromValue(UserType::SuperAdministrator);\n\n$userType-\u003ekey; // SuperAdministrator\n$userType-\u003evalue; // 0\n$userType-\u003edescription; // Super Administrator\n```\n\n这个功能在要将枚举实例传递到视图的场景下会很有用。\n\n### 实例类型转换\n\n枚举实例可以在实现 `__toString()` 魔术方法时转换为字符串。这也意味着它们可以在视图中直接输出。\n\n```php\n$userType = UserType::fromValue(UserType::SuperAdministrator);\n\n(string) $userType // '0'\n```\n\n### 实例相等性比较\n\n我们可以通过将任意值传递给实例的 `is` 方法来确定实例是否与这些相等。为了方便起见，还有一个 `isNot` 方法，它与 `is` 方法的逻辑完全相反。\n\n```php\n$admin = UserType::fromValue(UserType::Administrator);\n\n$admin-\u003eis(UserType::Administrator);   // true\n$admin-\u003eis($admin);                    // true\n$admin-\u003eis(UserType::Administrator()); // true\n\n$admin-\u003eis(UserType::Moderator);       // false\n$admin-\u003eis(UserType::Moderator());     // false\n$admin-\u003eis('random-value');            // false\n```\n\n还可以使用 `in` 方法来确定实例的值是否与可能值的数组匹配。\n\n```php\n$admin = UserType::fromValue(UserType::Administrator);\n\n$admin-\u003ein([UserType::Moderator, UserType::Administrator]);     // true\n$admin-\u003ein([UserType::Moderator(), UserType::Administrator()]); // true\n\n$admin-\u003ein([UserType::Moderator, UserType::Subscriber]);        // false\n$admin-\u003ein(['random-value']);                                   // false\n```\n\n### 类型提示\n\n另一个枚举实例的益处是让我们可以使用类型提示，如下所示。\n\n```php\nfunction canPerformAction(UserType $userType)\n{\n    if ($userType-\u003eis(UserType::SuperAdministrator)) {\n        return true;\n    }\n\n    return false;\n}\n\n$userType1 = UserType::fromValue(UserType::SuperAdministrator);\n$userType2 = UserType::fromValue(UserType::Moderator);\n\ncanPerformAction($userType1); // 返回 true\ncanPerformAction($userType2); // 返回 false\n```\n\n## 位标志/位移枚举\n\n标准枚举一次只能表示一个值，但是位标志或位移枚举可以同时表示多个值。当要表达一组选项的多个选择时，这是最佳的选择。一个很好的例子就是用户权限，其中可能的权限数量有限，但是用户可以没有权限或是拥有全部或部分权限。\n\n可以使用以下命令生成位标志枚举：\n\n```shell script\nphp bin/hyperf.php gen:enum UserPermissions --flagged\n```\n\n### 定义值\n\n定义值时，必须使用 `2` 的幂，最简单的方法是使用*左移位* `\u003c\u003c` 运算符，如下所示：\n\n```php\nfinal class UserPermissions extends FlaggedEnum\n{\n    const ReadComments      = 1 \u003c\u003c 0;\n    const WriteComments     = 1 \u003c\u003c 1;\n    const EditComments      = 1 \u003c\u003c 2;\n    const DeleteComments    = 1 \u003c\u003c 3;\n    // 接下来是 `1 \u003c\u003c 4`，并依此类推…\n}\n```\n\n### 定义位标志组合\n\n可以使用按位*或* `|` 表示一组给定值的组合值作为快捷方式来使用。\n\n```php\nfinal class UserPermissions extends FlaggedEnum\n{\n    const ReadComments      = 1 \u003c\u003c 0;\n    const WriteComments     = 1 \u003c\u003c 1;\n    const EditComments      = 1 \u003c\u003c 2;\n    const DeleteComments    = 1 \u003c\u003c 3;\n    \n    // 位标志组合\n    const Member = self::ReadComments | self::WriteComments; // 读取和写入权限\n    const Moderator = self::Member | self::EditComments; // Member 的所有权限，附加编辑权限\n    const Admin = self::Moderator | self::DeleteComments; // Moderator 的所有权限，附加删除权限\n}\n```\n\n### 实例化位标志枚举\n\n有几种方法可以实例化位标志枚举：\n\n```php\n// 标准的 PHP 实例化方式，将所需的枚举值作为值数组或枚举实例数组传递\n$permissions = new UserPermissions([UserPermissions::ReadComments, UserPermissions::EditComments]);\n$permissions = new UserPermissions([UserPermissions::ReadComments(), UserPermissions::EditComments()]);\n\n// 静态 flags 方法，同样将所需的枚举值作为值数组或枚举实例数组传递\n$permissions = UserPermissions::flags([UserPermissions::ReadComments, UserPermissions::EditComments]);\n$permissions = UserPermissions::flags([UserPermissions::ReadComments(), UserPermissions::EditComments()]);\n```\n\n[属性转换](#属性转换)的工作方式与单值枚举相同。\n\n### 空位标志枚举\n\n位标志枚举可以不包含任何值。每个标记的枚举都有一个预定义的常量 `None`，相当于 `0`。\n\n```php\nUserPermissions::flags([])-\u003evalue === UserPermissions::None; // True\n```\n\n### 位标志枚举方法\n\n除了标准的枚举方法，位标志枚举还提供了一组有用的方法。\n\n注意：在任何可以传递静态属性的地方，也可以传递枚举实例。\n\n#### setFlags(array $flags): Enum\n\n将枚举的位标志设置为给定的位标志数组。\n\n```php\n$permissions = UserPermissions::flags([UserPermissions::ReadComments]);\n$permissions-\u003eflags([UserPermissions::EditComments, UserPermissions::DeleteComments]); // 当前位标志为：EditComments, DeleteComments\n```\n\n#### addFlag($flag): Enum\n\n添加给定的位标志到枚举。\n\n```php\n$permissions = UserPermissions::flags([UserPermissions::ReadComments]);\n$permissions-\u003eaddFlag(UserPermissions::EditComments); // 当前位标志为：ReadComments, EditComments\n```\n\n#### addFlags(array $flags): Enum\n\n添加一组给定的位标志到枚举。\n\n```php\n$permissions = UserPermissions::flags([UserPermissions::ReadComments]);\n$permissions-\u003eaddFlags([UserPermissions::EditComments, UserPermissions::WriteComments]); // 当前位标志为：ReadComments, EditComments, WriteComments\n```\n\n#### removeFlag($flag): Enum\n\n从枚举中移除给定的位标志。\n\n```php\n$permissions = UserPermissions::flags([UserPermissions::ReadComments, UserPermissions::WriteComments]);\n$permissions-\u003eremoveFlag(UserPermissions::ReadComments); // 当前位标志为：WriteComments.\n```\n\n#### removeFlags(array $flags): Enum\n\n从枚举中移除一组给定的位标志。\n\n```php\n$permissions = UserPermissions::flags([UserPermissions::ReadComments, UserPermissions::WriteComments, UserPermissions::EditComments]);\n$permissions-\u003eremoveFlags([UserPermissions::ReadComments, UserPermissions::WriteComments]); // 当前位标志为：EditComments\n```\n\n#### hasFlag($flag): bool\n\n确定枚举中是否存在指定的位标志。\n\n```php\n$permissions = UserPermissions::flags([UserPermissions::ReadComments, UserPermissions::WriteComments]);\n$permissions-\u003ehasFlag(UserPermissions::ReadComments); // True\n$permissions-\u003ehasFlag(UserPermissions::EditComments); // False\n```\n\n#### hasFlags(array $flags): bool\n\n确定枚举中是否存在指定的全部位标志。\n\n```php\n$permissions = UserPermissions::flags([UserPermissions::ReadComments, UserPermissions::WriteComments]);\n$permissions-\u003ehasFlags([UserPermissions::ReadComments, UserPermissions::WriteComments]); // True\n$permissions-\u003ehasFlags([UserPermissions::ReadComments, UserPermissions::EditComments]); // False\n```\n\n#### notHasFlag($flag): bool\n\n确定枚举中是否不存在指定的位标志。\n\n```php\n$permissions = UserPermissions::flags([UserPermissions::ReadComments, UserPermissions::WriteComments]);\n$permissions-\u003enotHasFlag(UserPermissions::EditComments); // True\n$permissions-\u003enotHasFlag(UserPermissions::ReadComments); // False\n```\n\n#### notHasFlags(array $flags): bool\n\n确定枚举中是否不存在指定的任何一个位标志。\n\n```php\n$permissions = UserPermissions::flags([UserPermissions::ReadComments, UserPermissions::WriteComments]);\n$permissions-\u003enotHasFlags([UserPermissions::ReadComments, UserPermissions::EditComments]); // True\n$permissions-\u003enotHasFlags([UserPermissions::ReadComments, UserPermissions::WriteComments]); // False\n```\n\n#### getFlags(): Enum[]\n\n将位标志作为实例数组返回。\n\n```php\n$permissions = UserPermissions::flags([UserPermissions::ReadComments, UserPermissions::WriteComments]);\n$permissions-\u003egetFlags(); // [UserPermissions::ReadComments(), UserPermissions::WriteComments()];\n```\n\n#### hasMultipleFlags(): bool\n\n确定枚举是否有多个位标志。\n\n```php\n$permissions = UserPermissions::flags([UserPermissions::ReadComments, UserPermissions::WriteComments]);\n$permissions-\u003ehasMultipleFlags(); // True;\n$permissions-\u003eremoveFlag(UserPermissions::ReadComments)-\u003ehasMultipleFlags(); // False\n```\n\n#### getBitmask(): int\n\n获取枚举的位掩码。\n\n```php\nUserPermissions::Member()-\u003egetBitmask(); // 11;\nUserPermissions::Moderator()-\u003egetBitmask(); // 111;\nUserPermissions::Admin()-\u003egetBitmask(); // 1111;\nUserPermissions::DeleteComments()-\u003egetBitmask(); // 1000;\n```\n\n## 属性转换\n\n我们可以使用 Hyperf 内置的自定义类型转换将模型属性转换为枚举。这将在获取时将属性强制转换为枚举实例，并在设置时转回为枚举值。\n由于 `Enum::class` 实现了 `Castable` 接口，因此只需要指定枚举的类名即可：\n\n```php\nuse HyperfExt\\Enum\\Traits\\CastsEnums;\nuse HyperfTest\\Enum\\Enums\\UserType;\nuse Hyperf\\Database\\Model\\Model;\n\nclass Example extends Model\n{\n    use CastsEnums;\n\n    protected $casts = [\n        'random_flag' =\u003e 'boolean',     // 标准的 hyperf 类型转换示例\n        'user_type' =\u003e UserType::class, // 枚举类型转换示例\n    ];\n}\n```\n\n现在，当访问 `Example` 模型的 `user_type` 属性时，基础值将作为 `UserType` 枚举返回。\n\n```php\n$example = Example::first();\n$example-\u003euser_type // UserType 实例\n```\n\n查阅[枚举实例可用的方法和属性](#实例化)，以充分了解属性转换。\n\n我们还可以通过传递枚举值或另一个枚举实例来设置该值。\n\n```php\n$example = Example::first();\n\n// 设置使用枚举值\n$example-\u003euser_type = UserType::Moderator;\n\n// 设置使用枚举实例\n$example-\u003euser_type = UserType::Moderator();\n```\n\n### 转换基础原生类型\n\n有些数据库会以字符串的形式返回所有内容（例如，整数可能以字符串 `'1'` 的形式返回）。\n\n为了减少用户的麻烦，我们使用强类型来确定预期值。如果期望控制它，则可以在枚举类上重写 `parseDatabase` 静态方法：\n\n```php\nfinal class UserType extends Enum\n{\n    const Administrator = 0;\n    const Moderator = 1;\n    \n    public static function parseDatabase($value)\n    {\n        return (int) $value;\n    }\n}\n```\n\n从 `parseDatabase` 方法中返回 `null` 会使模型上的属性也为 `null`。如果数据库存储了不一致的空白值（例如空字符串）而不是 `NULL`，那么这会很有用。\n\n## 数据库迁移\n\n### 推荐\n\n由于枚举在代码级别强制一致性，因此不必在数据库级别再做这些工作。依据枚举值，数据库字段的推荐类型为 `string` 或 `int`。这就意味着我们可以在代码中添加或删除枚举值，而不必顾及数据库层。\n\n```php\nuse App\\Enum\\UserType;\nuse Hyperf\\Database\\Schema\\Schema;\nuse Hyperf\\Database\\Schema\\Blueprint;\nuse Hyperf\\Database\\Migrations\\Migration;\n\nclass CreateUsersTable extends Migration\n{\n    /**\n     * Run the migrations.\n     *\n     * @return void\n     */\n    public function up(): void\n    {\n        Schema::table('users', function (Blueprint $table): void {\n            $table-\u003ebigIncrements('id');\n            $table-\u003etimestamps();\n            $table-\u003estring('type')\n                -\u003edefault(UserType::Moderator);\n        });\n    }\n}\n```\n\n### 使用 `enum` 字段类型\n\n另外，我们可以在迁移中使用枚举来定义枚举字段。枚举值必须定义为字符串。\n\n```php\nuse App\\Enum\\UserType;\nuse Hyperf\\Database\\Schema\\Schema;\nuse Hyperf\\Database\\Schema\\Blueprint;\nuse Hyperf\\Database\\Migrations\\Migration;\n\nclass CreateUsersTable extends Migration\n{\n    /**\n     * Run the migrations.\n     *\n     * @return void\n     */\n    public function up(): void\n    {\n        Schema::table('users', function (Blueprint $table): void {\n            $table-\u003ebigIncrements('id');\n            $table-\u003etimestamps();\n            $table-\u003eenum('type', UserType::getValues())\n                -\u003edefault(UserType::Member);\n        });\n    }\n}\n```\n\n## 验证器\n\n### 数组验证器\n\n#### 枚举值\n\n我们可以使用 `EnumValue` 规则来验证传递的枚举值是否是给定枚举的有效值。\n\n```php\nuse HyperfExt\\Enum\\Rules\\EnumValue;\n\n/**\n * @Inject\n * @var \\Hyperf\\Validation\\ValidatorFactory\n */\nprotected $validatorFactory;\n\npublic function store(Request $request)\n{\n    $validator = $this-\u003evalidatorFactory-\u003emake($request-\u003epost(), [\n        'user_type' =\u003e ['required', new EnumValue(UserType::class)],\n    ]);\n}\n```\n\n默认情况下，类型检查被设置为严格模式，但是可以通过向 `EnumValue` 类的可选第二个参数传递 `false` 来绕过此检查。\n\n```php\nnew EnumValue(UserType::class, false) // 关闭严格模式类型检查\n```\n\n#### 枚举键\n\n我们也可以使用 `EnumKey` 规则对枚举键进行验证。例如，如果将枚举键用作 URL 参数进行排序或过滤，这会很有用。\n\n```php\nuse HyperfExt\\Enum\\Rules\\EnumKey;\n\n/**\n * @Inject\n * @var \\Hyperf\\Validation\\ValidatorFactory\n */\nprotected $validatorFactory;\n\npublic function store(Request $request)\n{\n    $validator = $this-\u003evalidatorFactory-\u003emake($request-\u003epost(), [\n        'user_type' =\u003e ['required', new EnumKey(UserType::class)],\n    ]);\n}\n```\n\n#### 枚举实例\n\n另外，我们可以验证参数是否为给定枚举的实例。\n\n```php\nuse HyperfExt\\Enum\\Rules\\Enum;\n\n/**\n * @Inject\n * @var \\Hyperf\\Validation\\ValidatorFactory\n */\nprotected $validatorFactory;\n\npublic function store(Request $request)\n{\n    $validator = $this-\u003evalidatorFactory-\u003emake($request-\u003epost(), [\n        'user_type' =\u003e ['required', new Enum(UserType::class)],\n    ]);\n}\n```\n\n### 管道验证\n\n也可以将“管道”语法用于验证规则。\n\n**enum_value**_:enum_class,[strict]_  \n**enum_key**_:enum_class_  \n**enum**_:enum_class_\n\n```php\n'user_type' =\u003e 'required|enum_value:' . UserType::class,\n'user_type' =\u003e 'required|enum_key:' . UserType::class,\n'user_type' =\u003e 'required|enum:' . UserType::class,\n```\n\n## 本地化\n\n本地化支持依赖 `hyperf/translation` 组件，不要忘记发布其配置并按需设置。\n\n```shell script\nphp bin/hyperf.php vendor:publish hyperf/translation\n```\n\n关于 `hyperf/translation` 组件的使用请阅读 [Hyperf 官方文档](https://hyperf.wiki/2.0/#/zh-cn/translation) 。\n\n### 验证器错误信息\n\n运行以下命令将语言文件发布到你的 `storage/languages` 目录中。\n\n```shell script\nphp bin/hyperf.php vendor:publish hyperf-ext/enum\n```\n\n### 枚举描述\n\n如果尚未通过 `vendor:publish` 命令发布语言文件，请先按照上面那条命令来发布。\n\n在此示例中，我们配置了英语和西班牙语两个语言文件。\n\n```php\n// storage/languages/en/enum.php\n\nuse App\\Enum\\UserType;\n\nreturn [\n    // …\n\n    UserType::class =\u003e [\n        UserType::Administrator =\u003e 'Administrator',\n        UserType::SuperAdministrator =\u003e 'Super administrator',\n    ],\n\n];\n```\n\n```php\n// storage/languages/es/enum.php\n\nuse App\\Enum\\UserType;\n\nreturn [\n    // …\n\n    UserType::class =\u003e [\n        UserType::Administrator =\u003e 'Administrador',\n        UserType::SuperAdministrator =\u003e 'Súper administrador',\n    ],\n\n];\n```\n\n最后，只需确保枚举类实现 `LocalizedEnum` 接口即可，如下所示：\n\n```php\nuse HyperfExt\\Enum\\Enum;\nuse HyperfExt\\Enum\\Contracts\\LocalizedEnum;\n\nfinal class UserType extends Enum implements LocalizedEnum\n{\n    // ...\n}\n```\n\n`getDescription` 方法将在语言文件中查找翻译的文本。如果给定键的值不存在，则返回默认描述。\n\n## 重写 getDescription 方法\n\n如果要通过 `getDescription` 方法返回自定义值，可以在枚举类中重写该方法来实现：\n\n```php\npublic static function getDescription($value): string\n{\n    if ($value === self::SuperAdministrator) {\n        return 'Super admin';\n    }\n\n    return parent::getDescription($value);\n}\n```\n\n现在，调用 `UserType::getDescription(3);` 将返回 `Super administator` 而不是 `Super admin`。\n\n## 扩展枚举基类\n\n枚举基类 `Enum` 实现了 Hyperf Macroable 特性，这意味着我们可以使用自己的函数轻松对其进行扩展。如果有经常要添加到每个枚举的函数，则可以使用宏。\n\n假设我们期望获得枚举类 `asArray` 方法的键值反转的版本，可以使用以下方法完成此操作：\n\n```php\nEnum::macro('asFlippedArray', function() {\n    return array_flip(self::asArray());\n});\n```\n\n现在在每个枚举中都可以使用 `UserType::asFlippedArray()` 来调用它。\n\n建议通过监听服务启动相关事件来注册宏。\n\n## PHPStan 集成\n\n如果要使用 [PHPStan](https://github.com/phpstan/phpstan) 进行静态分析，可以启用扩展程序以正确识别魔术实例化方法。\n\n将以下内容添加到项目的 `phpstan.neon` 的 includes 中：\n\n```neon\nincludes:\n- vendor/bensampo/laravel-enum/extension.neon\n```\n\n## 命令列表\n\n```shell script\nphp bin/hyperf.php gen:enum\n```\n生成一个新的枚举类。传递 `--flagged` 选项可以创建位标志枚举。[了解更多](#枚举定义)\n\n```shell script\nphp bin/hyperf.php enum:annotate\n```\n为枚举类生成 DocBlock 注释。[了解更多](#实例化)\n\n## Enum 类参考\n\n### static getKeys(): array\n\n返回包含枚举所有键的数组。\n\n```php\nUserType::getKeys(); // 返回 ['Administrator', 'Moderator', 'Subscriber', 'SuperAdministrator']\n```\n\n### static getValues(): array\n\n返回包含枚举所有值的数组。\n\n```php\nUserType::getValues(); // 返回 [0, 1, 2, 3]\n```\n\n### static getKey(mixed $value): string\n\n返回给定枚举值的键。\n\n```php\nUserType::getKey(1); // 返回 'Moderator'\nUserType::getKey(UserType::Moderator); // 返回 'Moderator'\n```\n\n### static getValue(string $key): mixed\n\n返回给定枚举键的值。\n\n```php\nUserType::getValue('Moderator'); // 返回 1\n```\n\n### static hasKey(string $key): bool\n\n确定枚举中是否含有给定的键。\n\n```php\nUserType::hasKey('Moderator'); // 返回 'True'\n```\n\n### static hasValue(mixed $value, bool $strict = true): bool\n\n确定枚举中是否含有给定的值。\n\n```php\nUserType::hasValue(1); // 返回 'True'\n\n// 可以禁用严格类型检查：\nUserType::hasValue('1'); // 返回 'False'\nUserType::hasValue('1', false); // 返回 'True'\n```\n\n### static getDescription(mixed $value): string\n\n以句首字母大写形式返回枚举键。可以通过[重写 getDescription 方法](#重写-getDescription-方法)来返回自定义描述。\n\n```php\nUserType::getDescription(3); // 返回 'Super administrator'\nUserType::getDescription(UserType::SuperAdministrator); // 返回 'Super administrator'\n```\n\n### static getRandomKey(): string\n\n随机返回枚举的一个键。\n\n```php\nUserType::getRandomKey(); // 返回 'Administrator', 'Moderator', 'Subscriber' 或 'SuperAdministrator'\n```\n\n### static getRandomValue(): mixed\n\n随机返回枚举的一个值。\n\n```php\nUserType::getRandomValue(); // 返回 0, 1, 2 或 3\n```\n\n### static getRandomInstance(): mixed\n\n随机返回枚举的一个实例。\n\n``` php\nUserType::getRandomInstance(); // 返回随机值的 UserType 实例\n```\n\n### static asArray(): array\n\n将枚举键值作为关联数组返回。\n\n```php\nUserType::asArray(); // 返回 ['Administrator' =\u003e 0, 'Moderator' =\u003e 1, 'Subscriber' =\u003e 2, 'SuperAdministrator' =\u003e 3]\n```\n\n### static asSelectArray(): array\n\n返回 value =\u003e description 形式的数组。\n\n```php\nUserType::asSelectArray(); // 返回 [0 =\u003e 'Administrator', 1 =\u003e 'Moderator', 2 =\u003e 'Subscriber', 3 =\u003e 'Super administrator']\n```\n\n### static fromValue(mixed $enumValue): Enum\n\n返回被调用枚举的实例。进一步了解[枚举实例化](#实例化)。\n\n``` php\nUserType::fromValue(UserType::Administrator); // 返回 UserType 的实例，该实例的值为 UserType::Administrator\n```\n\n### static getInstances(): array\n\n返回一个包含被调用枚举的所有可能实例的数组，以常量名作为键。\n\n```php\nvar_dump(UserType::getInstances());\n\narray(4) {\n  'Administrator' =\u003e\n  class HyperfExt\\Enum\\Tests\\Enums\\UserType#415 (3) {\n    public $key =\u003e\n    string(13) \"Administrator\"\n    public $value =\u003e\n    int(0)\n    public $description =\u003e\n    string(13) \"Administrator\"\n  }\n  'Moderator' =\u003e\n  class HyperfExt\\Enum\\Tests\\Enums\\UserType#396 (3) {\n    public $key =\u003e\n    string(9) \"Moderator\"\n    public $value =\u003e\n    int(1)\n    public $description =\u003e\n    string(9) \"Moderator\"\n  }\n  'Subscriber' =\u003e\n  class HyperfExt\\Enum\\Tests\\Enums\\UserType#393 (3) {\n    public $key =\u003e\n    string(10) \"Subscriber\"\n    public $value =\u003e\n    int(2)\n    public $description =\u003e\n    string(10) \"Subscriber\"\n  }\n  'SuperAdministrator' =\u003e\n  class HyperfExt\\Enum\\Tests\\Enums\\UserType#102 (3) {\n    public $key =\u003e\n    string(18) \"SuperAdministrator\"\n    public $value =\u003e\n    int(3)\n    public $description =\u003e\n    string(19) \"Super administrator\"\n  }\n}\n```\n\n### static coerce(mixed $enumKeyOrValue): ?Enum\n\n尝试使用给定的键或值实例化一个新的枚举。如果无法实例化，则返回 `null`。\n\n```php\nUserType::coerce(0); // 返回 UserType 的实例，该实例的值为 UserType::Administrator\nUserType::coerce('Administrator'); // 返回 UserType 的实例，该实例的值为 UserType::Administrator\nUserType::coerce(99); // 返回 null (无效的枚举值)\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperf-ext%2Fenum","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyperf-ext%2Fenum","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperf-ext%2Fenum/lists"}