README

此包为您的 Symfony2 项目提供类型化枚举。

注意：对于 Symfony 2.0.x，您需要使用此包的 1.0.0 版本。

注意：对于低于 2.7 的 Symfony，您需要使用此包的 1.2.0 版本。

功能

• 为枚举类型提供基本实现。
• 为标志枚举类型提供基本实现（作为位字段，即一组标志）。
• 使用枚举类型与 Symfony 的表单组件。
• 包含 Symfony 的序列化组件的正常化程序。
• 包含 JMSSerializerBundle 的自定义处理程序。

安装

将此包添加到您的项目中

在 shell 中运行以下命令以安装包

$ composer require yethee/enum-bundle

将包添加到您的应用程序内核中

<?php
// app/AppKernel.php

public function registerBundles()
{
    return array(
        // ...
        new Biplane\EnumBundle\BiplaneEnumBundle(),
        // ...
    );
}

用法

为了创建类型化枚举，只需扩展基类 Biplane\EnumBundle\Enumeration\Enum

• 定义常量并实现 getPossibleValues() 和 getReadables() 方法。第一个方法应返回枚举的可能值数组，第二个方法返回可能值及其人类表示的哈希表。

以下是一个简单的用户角色枚举实现示例

<?php

use Biplane\EnumBundle\Enumeration\Enum;

class UserRoles extends Enum
{
    const MEMBER = 'ROLE_MEMBER';
    const ADMIN  = 'ROLE_ADMIN';

    public static function getPossibleValues()
    {
        return array(static::MEMBER, static::ADMIN);
    }

    public static function getReadables()
    {
        return array(static::MEMBER => 'Member', static::ADMIN => 'Admin');
    }
}

您可以通过 create() 工厂方法创建枚举的新实例，该工厂方法提供基类

$role = UserRoles::create(UserRoles::ADMIN);

如果参数包含无效值，将抛出 Biplane\EnumBundle\Exception\InvalidEnumArgumentException 类型的异常。

以下代码示例展示了如何从对象中获取枚举值的原始值或人类表示

$role->getValue(); // returns string 'ROLE_ADMIN'
$role->getReadable(); // returns string 'Admin'

您还可以将对象转换为字符串以获取枚举值的人类表示

(string)$role;

位标志支持

如果您要在数值上执行位操作，则可以扩展 Biplane\EnumBundle\Enumeration\FlaggedEnum 以用于枚举。

在这种情况下，以 2 的幂定义枚举常量，即 1、2、4、8 等。这意味着组合枚举常量中的单个标志不重叠。您还可以创建用于常用标志组合的枚举常量，但这些常量的值 不得 由 getPossibleValues() 方法返回。

以下是一个权限列表标志枚举的实现示例

<?php

use Biplane\EnumBundle\Enumeration\FlaggedEnum;

class Permissions extends FlaggedEnum
{
    const READ   = 1;
    const WRITE  = 2;
    const REMOVE = 4;
    const ALL    = 7;

    public static function getPossibleValues()
    {
        return array(static::READ, static::WRITE, static::REMOVE);
    }

    public static function getReadables()
    {
        return array(
            static::READ   => 'Read',
            static::WRITE  => 'Write',
            static::REMOVE => 'Remove',
            static::ALL    => 'All permissions',
        );
    }
}

您可以使用位操作在常量上创建枚举的新实例

$permissions = Permissions::create(Permissions::READ | Permissions::WRITE);

此类枚举提供了一些额外的方法

• getFlags() 返回枚举值的位标志数组。对于前面的示例，此方法返回 array(1, 2)。

• hasFlag() 如果指定的标志在数值中设置，则返回 true。

与 Doctrine ORM 一起使用

您可以在实体中存储枚举的原始值，并在获取和设置中使用类型转换

<?php

use Doctrine\ORM\Mapping as ORM;

class User
{
    /**
     * @ORM\Column(type="string")
     */
    private $role;

    public function getRole()
    {
        return UserRoles::create($this->role);
    }

    public function setRole(UserRoles $role)
    {
        $this->role = $role->getValue();
    }
}

或者您可以为 DBAL 创建一个自定义类型，以将类型转换的逻辑从实体中移动出来

<?php

namespace Acme\DemoBundle\Doctrine\Type;

use Doctrine\DBAL\Types\StringType;
use Doctrine\DBAL\Platforms\AbstractPlatform;

class RoleType extends StringType
{
    public function getName()
    {
        return 'role_enum';
    }

    public function convertToDatabaseValue($value, AbstractPlatform $platform)
    {
        return $value->getValue();
    }

    public function convertToPHPValue($value, AbstractPlatform $platform)
    {
        if ($value === null) {
            return null;
        }

        return UserRoles::create($value);
    }
}

注意：在 convertToPHPValue 方法中创建枚举的新实例之前，您应手动将原始值转换为枚举的有效类型。因为此方法总是将值作为字符串（或 null）传递。

之后，您应该注册您的类型，这可以通过配置完成

# app/config/config.yml
doctrine:
    dbal:
        types:
            role_enum: Acme\DemoBundle\Doctrine\Type\RoleType

在实体的映射中设置您的类型

<?php

use Doctrine\ORM\Mapping as ORM;

class User
{
    /**
     * @ORM\Column(type="role_enum")
     */
    private $role;
}

JMSSerializerBundle 支持

本包为序列化器提供自定义处理程序，允许将枚举对象序列化为标量值，并转换为JSON或XML格式。自定义处理程序仅用于在配置中指定的那些类型枚举。

您可以通过配置来注册您的类型枚举。

# app/config/config.yml
biplane_enum:
    serializer:
        types:
            - Acme\DemoBundle\Enum\MyEnum
            - Acme\UserBundle\Enum\UserRoles
            # etc