README

codekandis/phlags 引入了在 PHP 中使用可标记枚举的可能性。

索引

安装
测试
如何使用
- 声明
- 一般提示
- 实例化
- 读取
- 确定
- 操作
- 流畅操作
- 字符串表示
- 特性扩展
  - 条件操作
验证
- 可标记枚举
  - 值

安装

使用以下命令安装最新版本：

$ composer require codekandis/phlags

测试

使用以下命令测试代码：

$ composer test

如何使用

示例：文件系统中的简单权限

声明

声明一个扩展可标记基类的类 AbstractFlagable。

class Permissions extends AbstractFlagable
{
    public const int READ    = 1;
    public const int WRITE   = 2;
    public const int EXECUTE = 4;
}

一般提示

在操作可标记枚举的上下文中，以下值被认为是相等的，并且可以类似地传递给可标记枚举的所有方法。

1
Permissions::READ
new Permissions( 1 )
new Permissions( Permission::READ )
new Permissions( 'READ' );

另一方面，PHP 的类型限制不允许任何整数值与可标记枚举的组合。

new Permission( 1 | 'READ' | new Permissions( READ ) )

实例化

您可以轻松地以不同的方式实例化您的可标记枚举。

// with the default flag 'Permissions::NONE' (inherited from `FlagableInterface::NONE`)
$permissions = new Permissions();

// with a single flag
$permissions = new Permissions( Permissions::READ );

// with multiple flags
$permissions = new Permissions( Permissions::READ | Permissions::WRITE );

// with another flagable
$permissions = new Permissions( new Permissions( Permissions::READ ) );

// with string representations
$permissions = new ( 'READ' );
$permissions = new ( 'READ|WRITE' );
$permissions = new ( 'READ|WRITE|EXECUTE' );

// with mixed string representations
$permissions = new ( '1' );
$permissions = new ( '1|2' );
$permissions = new ( '1|WRITE|4' );

读取

您可以通过两种不同的方式读取可标记枚举的值。

$permissions = new Permissions( Permissions::READ );
echo $permissions->getValue();  // 1
echo $permissions();            // 1

确定

您可以确定一个或多个特定标记是否已设置。

$permissions = new Permissions( Permissions::READ | Permissions::WRITE );
$permissions->has( Permissions::READ );     // true
$permissions->has( Permissions::WRITE );    // true
$permissions->has( Permissions::EXECUTE );  // false

操作

您可以设置、取消设置和切换标记。

$permissions = new Permissions();
$permissions->set( Permissions::READ );
$permissions->unset( Permissions::READ );
$permissions->switch( Permissions::READ );
$permissions->has( Permissions::READ );     // true

流畅操作

基类 AbstractFlagable 实现了流畅接口。因此，可标记枚举的操作可以链接。

$permissions = new Permissions();
$permissions->set( Permissions::READ )
            ->unset( Permissions::READ )
            ->switch( Permissions::READ )
            ->has( Permissions::READ );    // true

字符串表示

可标记枚举可以以不同的方式字符串化，输出不同。

$permissions = new Permissions();
(string)$permissions->getValue();  // 0
(string)$permissions();            // 0
(string)$permissions;              // NONE
$permissions->__toString();        // NONE

$permissions = new Permissions( PERMISSIONS::READ | PERMISSIONS::EXECUTE );
(string)$permissions->getValue();  // 5
(string)$permissions();            // 5
(string)$permissions;              // READ|EXECUTE
$permissions->__toString();        // READ|EXECUTE

特性扩展

为了保持简单性和性能，Phlags 提供了 Traitful Extensions。您不需要实现复杂和重量级的继承，而是可以将您选择的扩展组合到所需的可标记枚举中。

class Permissions extends AbstractFlagable SomeTraitfulInterface
{
    use SomeTraitfulExtension;

    public const int READ    = 1;
    public const int WRITE   = 2;
    public const int EXECUTE = 4;
}

条件操作

— ConditionalManipulationExtension

条件操作提供您设置、取消设置和切换标记值的方法，而传递的语句必须评估为 true。

$pathToFile = '/some-random-file.txt';
$permissions = new Permissions();
$permissions->ifSet( Permissions::DIRECTORY, is_dir( $pathToFile ) );
$permissions->has( Permissions::DIRECTORY );  // false

$pathToFile = '/some-random-directory';
$permissions = new Permissions();
$permissions->ifSet( Permissions::DIRECTORY, is_dir( $pathToDirectory ) );
$permissions->has( Permissions::DIRECTORY );  // true

验证

可标记枚举

在实例化您的第一个可标记枚举时，您的可标记枚举必须通过一次性验证。

所有声明的常量都是 无符号整数
所有常量都是 2 的幂
没有常量值重复
没有缺失值，例如，设置标记为 1, 2, 8 的标记枚举是无效的，而标记 4 缺失

如果标记枚举未通过验证，将抛出 InvalidFlagableException，并且您可以检索验证的错误消息数组。

try
{
    $permissions = new Permissions();
}
catch ( InvalidFlagableException $e )
{
    $errorMessages = $e->getErrorMessages();
}

值

传递给标记枚举方法的标记值必须在每次方法调用时通过验证。

它是一个小于或等于调用标记枚举最大值的 无符号整数
它是标记枚举的 字符串 表示，其类型与调用标记枚举的类型相同
它是一个与调用标记枚举类型相同的标记枚举
它不超出调用标记枚举的最大标记值

如果值未通过验证，将抛出 InvalidValueException，并且您可以检索验证的错误消息数组。

try
{
    $permissions->set( $value );
}
catch ( InvalidValueException $e )
{
    $errorMessages = $e->getErrorMessages();
}

codekandis / phlags

维护者

详细信息