README

bramus/enumeration 是 PHP 的枚举实现。它允许用户创建单一枚举和组合枚举。

由 Bramus Van Damme (https://www.bram.us) 和 贡献者 构建

先决条件/要求

• PHP 7.2 或更高版本

安装

可以使用 Composer 进行安装

$ composer require bramus/enumeration ~1.4

用法

单一枚举

<?php

use Bramus\Enumeration\Enumeration;

class Weekday extends Enumeration
{
	const MONDAY = 1;
	const TUESDAY = 2;
	const WEDNESDAY = 3;
	const THURSDAY = 4;
	const FRIDAY = 5;
	const SATURDAY = 6;
	const SUNDAY = 7;
}

创建和实例操作

$instance = new Weekday(1);
$instance = new Weekday(Weekday::MONDAY);
$instance = Weekday::MONDAY();

$instance->getValue();
// ~> 1

$instance->getIdentifier();
// ~> 'MONDAY'

(string) $instance;
// ~> '1'

在值和标识符之间转换

Weekday::toValue('MONDAY');
// ~> 1

Weekday::toIdentifier(1);
// ~> 'MONDAY;

列出值和标识符

Weekday::values();
// ~> [1, 2, 3, 4, 5, 6, 7]

Weekday::identifiers();
// ~> ['MONDAY', 'TUESDAY', 'WEDNESDAY', 'THURSDAY', 'FRIDAY', 'SATURDAY', 'SUNDAY']

检查值和标识符

Weekday::isValidValue(2);
// ~> true

Weekday::isValidValue(8);
// ~> false

Weekday::isValidIdentifier('TUESDAY');
// ~> true

Weekday::isValidIdentifier('SUMMERDAY');
// ~> false

组合枚举

一个枚举也可以由几个其他枚举组成

<?php

namespace Bramus\Http\StatusCodes;

use Bramus\Enumeration\Enumeration;
use Bramus\Enumeration\ComposedEnumeration;

abstract class Informal extends Enumeration
{
	const CONTINUE = 100;
	const SWITCHING_PROTOCOLS = 101;
	const PROCESSING = 102;
	…
}

abstract class Success extends Enumeration
{
	const OK = 200;
	const CREATED = 201;
	const ACCEPTED = 202;
	…
}

abstract class Redirection extends Enumeration
{
	const MULTIPLE_CHOICES = 300;
	const MOVED_PERMANENTLY = 301;
	const FOUND = 302;
	…
}

abstract class ClientError extends Enumeration
{
	const BAD_REQUEST = 400;
	const UNAUTHORIZED = 401;
	const PAYMENT_REQUIRED = 402;
	…
	const IM_A_TEAPOT = 418;
	…
}

abstract class ServerError extends Enumeration
{
	const INTERNAL_SERVER_ERROR = 500;
	const NOT_IMPLEMENTED = 501;
	const BAD_GATEWAY = 502;
	…
	const NETWORK_AUTHENTICATION_REQUIRED = 511;
}

class StatusCode extends ComposedEnumeration
{
	public static $classes = [
		'\Bramus\Http\StatusCodes\Informal',
		'\Bramus\Http\StatusCodes\Success',
		'\Bramus\Http\StatusCodes\Redirection',
		'\Bramus\Http\StatusCodes\ClientError',
		'\Bramus\Http\StatusCodes\ServerError',
	];
}

@note: 虽然技术上可以在组成组合枚举的类中重用相同的标识符和值，但建议不要这样做。

创建和实例操作

use Bramus\Http\StatusCodes\StatusCode;

$instance = new StatusCode(200);
// $instance = new StatusCode(StatusCode::OK); <-- This won't work, due to __getStatic not existing in PHP …
$instance = StatusCode::OK();

$instance->getValue();
// ~> 200

$instance->getIdentifier();
// ~> 'OK'

(string) $instance;
// ~> '200'

在值和标识符之间转换

StatusCode::toValue('OK');
// ~> 200

StatusCode::toIdentifier(200);
// ~> 'OK;

列出值和标识符

StatusCode::values();
// ~> [100, 101, 102, …, 200, 201, 202, …, 511]

StatusCode::identifiers();
// ~> ['CONTINUE', 'SWITCHING_PROTOCOLS', 'PROCESSING', …, 'OK', 'CREATED', 'ACCEPTED', …, 'NETWORK_AUTHENTICATION_REQUIRED']

检查值和标识符

StatusCode::isValidValue(418);
// ~> true

StatusCode::isValidValue(700);
// ~> false

StatusCode::isValidIdentifier('IM_A_TEAPOT');
// ~> true

StatusCode::isValidIdentifier('BROKEN');
// ~> false

默认值

如果您想，您可以定义一个默认值来使用。在您的类中将它定义为名为 __DEFAULT 的常量即可

<?php

use Bramus\Enumeration\Enumeration;

class Weekday extends Enumeration
{
	const __DEFAULT = 1;

	const MONDAY = 1;
	const TUESDAY = 2;
	…
}

当构造函数没有传入值时将使用默认值

$instance = new Weekday();

// object(Weekday)#424 (2) {
//  ["value":"Bramus\Enumeration\Enumeration":private]=>
//  int(1)
//  ["identifier":"Bramus\Enumeration\Enumeration":private]=>
//  string(6) "MONDAY"
//}

这对 Enumeration 和 ComposedEnumeration 类都适用

class StatusCode extends ComposedEnumeration
{
	const __DEFAULT = 200;

	public static $classes = [
		…
	];
}

摘要和描述

在定义与枚举常量一起使用的 DocBlocks 时，您可以使用 getSummary() 和 getDescription() 方法分别获取其摘要和描述。

<?php

use Bramus\Enumeration\Enumeration;

class Weekday extends Enumeration
{
	/**
	 * Monday.
	 *
	 * The first day of the week.
	 */
	const MONDAY = 1;

	//
}

$instance = new Weekday(1);

$instance->getSummary();
// ~> 'Monday.'

$instance->getDescription();
// ~> 'The first day of the week.'

也提供了获取这些信息的静态方法。对于每个方法，它们的唯一参数是有效的枚举值或 Bramus\Enumeration\Enumeration 实例

Weekday::toSummary(Weekday::MONDAY);
// ~> 'Monday.'

Weekday::toSummary($instance);
// ~> 'Monday.'

Weekday::toDescription(Weekday::MONDAY);
// ~> 'The first day of the week.'

Weekday::toDescription($instance);
// ~> 'The first day of the week.'

还可能获取所有摘要/描述的列表。返回一个以枚举值为键的数组

$summaries = Weekday::summaries();
// ~> [1 => 'Monday.', 2 => 'Tuesday.', …, 7 => 'Sunday.']

$descriptions = Weekday::descriptions();
// ~> [1 => 'The first day of the week', 2 => 'The second day of the week', …, 7 => 'The seventh day of the week']

比较值

要比较 Bramus\Enumeration\Enumeration 实例与值，请使用 $instance->equals()

$instance = new Weekday(Weekday::MONDAY);

$instance->equals(1);
// ~> true

比较 Bramus\Enumeration\Enumeration 实例与其他 Bramus\Enumeration\Enumeration 也是可能的

$instance = new Weekday(Weekday::MONDAY);
$otherInstance = Weekday::MONDAY();

$instance->equals($otherInstance);
// ~> true

实用类

bramus/enumeration 包含 2 个实用类。虽然您可能不需要直接使用这些类，但它们可能会有所帮助

\Bramus\Enumeration\Helpers\Extractor

此类从 \Bramus\Enumeration\Enumeration 类中提取常量/标识符/值。它由 \Bramus\Enumeration\Enumeration 内部使用。

\Bramus\Enumeration\Helpers\Generator

此类允许用户生成 \Bramus\Enumeration\Enumeration 类的实例。以下面示例中的 \Bramus\Http\StatusCodes\StatusCode 类为例，其用法可能如下所示

use Bramus\Enumeration\Helpers\Generator;

Generator::setNamespace('\\Bramus\\Http\\StatusCodes\\');

Generator::generateStatusCode(); // Generates a \Bramus\Http\StatusCodes\StatusCode instance with its default value
Generator::generateStatusCode(404); // Generates a \Bramus\Http\StatusCodes\StatusCode instance with the value 404

@note: 如果 Enumeration 没有 __DEFAULT（例如，它是 NULL），则调用 Generator::generate* 将返回枚举的随机值。

测试

bramus/enumeration 随附使用 PHPUnit ~8.0 的单元测试。

• 如果全局安装了 PHPUnit，则运行 phpunit 以运行测试。
• 如果未全局安装 PHPUnit，则通过运行 composer install --dev 在本地安装它。通过调用 ./vendor/bin/phpunit 或使用 composer 脚本 composer test 运行测试本身

$ composer test

许可协议

bramus/enumeration 根据 MIT 公共许可证发布。有关详细信息，请参阅附带的 LICENSE 文件。