README

此包是consistence/consistence的分支，由社区维护以支持新的PHP版本。

PHP提供了许多便利的功能，但由于其有机增长，这并不总是易于使用。这个库的目标是提供对PHP功能的统一方法。这意味着

• 清晰的、一致的命名模式
• 一致的参数顺序
• 错误以异常的形式报告，而不是作为返回值
• 添加了缺失的功能和接口
• 表示常见元素的价值对象

安装

使用Composer安装包consistence-community/consistence

composer require consistence-community/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会尝试将给定的类型转换为期望的类型，这可能会导致意外结果。Consistence提倡使用严格类型，以实现更可预测、可维护和可读的代码。

<?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中了解更多关于数组的内容