README

为 SPF 提供各种支持元素，例如

• 集合
• 配置
• 字段集和字段
• Twig 扩展
• 验证

要求

此库仅需要 PHP 7.2 或更高版本以及 SPF Contracts 包 (simon-downes/spf-contracts)。

安装

可以通过 Composer 安装和自动加载，作为 simon-downes/spf-support。

或者，下载一个版本或克隆此存储库，并将 \spf\support 命名空间添加到自动加载器。

许可证

SPF Support 是开源软件，许可协议为 MIT。

集合

此包提供了在 spf-contracts 包中定义的 Collection、Dictionary 和 Set 接口的基本实现。

BaseCollection 在其构造函数中接受一个项目数组，并提供了基本的集合操作，如迭代、计数、清空和检查是否存在。不支持添加或删除单个项目，这由特定的子类提供。

BaseDictionary 扩展 BaseCollection 以支持添加和删除键/值对 - 每个键都是唯一的。

BaseSet 扩展 BaseCollection 以支持添加和删除唯一项。

use spf\support\collections\{BaseCollection, BaseDictionary, BaseSet};

$c = new BaseCollection([123, 456, 789]);

$c->count();		// returns 3
$c->contains(456);	// returns true
$c->contains(234);	// returns false
$c->isEmpty();		// returns false
$c->clear();		// remove all items
$c->isEmpty();		// returns true

$d = new BaseDictionary();

$d->add('foo', 123);
$d->add('bar', 456);
$d->has('foo');		// returns true
$d->has('baz');		// returns false
$d->get('foo');		// returns 123
$d->keys();			// returns ['foo', 'bar']
$d->remove('bar');

$d = new BaseSet();

$d->add('foo');
$d->add('bar');
$d->contains('foo');	// returns true
$d->remove('bar');
$d->contains('bar');	// returns false

配置

BaseConfig 提供了一个基本的配置对象，其底层实现是一个数组。数组可以通过 load() 从外部文件填充，或通过 merge() 从现有数组填充。还提供了方法，允许轻松访问嵌套元素。

use spf\support\BaseConfig;

$c = new BaseConfig([
	'foo' => [
		'bar' => 123,
		'baz' => 456,
	],
]);

$c->get('foo.bar');	// returns 123

$c->set('foo.baz', 789);	// changes the value of ['foo']['bar']

// overwrite the 'foo' branch and add an additional value for 'bar'
$c->merge([
	'foo' => 'abc',
	'bar' => 'def',
]);

$c->get('foo.bar');	// returns null (key doesn't exist)

$c->get('bar');	// returns 'def'

$c->load(__DIR__. 'config.php');	// 'config.php' should return an array

字段集和字段

字段表示对象属性、数据库列或类似的构造。

字段集是字段的集合，可以用作数据库表/模型定义、HTML 表单定义等。

字段

字段必须有一个名称和一个类型，并可选择有额外的规则来定义被视为有效的值的规则。

支持的字段类型在 spf\contracts\support\Type 中列出。

use spf\support\Field;

$f = new Field('id', Type::INTEGER);
$f = new Field('email', Type::EMAIL, ['required' => true, 'unique' => true]);
$f = new Field(
	'status',
	Type::ENUM,
	[
		'required' => true,
		'values' => ['EMPLOYEE', 'PARTNER', 'OTHER']
	]
);

可用规则

• required - [布尔值] 如果为真，必须有非空值（默认：false）
• nullable - [布尔值] 确定是否接受 null 作为值（默认：false）
• default - [混合] 如果未指定，则使用的默认值（默认：基于类型的空值）
• label - [字符串] 用户友好的标签，（默认：标题化名称）
• unique - [布尔值] 确定值是否应该是唯一的（默认：false）
• min - [整数|字符串] 可接受的最小值
• max - [整数|字符串] 可接受的最大值
• min-length - [整数] 值的最小长度
• max-length - [整数] 值的最大长度
• regex - [字符串] 可接受值的正则表达式
• values - [数组] 包含所有可接受值的数组

指定的规则作为 Field 对象上的属性可用；例如 $f->required。字段一旦实例化就是不可变的。

提供了两种验证方法

• cast() - 将指定值转换为字段的类型
• validate() - 将指定值与字段的规则进行验证，并返回“清洁”值和遇到的任何验证错误。支持的错误在 spf\contracts\support\Error 中定义。

use spf\contracts\support\Error;
use spf\support\Field;

$f = new Field('id', Type::INTEGER, ['required' => true, 'min' => 0]);

$f->cast(false);		// returns 0
$f->cast('123fgh');		// returns 123
$f->cast('fghsdfs');	// returns 0

$f->validate(0);			// returns [0, Error::REQUIRED]
$f->validate(false);		// returns [false, Error::REQUIRED]
$f->validate('123fgh');		// returns [123, Error::NONE]
$f->validate('fghsdfs');	// returns ['fghsdfs', Error::TYPE]
$f->validate(-123);			// returns [-123, Error::MIN]

字段集

字段通过add()方法添加

use spf\support\Fieldset;

$f = new Fieldset();
$f->add($name, $type = Type::TEXT, $rules = []);

可以通过调用validate()方法并传入一个字段名和值数组，一次性验证Fieldset中的所有字段。返回值是一个包含两个元素的数组，第一个元素是按字段名索引的'清洁'值数组；第二个元素是按字段名索引的验证错误数组。

use spf\contracts\support\Error;
use spf\support\Fieldset;

$f = new Fieldset();

$f->add('id', Type::INTEGER);
$f->add('email', Type::EMAIL, ['required' => true, 'unique' => true]);


$f->validate([
	'id'    => '123',
	'email' => 'bar',
]);
/*
returns:
[
	[
		'id'    => 123,
		'email' => 'bar',
],
	[
		'id'    => Error::NONE,
		'email' => Error::EMAIL,
	],
]

Twig 扩展

Twig扩展为Twig环境提供了额外的实用功能。

测试（是）

• numeric - 判断变量是否包含数值
• integer - 判断变量是否包含整数值
• string - 判断变量是否为字符串
• array - 判断变量是否为数组
• object - 判断变量是否为对象

过滤器

• md5 - 生成值的md5散列
• sha1 - 生成值的sha1散列
• truncate - 截断值到指定长度
• sum - 通过array_sum()生成数组的和
• shuffle - 通过shuffle()打乱数组

函数

• ceil - 通过ceil()将值向上舍入到下一个最高整数
• floor - 通过floor()将值向下舍入到下一个最低整数

如果检测到spf-core包，大多数辅助方法都包含为没有相应原生功能的过滤器或函数。

验证

spf\support\Validator类包含用于验证值的静态方法。尽可能使用PHP的内置filter_var()函数以及适当的标志进行验证。验证函数将返回正确类型的有效值，或返回正确类型的空值。

• isEmpty($v, $type = Type::TEXT)
• validateText($v)
• validateInteger($v)
• validateFloat($v)
• validateBoolean($v)
• validateTimestamp($v)
• validateDateTime($v, $format = 'Y-m-d H:i:s')
• validateDate($v)
• validateTime($v)
• validateYear($v, $min = 1900, $max = 2155)
• validateEmail($v)
• validateIP($v)
• validateURL($v)
• validateJSON($v)
• validateObject($v, $class, $nullable = false)