README

包含一些常用辅助类的包

要求

PHP 8.0 或更高版本。

安装

composer require starburst/utils

使用

Json

Starburst\Utils\Json 类提供了在 PHP 中编码和解码 Json 的静态方法。下面，您将找到如何使用它的详细文档

encode(mixed $value, bool $encodeNull = true): ?string

此方法接受任何类型的变量并将其转换为 JSON 字符串。

参数

• $value (mixed): 要编码为 JSON 的值。
• $encodeNull (bool): 是否应将 null 编码为 string 或不编码

返回

• JSON 编码字符串。如果 $encodeNull 为 false，则也可以返回 null

使用

$jsonString = \Starburst\Utils\Json::encode(["name" => "John Doe", "age" => 30]);

// behaviour is using encodeNull flag 
\Starburst\Utils\Json::encode(null, encodeNull: true) === 'null';
\Starburst\Utils\Json::encode(null, encodeNull: false) === null;

decode(string $value): mixed

此方法接受一个 JSON 字符串并将其解码为相应的 PHP 值或数组。

参数

• $value (string): 要解码的 JSON 字符串。

返回

• 在 JSON 字符串中编码的 PHP 值。如果 json 是对象，则作为关联数组返回

使用

$phpValue = \Starburst\Utils\Json::decode($jsonString);

decodeArray(string $value, bool $allowNull = false): ?array

此方法将 JSON 字符串解码为 PHP 中的关联数组。

如果解码的值不是数组，则方法抛出 JsonException。

参数

• $value (string): 要解码为数组的 JSON 字符串。
• $allowNull (bool): 允许编码的 null 值返回 null 而不抛出异常

返回

• 在 JSON 字符串中编码的关联数组。

使用

$associativeArray = \Starburst\Utils\Json::decodeArray($jsonString);

// behaviour is using allowNull flag 
\Starburst\Utils\Json::decodeArray('null', allowNull: false); // throw exception
\Starburst\Utils\Json::decodeArray('null', allowNull: true) === null;

decodeList(string $value, bool $allowNull = false): ?array

此方法将 JSON 字符串解码为 PHP 中的数字数组（列表）。

如果解码的值不是列表，则方法抛出 JsonException。

参数

• $value (string): 要解码为数组的 JSON 字符串。
• $allowNull (bool): 允许编码的 null 值返回 null 而不抛出异常

返回

• 在 JSON 字符串中编码的数字数组（列表）。

使用

$list = \Starburst\Utils\Json::decodeList($jsonString);

// behaviour is using allowNull flag 
\Starburst\Utils\Json::decodeList('null', allowNull: false); // throw exception
\Starburst\Utils\Json::decodeList('null', allowNull: true) === null;

验证器

Starburst\Utils\Validators 类提供了静态方法来验证不同类型的输入。

isUnicode(mixed $value): bool

此函数检查提供的值是否是有效的 UTF-8 字符串。

参数

• $value (mixed): 要检查的值。

返回

• True 或 false。对于非字符串类型，它总是返回 false

使用

$isValid = \Starburst\Utils\Validators::isUnicode($value);

isKennitala(mixed $value): bool

此函数检查提供的值是否是有效的 kennitala。

参数

• $value (mixed): 要检查的值。

返回

• True 或 false

使用

$isValid = \Starburst\Utils\Validators::isKennitala($value);

isEmail(string $value): bool

此函数检查提供的字符串是否是有效的电子邮件地址。请注意，它只检查电子邮件地址的语法，并不检查电子邮件域名是否实际存在。

参数

• $value (string): 要检查的值。

返回

• True 或 false

使用

$isValid = \Starburst\Utils\Validators::isEmail($value);

GetArrayCopy

帮助将对象转换为关联数组的特性。

它支持值解析器，可用于以自定义方式格式化某些属性。

示例

class TestObject
{
	use \Starburst\Utils\Traits\GetArrayCopyTrait;
	
	public function __construct(
		public int $id,
		#[\Starburst\Utils\Attributes\DateFormat('Y-m-d')]
		public \DateTimeImmutable $startDate,
		public \DateTimeImmutable $createdOn,
		#[\Starburst\Utils\Attributes\HiddenProperty]
		public string $internalField,
		#[\Starburst\Utils\Attributes\CustomName('parent')]
		public ?TestObject $parentObject = null,
	) {}
}

$obj = new TestObject(
	1,
	new DateTimeImmutable('2024-05-24 08:00:00'),
	new DateTimeImmutable('2024-05-20 12:23:01'),
	'internalValue'
);

$obj->getArrayCopy() === [
	'id' => 1,
	'startOn' => '2024-05-24',
	'createdOn' => '2024-05-20 12:23:01',
	'parent' => null,
];

配置自定义值解析器

#[\Attribute(\Attribute::TARGET_PROPERTY)]
class CustomAttribute {}
class CustomResolver implements \Starburst\Utils\ValueResolvers\ValueResolver
{
	/**
	 * @param \WeakMap<object, mixed> $tracker
	 */
	public function resolve(mixed $value, \WeakMap $tracker, ?\ReflectionProperty $reflectionProperty = null): mixed
	{
		$attrs = $reflectionProperty?->getAttributes(CustomAttribute::class);
		if (!$attrs) {
			return $value;
		}
		if ($value instanceof \DateTimeInterface) {
			return $value->format('j.m k\l. H:i');
		}
		
		return 'Random string';
	}

}

$collection = new \Starburst\Utils\ValueResolvers\ResolverCollection(
	new \Starburst\Utils\Tests\Stubs\CustomValueResolver(),
);

$obj = new class (1) {
	use \Starburst\Utils\Traits\GetArrayCopyTrait;
	
	public function __construct(
		#[CustomAttribute]
		private mixed $value,
	) {}
};

$obj->getArrayCopy() === [
	'value' => 'Random string'
];

$obj = new class (new \DateTimeImmutable('2024-05-24 08:12:42')) {
	use \Starburst\Utils\Traits\GetArrayCopyTrait;
	
	public function __construct(
		#[CustomAttribute]
		private mixed $value,
	) {}
};

$obj->getArrayCopy() === [
	'value' => '24.05 kl. 08:12:42'
];