starburst / utils
Installs: 2 409
Dependents: 1
Suggesters: 0
Security: 0
Stars: 0
Watchers: 1
Forks: 0
Open Issues: 0
Requires
- php: ^8.0
- ext-intl: *
- ext-mbstring: *
Suggests
- sunkan/dictus: Needed to use date resolver and date utility class
README
Package that contain some common helper classes
Requirements
PHP 8.0 or higher.
Installation
composer require starburst/utils
Usage
Json
The Starburst\Utils\Json
class provides static methods for encoding and
decoding Json in PHP.
Below, you'll find detailed documentation on how to use it:
encode(mixed $value, bool $encodeNull = true): ?string
This method accepts a variable of any type and converts it to a JSON string.
Parameters:
$value (mixed)
: The value you want to encode to JSON.$encodeNull (bool)
: If we should encodenull
asstring
or not
Returns:
- JSON Encoded string. If
$encodeNull
is false this can also return null
Usage:
$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
This method accepts a JSON string and decodes it to the corresponding PHP value or array.
Parameters:
$value (string)
: The JSON string you want to decode.
Returns:
- The PHP value that was encoded in the JSON string. If json is an object it's returned as an assoc array
Usage:
$phpValue = \Starburst\Utils\Json::decode($jsonString);
decodeArray(string $value, bool $allowNull = false): ?array
This method decodes a JSON string to an associative array in PHP.
The method throws a JsonException if the decoded value is not an array.
Parameters:
$value (string)
: The JSON string you want to decode to an array.$allowNull (bool)
: Allow encoded null values to return null without exception
Returns:
- The associative array that was encoded in the JSON string.
Usage:
$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
This method decodes a JSON string to a numeric array (list) in PHP.
The method throws a JsonException if the decoded value is not a list.
Parameters:
$value (string)
: The JSON string you want to decode to an array.$allowNull (bool)
: Allow encoded null values to return null without exception
Returns:
- The numeric array (list) that was encoded in the JSON string.
Usage:
$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;
Validators
The Starburst\Utils\Validators
class provides static methods to validate different types of input.
isUnicode(mixed $value): bool
This function checks if the provided value is a valid UTF-8 string.
Parameters:
$value (mixed)
: The value you want to check.
Returns:
- True or false. It will always return false for none string types
Usage:
$isValid = \Starburst\Utils\Validators::isUnicode($value);
isKennitala(mixed $value): bool
This function checks if the provided value is a valid kennitala.
Parameters:
$value (mixed)
: The value you want to check.
Returns:
- True or false
Usage:
$isValid = \Starburst\Utils\Validators::isKennitala($value);
isEmail(string $value): bool
This function checks if the provided string is a valid email address. Note that it only checks the syntax of the email and not if the email domain actually exists.
Parameters:
$value (string)
: The value you want to check.
Returns:
- True or false
Usage:
$isValid = \Starburst\Utils\Validators::isEmail($value);
GetArrayCopy
Trait that helps convert an object into an assoc array.
It supports value resolvers that can be used to format some properties in a custom way.
Example
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, ];
Configure custom value resolvers
#[\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' ];