A simple and easy-to-use enumeration extension package to help you manage enumerations in your project more conveniently, supporting Laravel and Lumen.
- 一个简单好用的枚举扩展包，帮助你更方便地管理项目中的枚举，支持 Laravel 和 Lumen。
中文文档 | English
laravel-enum 主要用来扩展项目中的枚举使用，通过合理的定义枚举可以使代码更加规范，更易阅读和维护。
php8.1 版本后内置枚举支持，更多信息可以查看：https://www.php.net/manual/zh/language.enumerations.php
参与社区讨论：- 教你更优雅地写 API 之「枚举使用」
- 🌍 多语言支持：扩展原生的 BackedEnum，支持多语言描述
- 🔧 实例化方法：提供多种实用的方式来实例化枚举（fromValue、fromName、guess、random）
- 📊 数据获取：便捷获取枚举 name、value、names、values、count 等信息
- 🔍 比较方法：提供便捷的比较方法
is、isNot、isAny，用于枚举实例之间的对比 - 🧭 导航功能：支持枚举位置检查（isFirst、isLast）和导航（next、previous）
- 📋 数组转换：支持转换为数组格式，适用于 API 响应和表单选项
⚠️ 错误处理：提供详细的错误信息，包含有效值提示
支持 Laravel 10 以上版本：
$ composer require jiannei/laravel-enum -vvv更为具体的使用可以查看测试用例：https://github.com/Jiannei/laravel-enum/tree/main/tests
- 定义
<?php
namespace Jiannei\Enum\Laravel\Tests\Enums;
use Jiannei\Enum\Laravel\Support\Traits\EnumEnhance;
enum UserType: int
{
use EnumEnhance;
case ADMINISTRATOR = 0;
case MODERATOR = 1;
case SUBSCRIBER = 2;
}// 获取枚举的值
UserType::ADMINISTRATOR->value; // 0
// 获取枚举的名称
UserType::ADMINISTRATOR->name(); // 'ADMINISTRATOR'
// 获取枚举的值（通过方法）
UserType::ADMINISTRATOR->value(); // 0
// 获取所有已定义枚举的名称
$names = UserType::names(); // ['ADMINISTRATOR', 'MODERATOR', 'SUBSCRIBER']
// 获取所有已定义枚举的值
$values = UserType::values(); // [0, 1, 2]
// 获取枚举数量
$count = UserType::count(); // 3// 检查定义的枚举中是否包含某个「枚举值」
UserType::hasValue(1); // true
UserType::hasValue(-1); // false
// 检查定义的枚举中是否包含某个「枚举名称」
UserType::hasName('MODERATOR'); // true
UserType::hasName('ADMIN'); // false枚举实例化以后可以方便地通过对象实例访问枚举的 name、value 以及 description 属性的值。
// 通过 value 实例化
$admin = UserType::fromValue(0); // UserType::ADMINISTRATOR
// 通过 name 实例化
$admin = UserType::fromName('ADMINISTRATOR'); // UserType::ADMINISTRATOR
// 通过 name/value 智能猜测
$subscriber = UserType::guess(2); // UserType::SUBSCRIBER
$subscriber = UserType::guess('SUBSCRIBER'); // UserType::SUBSCRIBER
// 获取随机枚举实例
$random = UserType::random(); // 随机返回一个枚举实例$admin = UserType::ADMINISTRATOR;
// 检查是否等于某个枚举
$admin->is(UserType::ADMINISTRATOR); // true
$admin->is(UserType::SUBSCRIBER); // false
// 检查是否不等于某个枚举
$admin->isNot(UserType::SUBSCRIBER); // true
$admin->isNot(UserType::ADMINISTRATOR); // false
// 检查是否为多个枚举中的任意一个
$admin->isAny(UserType::ADMINISTRATOR, UserType::MODERATOR); // true
$admin->isAny(UserType::MODERATOR, UserType::SUBSCRIBER); // false$admin = UserType::ADMINISTRATOR;
$moderator = UserType::MODERATOR;
$subscriber = UserType::SUBSCRIBER;
// 检查是否为第一个枚举
$admin->isFirst(); // true
$moderator->isFirst(); // false
// 检查是否为最后一个枚举
$subscriber->isLast(); // true
$admin->isLast(); // false
// 获取下一个枚举（如果是最后一个则返回 null）
$admin->next(); // UserType::MODERATOR
$moderator->next(); // UserType::SUBSCRIBER
$subscriber->next(); // null
// 获取上一个枚举（如果是第一个则返回 null）
$admin->previous(); // null
$moderator->previous(); // UserType::ADMINISTRATOR
$subscriber->previous(); // UserType::MODERATOR// 转换为详细数组
$array = UserType::toArray();
/*
[
['name' => 'ADMINISTRATOR', 'value' => 0, 'description' => '管理员'],
['name' => 'MODERATOR', 'value' => 1, 'description' => '主持人'],
['name' => 'SUBSCRIBER', 'value' => 2, 'description' => '订阅用户'],
]
*/
// 转换为选择数组（适用于下拉框等场景）
$selectArray = UserType::toSelectArray(); // 支持多语言配置
/*
[
0 => '管理员',
1 => '主持人',
2 => '订阅用户',
]
*/
// 指定本地化组
$selectArray = UserType::toSelectArray('*');
/*
[
0 => '管理员',
1 => '监督员',
2 => '订阅用户',
]
*/枚举支持多语言描述，通过 description() 方法获取：
// 获取默认语言描述
UserType::ADMINISTRATOR->description(); // '管理员'
// 获取指定本地化组的描述
UserType::ADMINISTRATOR->description('*'); // 可能返回不同的翻译
// 在数组转换中使用多语言
$array = UserType::toArray('custom_group');
$selectArray = UserType::toSelectArray('custom_group');当使用无效的名称或值时，会抛出详细的错误信息：
try {
UserType::fromName('INVALID_NAME');
} catch (ValueError $e) {
// 错误信息会包含所有有效的枚举名称
echo $e->getMessage(); // "Invalid enum name "INVALID_NAME". Valid names are: ADMINISTRATOR, MODERATOR, SUBSCRIBER"
}
try {
UserType::fromValue(999);
} catch (ValueError $e) {
// 错误信息会包含所有有效的枚举值
echo $e->getMessage(); // "Invalid enum backing value "999". Valid values are: 0, 1, 2"
}// 在控制器中使用
class UserController extends Controller
{
public function index(Request $request)
{
$userType = UserType::fromValue($request->input('type', 0));
$users = User::where('type', $userType->value)->get();
return response()->json([
'users' => $users,
'current_type' => [
'name' => $userType->name(),
'value' => $userType->value(),
'description' => $userType->description(),
'is_admin' => $userType->is(UserType::ADMINISTRATOR),
]
]);
}
public function getTypes()
{
return response()->json([
'types' => UserType::toSelectArray(),
'count' => UserType::count(),
]);
}
}
// 在模型中使用
class User extends Model
{
protected $casts = [
'type' => UserType::class,
];
public function isAdmin(): bool
{
return $this->type->is(UserType::ADMINISTRATOR);
}
public function canModerate(): bool
{
return $this->type->isAny(UserType::ADMINISTRATOR, UserType::MODERATOR);
}
public function getNextRole(): ?UserType
{
return $this->type->next();
}
}
// 在表单验证中使用
class CreateUserRequest extends FormRequest
{
public function rules()
{
return [
'type' => ['required', 'integer', Rule::in(UserType::values())],
];
}
}- https://laravel.com/docs/11.x/requests#retrieving-enum-input-values
- https://laravel.com/docs/11.x/validation#rule-enum
| 方法 | 返回类型 | 描述 |
|---|---|---|
names() |
array<string> |
获取所有枚举名称 |
values() |
array<int|string> |
获取所有枚举值 |
count() |
int |
获取枚举数量 |
hasName(string $name) |
bool |
检查是否包含指定名称 |
hasValue(mixed $value) |
bool |
检查是否包含指定值 |
fromName(string $name) |
static |
通过名称实例化 |
fromValue(mixed $value) |
static |
通过值实例化 |
guess(mixed $value) |
static |
智能猜测实例化 |
random() |
static |
获取随机枚举实例 |
toArray(?string $localizationGroup = null) |
array |
转换为详细数组 |
toSelectArray(?string $localizationGroup = null) |
array |
转换为选择数组 |
| 方法 | 返回类型 | 描述 |
|---|---|---|
name() |
string |
获取枚举名称 |
value() |
int|string |
获取枚举值 |
description(?string $localizationGroup = null) |
string |
获取描述 |
is(BackedEnum $enum) |
bool |
检查是否等于指定枚举 |
isNot(BackedEnum $enum) |
bool |
检查是否不等于指定枚举 |
isAny(BackedEnum ...$enums) |
bool |
检查是否为任意指定枚举 |
isFirst() |
bool |
检查是否为第一个枚举 |
isLast() |
bool |
检查是否为最后一个枚举 |
next() |
?static |
获取下一个枚举 |
previous() |
?static |
获取上一个枚举 |
MIT