Add ToArrayOfStrings parameter attribute (#94)

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## 1.3.1 under development
 
+- New #94: Add `ToArrayOfStrings` parameter attribute (@vjik)
 - Enh #93: Add backed enumeration support to `Collection` (@vjik) 
 
 ## 1.3.0 August 07, 2024

docs/guide/en/typecasting.md

@@ -212,3 +212,28 @@ $category = $hydrator->create(
  ],
 );
 ```
+
+### `ToArrayOfStrings`
+
+Use `ToArrayOfStrings` attribute to cast a value to an array of strings:
+
+```php
+use Yiisoft\Hydrator\Attribute\Parameter\ToArrayOfStrings;
+
+final class Post
+{
+ #[ToArrayOfStrings(separator: ',')]
+ public array $tags = []; 
+}
+```
+
+Value of `tags` will be cast to an array of strings by splitting it by `,`. For example, string `news,city,hot` will be
+converted to array `['news', 'city', 'hot']`.
+
+Attribute parameters:
+
+- `trim` — trim each string of array (boolean, default `false`);
+- `removeEmpty` — remove empty strings from array (boolean, default `false`);
+- `splitResolvedValue` — split resolved value by separator (boolean, default `true`);
+- `separator` — the boundary string (default, `\R`), it's a part of regular expression so should be taken into account 
+ or properly escaped with `preg_quote()`.

src/Attribute/Parameter/ToArrayOfStrings.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Hydrator\Attribute\Parameter;
+
+use Attribute;
+
+/**
+ * Casts the resolved value to array of strings.
+ */
+#[Attribute(Attribute::TARGET_PROPERTY | Attribute::TARGET_PARAMETER | Attribute::IS_REPEATABLE)]
+final class ToArrayOfStrings implements ParameterAttributeInterface
+{
+ /**
+ * @param bool $trim Trim each string of array.
+ * @param bool $removeEmpty Remove empty strings from array.
+ * @param bool $splitResolvedValue Split non-array resolved value to array of strings by {@see $separator}.
+ * @param string $separator The boundary string. It is a part of regular expression
+ * so should be taken into account or properly escaped with {@see preg_quote()}.
+ */
+ public function __construct(
+ public readonly bool $trim = false,
+ public readonly bool $removeEmpty = false,
+ public readonly bool $splitResolvedValue = true,
+ public readonly string $separator = '\R',
+ ) {
+ }
+
+ public function getResolver(): string
+ {
+ return ToArrayOfStringsResolver::class;
+ }
+}

src/Attribute/Parameter/ToArrayOfStringsResolver.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Hydrator\Attribute\Parameter;
+
+use Stringable;
+use Traversable;
+use Yiisoft\Hydrator\AttributeHandling\Exception\UnexpectedAttributeException;
+use Yiisoft\Hydrator\AttributeHandling\ParameterAttributeResolveContext;
+use Yiisoft\Hydrator\Result;
+
+final class ToArrayOfStringsResolver implements ParameterAttributeResolverInterface
+{
+ public function getParameterValue(
+ ParameterAttributeInterface $attribute,
+ ParameterAttributeResolveContext $context
+ ): Result {
+ if (!$attribute instanceof ToArrayOfStrings) {
+ throw new UnexpectedAttributeException(ToArrayOfStrings::class, $attribute);
+ }
+
+ if (!$context->isResolved()) {
+ return Result::fail();
+ }
+
+ $resolvedValue = $context->getResolvedValue();
+ if (is_iterable($resolvedValue)) {
+ $array = array_map(
+ $this->castValueToString(...),
+ $resolvedValue instanceof Traversable ? iterator_to_array($resolvedValue) : $resolvedValue
+ );
+ } else {
+ $value = $this->castValueToString($resolvedValue);
+ $array = $attribute->splitResolvedValue
+ ? preg_split('~' . $attribute->separator . '~u', $value)
+ : [$value];
+ }
+
+ if ($attribute->trim) {
+ $array = array_map(trim(...), $array);
+ }
+
+ if ($attribute->removeEmpty) {
+ $array = array_filter(
+ $array,
+ static fn(string $value): bool => $value !== '',
+ );
+ }
+
+ return Result::success($array);
+ }
+
+ private function castValueToString(mixed $value): string
+ {
+ return is_scalar($value) || $value instanceof Stringable ? (string) $value : '';
+ }
+}

tests/Attribute/Parameter/ToArrayOfStringsTest.php

@@ -0,0 +1,200 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Hydrator\Tests\Attribute\Parameter;
+
+use ArrayObject;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\TestCase;
+use stdClass;
+use Yiisoft\Hydrator\Attribute\Parameter\ToArrayOfStrings;
+use Yiisoft\Hydrator\Attribute\Parameter\ToArrayOfStringsResolver;
+use Yiisoft\Hydrator\AttributeHandling\Exception\UnexpectedAttributeException;
+use Yiisoft\Hydrator\AttributeHandling\ResolverFactory\ContainerAttributeResolverFactory;
+use Yiisoft\Hydrator\Hydrator;
+use Yiisoft\Hydrator\Tests\Support\Attribute\Counter;
+use Yiisoft\Hydrator\Tests\Support\Attribute\CounterResolver;
+use Yiisoft\Hydrator\Tests\Support\Classes\CounterClass;
+use Yiisoft\Test\Support\Container\SimpleContainer;
+
+final class ToArrayOfStringsTest extends TestCase
+{
+ public static function dataBase(): iterable
+ {
+ yield [
+ [],
+ [],
+ new class () {
+ #[ToArrayOfStrings]
+ public ?array $value = null;
+ },
+ ];
+ yield [
+ [''],
+ '',
+ new class () {
+ #[ToArrayOfStrings]
+ public ?array $value = null;
+ },
+ ];
+ yield [
+ [''],
+ new stdClass(),
+ new class () {
+ #[ToArrayOfStrings]
+ public ?array $value = null;
+ },
+ ];
+ yield [
+ ['hello'],
+ 'hello',
+ new class () {
+ #[ToArrayOfStrings]
+ public ?array $value = null;
+ },
+ ];
+ yield [
+ ['hello'],
+ ['hello'],
+ new class () {
+ #[ToArrayOfStrings]
+ public ?array $value = null;
+ },
+ ];
+ yield [
+ ['hello '],
+ 'hello ',
+ new class () {
+ #[ToArrayOfStrings]
+ public ?array $value = null;
+ },
+ ];
+ yield [
+ ['hello'],
+ 'hello ',
+ new class () {
+ #[ToArrayOfStrings(trim: true)]
+ public ?array $value = null;
+ },
+ ];
+ yield [
+ ['hello', 'world'],
+ "hello\nworld",
+ new class () {
+ #[ToArrayOfStrings]
+ public ?array $value = null;
+ },
+ ];
+ yield [
+ ['hello', 'world'],
+ ['hello', 'world'],
+ new class () {
+ #[ToArrayOfStrings]
+ public ?array $value = null;
+ },
+ ];
+ yield [
+ ['hello', '42', '1', '2.4'],
+ ['hello', 42, true, 2.4],
+ new class () {
+ #[ToArrayOfStrings]
+ public ?array $value = null;
+ },
+ ];
+ yield [
+ ['hello', 'world'],
+ new ArrayObject(['hello', 'world']),
+ new class () {
+ #[ToArrayOfStrings]
+ public ?array $value = null;
+ },
+ ];
+ yield [
+ ["hello\nworld"],
+ "hello\nworld",
+ new class () {
+ #[ToArrayOfStrings(splitResolvedValue: false)]
+ public ?array $value = null;
+ },
+ ];
+ yield [
+ ['hello', '', 'world'],
+ "hello\n\nworld",
+ new class () {
+ #[ToArrayOfStrings]
+ public ?array $value = null;
+ },
+ ];
+ yield [
+ ['hello', 2 => 'world'],
+ "hello\n\nworld",
+ new class () {
+ #[ToArrayOfStrings(removeEmpty: true)]
+ public ?array $value = null;
+ },
+ ];
+ yield [
+ ['hello', '', ' world', ' good '],
+ "hello\n\n world\n good ",
+ new class () {
+ #[ToArrayOfStrings]
+ public ?array $value = null;
+ },
+ ];
+ yield [
+ ['hello', 2 => 'world', 3 => 'good'],
+ "hello\n\n world\n good ",
+ new class () {
+ #[ToArrayOfStrings(trim: true, removeEmpty: true)]
+ public ?array $value = null;
+ },
+ ];
+ yield [
+ ['hello', 'world', 'good'],
+ 'hello,world,good',
+ new class () {
+ #[ToArrayOfStrings(separator: ',')]
+ public ?array $value = null;
+ },
+ ];
+ }
+
+ #[DataProvider('dataBase')]
+ public function testBase(mixed $expectedValue, mixed $value, object $object)
+ {
+ (new Hydrator())->hydrate($object, ['value' => $value]);
+ $this->assertSame($expectedValue, $object->value);
+ }
+
+ public function testNotResolved(): void
+ {
+ $object = new class () {
+ #[ToArrayOfStrings]
+ public ?array $value = null;
+ };
+
+ (new Hydrator())->hydrate($object);
+
+ $this->assertNull($object->value);
+ }
+
+ public function testUnexpectedAttributeException(): void
+ {
+ $hydrator = new Hydrator(
+ attributeResolverFactory: new ContainerAttributeResolverFactory(
+ new SimpleContainer([
+ CounterResolver::class => new ToArrayOfStringsResolver(),
+ ]),
+ ),
+ );
+
+ $object = new CounterClass();
+
+ $this->expectException(UnexpectedAttributeException::class);
+ $this->expectExceptionMessage(
+ 'Expected "' . ToArrayOfStrings::class . '", but "' . Counter::class . '" given.'
+ );
+ $hydrator->hydrate($object);
+ }
+}