README

此包是 consistence/consistence 的分支，增加了对 PHP 8 的支持。

PHP 提供了大量的实用功能，但由于其有机增长，这些功能并不总是易于使用。此库的目的是提供 PHP 功能的一致性方法。这意味着

• 清晰且一致的名字模式
• 一致的参数顺序
• 错误报告为异常，而不是返回值
• 添加的功能和接口，这些功能缺失
• 表示常见元素的值对象

安装

使用 Composer 安装包 slevomat/consistence

composer require slevomat/consistence

没有其他步骤，您可以在代码库中适当时使用 Consistence，下面是功能说明。

集成

如果您正在使用以下库/框架之一，请查看这些集成

• Doctrine ORM 集成 提供通过实体将 Consistence 值对象存储到数据库的集成，还有一个 带有此集成的 Symfony 扩展
• JMS Serializer 集成 提供集成以（反）序列化 Consistence 值对象，还有一个 带有此集成的 Symfony 扩展

文档 & 功能

在以下部分中，有一些 Consistence 功能摘录，帮助关键领域，以及链接到专门的文档页面。

枚举和多枚举

枚举表示预定义值的集合。每个枚举类静态地定义了可用的值。每个值通过该类的一个实例以轻量级方式表示。这确保了相同的值总是相同的实例。

<?php

class CardColor extends \Consistence\Enum\Enum
{

	public const BLACK = 'black';
	public const RED = 'red';

}

$red = CardColor::get(CardColor::RED);

$availableValues = CardColor::getAvailableValues(); // ['black', 'red']

function doMagicTrick(CardColor $guessedCardColor)
{
	// ...
}

使用枚举表示值集合的主要优点是

• 您可以确保值没有更改（而不仅仅是验证一次）
• 您可以使用类型提示来检查是否只接受定义的值集合
• 您可以在表示的值之上定义行为

> 在 Consistence 中了解更多关于枚举的信息

通过 多枚举，您甚至可以在单个对象中表示多个值及其操作。

严格类型

PHP 默认包含大量魔法行为，几乎不做任何检查。当期望特定类型时，PHP 会尝试将给定类型转换为期望的类型，这可能会导致意外结果。一致性提倡使用严格类型，以实现更可预测、可维护和可读的代码。

<?php

class Foo extends \Consistence\ObjectPrototype
{

}

$foo = new Foo();

// \Consistence\UndefinedPropertyException: Property Foo::$bar is not defined or is not accessible
$foo->bar = 'bar';

<?php

use Consistence\Type\Type;

Type::checkType('foo', 'string');
Type::checkType('foo', 'string|int');
Type::checkType(1, 'string|int');
Type::checkType(
	[
		[
			'foo',
		],
		[
			'bar',
		],
	],
	'string[][]'
);

> 在 Consistence 中了解更多关于严格类型的信息

时间格式

使用 值对象 很好，因为你可以得到清晰的类型提示，并且可以确信你得到的是处于一致状态且有效的值（如果表示形式遵循原则）。

DateTime 是 PHP 中原生的少数几个值对象之一。不幸的是，PHP 仍然默认倾向于使用魔法行为而不是清晰的错误，并且还缺少许多常用的功能，因此 Consistence 尝试帮助解决这些不足。

<?php

use Consistence\Time\TimeFormat;

// example of strict validation of format:

// H requires leading zero, but there is none
// \Consistence\Time\TimeDoesNotMatchFormatException: Time "2:30" does not match format "H:i"
TimeFormat::createDateTimeFromFormat('H:i', '2:30');

// example of strict validation of values:

// there is no 25th hour in the day
// \Consistence\Time\TimeDoesNotExistException: Time given in "25:00" does not exist
TimeFormat::createDateTimeFromFormat('H:i', '25:00');

> 在 Consistence 中了解更多关于时间格式信息

数组

PHP 中的数组是传统 列表 和 字典 的组合，因此具有广泛的应用。由于它们非常常见，因此有很多重复的操作用于操作这些数据结构。这些操作应该被抽象成函数，以便可以重用，并且代码中只包含业务逻辑。

通过自定义规则简单查找值（例如，“查找少于五个字符的值”）可能会很麻烦

<?php

$haystack = ['lorem', 'ipsum', 'dolor', 'sit', 'amet'];
foreach ($haystack as $value) {
	if (strlen($value) < 5) {
		// do something with value
	}
}

在上一个例子中，有数组遍历的逻辑与业务逻辑混合。可以通过使用专门的迭代方法来改进。然后只有业务逻辑保留在回调中

<?php

use Consistence\Type\ArrayType\ArrayType;

$haystack = ['lorem', 'ipsum', 'dolor', 'sit', 'amet'];
$value = ArrayType::findValueByCallback($haystack, function($value) {
	return strlen($value) < 5;
});
if ($value !== null) {
	// do something with value
}

PHP 有很多 数组操作函数，但使用它们很困难，因为它们没有统一的 API，并且从不抛出任何异常，错误只通过返回值报告。这些函数在默认情况下也使用非严格比较进行搜索。Consistence 尝试解决这些问题。

> 在 Consistence 中了解更多关于数组信息