README

PHP 枚举

此包为PHP提供强类型枚举。在这个包中，枚举总是对象，而不是独立的常量值。这允许在IDE中进行适当的静态分析和重构。

以下是使用此包创建枚举的方式

use \Spatie\Enum\Enum;

/**
 * @method static self draft()
 * @method static self published()
 * @method static self archived()
 */
class StatusEnum extends Enum
{
}

这是它们的用法

public function setStatus(StatusEnum $status): void
{
    $this->status = $status;
}

// ...

$class->setStatus(StatusEnum::draft());

支持我们

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

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

安装

您可以通过composer安装此包

composer require spatie/enum

用法

以下是定义枚举的方式。

/**
 * @method static self draft()
 * @method static self published()
 * @method static self archived()
 */
class StatusEnum extends Enum
{
}

这是它们的用法

public function setStatus(StatusEnum $status)
{
    $this->status = $status;
}

// ...

$class->setStatus(StatusEnum::draft());

从值创建枚举

$status = StatusEnum::from('draft');

当枚举值不存在时，您会收到一个BadMethodCallException。如果您不希望捕获异常，可以使用

$status = StatusEnum::tryFrom('draft');

在这种情况下，如果枚举值不存在，则$status将为null。

您只想从值构建枚举的情况是，例如，从数据库反序列化它们。

如果您想获取枚举的值以存储它，您可以这样做

$status->value;

请注意，value是一个只读属性，不能更改。

枚举值

默认情况下，枚举值是它的方法名。但是，您可以覆盖它，例如，如果您想将枚举存储为数据库中的整数，而不是使用它们的方法名。

/**
 * @method static self draft()
 * @method static self published()
 * @method static self archived()
 */
class StatusEnum extends Enum
{
    protected static function values(): array
    {
        return [
            'draft' => 1,
            'published' => 2,
            'archived' => 3,
        ];
    }
}

枚举值不一定是string，如示例所示，它也可以是int。

请注意，您不需要覆盖所有值。相反，只需覆盖那些您希望与默认值不同的值。

如果您有一个应用于所有方法名的逻辑来获取值，例如将它们转换为小写，则可以返回一个Closure。

/**
 * @method static self DRAFT()
 * @method static self PUBLISHED()
 * @method static self ARCHIVED()
 */
class StatusEnum extends Enum
{
    protected static function values(): Closure
    {
        return function(string $name): string|int {
            return mb_strtolower($name);
        };
    }
}

枚举标签

枚举可以赋予标签，您可以通过覆盖labels方法来完成此操作。

/**
 * @method static self draft()
 * @method static self published()
 * @method static self archived()
 */
class StatusEnum extends Enum
{
    protected static function labels(): array
    {
        return [
            'draft' => 'my draft label',
        ];
    }
}

请注意，您不需要覆盖所有标签，默认标签将是枚举的值。

如果您有一个应用于所有方法名的逻辑来获取标签，例如将它们转换为小写，则可以返回一个与值示例相同的Closure。

您可以通过以下方式访问枚举的标签

$status->label;

请注意，label是一个只读属性，不能更改。

比较枚举

可以使用equals方法比较枚举

$status->equals(StatusEnum::draft());

您可以将多个枚举传递给equals方法，如果当前枚举等于提供的值之一，它将返回true。

$status->equals(StatusEnum::draft(), StatusEnum::archived());

PHPUnit 断言

此包提供了一个抽象类Spatie\Enum\Phpunit\EnumAssertions，其中包含一些基本的/常见的断言，如果您必须测试枚举。

use Spatie\Enum\Phpunit\EnumAssertions;

EnumAssertions::assertIsEnum($post->status); // checks if actual extends Enum::class
EnumAssertions::assertIsEnumValue(StatusEnum::class, 'draft'); // checks if actual is a value of given enum
EnumAssertions::assertIsEnumLabel(StatusEnum::class, 'draft'); // checks if actual is a label of given enum
EnumAssertions::assertEqualsEnum(StatusEnum::draft(), 'draft'); // checks if actual (transformed to enum) equals expected
EnumAssertions::assertSameEnum(StatusEnum::draft(), $post->status); // checks if actual is same as expected
EnumAssertions::assertSameEnumValue(StatusEnum::draft(), 1); // checks if actual is same value as expected
EnumAssertions::assertSameEnumLabel(StatusEnum::draft(), 'draft'); // checks if actual is same label as expected

Faker 提供者

可能您正在使用faker并希望生成随机的枚举。由于默认的faker这样做需要大量的复制粘贴，我们为您提供了一个faker提供者Spatie\Enum\Faker\FakerEnumProvider来解决这个问题。

use Spatie\Enum\Faker\FakerEnumProvider;
use Faker\Generator as Faker;

/** @var Faker|FakerEnumProvider $faker */
$faker = new Faker();
$faker->addProvider(new FakerEnumProvider($faker));

$enum = $faker->randomEnum(StatusEnum::class);
$value = $faker->randomEnumValue(StatusEnum::class);
$label = $faker->randomEnumLabel(StatusEnum::class);

测试

composer test

更新日志

有关最近更改的详细信息，请参阅更新日志。

贡献

有关详细信息，请参阅贡献指南。

安全性

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

明信片软件

您可以使用这个包，但如果它进入了您的生产环境，我们非常感激您从家乡寄给我们一张明信片，注明您正在使用我们哪个包。

我们的地址是：Spatie，Kruikstraat 22，2018 安特卫普，比利时。

我们将所有收到的明信片发布在我们的公司网站上。

鸣谢

• Brent Roose
• 所有贡献者

许可

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