Improved XML support with own GetValue method wrappings

Author: pionl

docs/content/en/index.md

@@ -309,6 +309,55 @@ missing.
 $value = $data->getRequiredArrayGetter('key');
 ```
 
+### Get SimpleXMLElement
+
+Return SimpleXMLElement for given key. Uses `xml` transformer strategy.
+
+```php
+$xml = $data->getNullableXML('child');
+```
+
+### GetValue with XMLData
+
+> Throws always `NotXMLException` exception if value is not a SimpleXMLElement. XML transformer strategy is applied.
+
+Get always `GetValue` instance even if provided data is missing or if null.
+
+```php
+$value = $data->getXMLGetter('key');
+```
+
+Try to get nullable array from data and wrap it in `GetValue` instance.
+
+```php
+$value = $data->getNullableXMLGetter('key');
+```
+
+Try to get non-empty array from data and wrap it in `GetValue` instance. Throws `ArrayIsEmptyException` exception if
+missing.
+
+```php
+$value = $data->getRequiredXMLGetter('key');
+```
+
+### GetValue XML attributes
+
+> Throws always `NotXMLException` exception if value is not a SimpleXMLElement. XML transformer strategy is applied.
+
+Wraps XML element attributes in GetValue instance (even if attributes are not set in element).
+
+Key contains `@attributes` like `title.@attributes.test`.
+
+```php
+ // Access attributes from root data
+$rootAttributes = $data->getXMLAttributesGetter();
+$rootAttributes->getString('attributeName');
+
+ // Access attributes from given element
+$attributes = $data->getXMLAttributesGetter('node');
+$attributes->getString('attributeName');
+```
+
 ## Exceptions
 
 > All exceptions receive full key that was used for getting data. You can receive it by using `$exception->getKey()`

docs/content/en/transformers.md

@@ -221,12 +221,32 @@ $transformer = new ArrayItemTransformer(function (mixed $value, string $key): ?a
 $values = $data->getArray('names', transformers: [$transformer]);
 // Result: [['Marco', 'Polo'], ['Way', 'Point'], null]
 ```
+### GetterTransformer (since v0.6.0)
+
+Transforms an **array/xml value** in a closure that receives wrapped GetValue instance.
+
+```php
+use Wrkflow\GetValue\GetValue;
+use Wrkflow\GetValue\DataHolders\ArrayData;
+use Wrkflow\GetValue\Transformers\GetterTransformer;
+
+$data = new GetValue(new ArrayData([
+   'person' => ['name' => 'Marco', 'surname' => 'Polo'],
+]));
+
+$transformer = new GetterTransformer(function (GetValue $value, string $key): string {
+   return $value->getRequiredString('name') . ' '.$value->getRequiredString('surname');
+}, beforeValidation: true);
+
+$value = $data->getString('person', transformers: [$transformer]);
+// Result: 'Marco Polo'
+```
 
 ### ArrayItemGetterTransformer
 
 > Can be used only with get\*Array\* methods. Throws NotAnArrayException if array value is not an array.
 
-Transforms an **array that contains array values** in a closure that receives wrapped array in GetValue.
+Transforms an **array/xml that contains array/xml values** in a closure that receives wrapped GetValue instance.
 
 ```php
 use Wrkflow\GetValue\GetValue;

src/Actions/GetValidatedValueAction.php

@@ -6,6 +6,7 @@
 
 use Wrkflow\GetValue\Contracts\RuleContract;
 use Wrkflow\GetValue\Contracts\TransformerContract;
+use Wrkflow\GetValue\Enums\ValueType;
 use Wrkflow\GetValue\GetValue;
 
 class GetValidatedValueAction
@@ -19,10 +20,15 @@ public function __construct(
      * @param array<RuleContract>        $rules
      * @param array<TransformerContract> $transforms
      */
-    public function execute(GetValue $getValue, string|array $key, array $rules, array $transforms): mixed
-    {
-        $value = $getValue->data->getValue($key);
+    public function execute(
+        GetValue $getValue,
+        ValueType $valueType,
+        string|array $key,
+        array $rules,
+        array $transforms,
+    ): mixed {
         $fullKey = $getValue->data->getKey($key);
+        $value = $getValue->data->getValue($key, $valueType);
 
         $afterValidationTransforms = [];
 

src/Builders/ExceptionBuilder.php

@@ -8,7 +8,8 @@
 use Wrkflow\GetValue\Contracts\ExceptionBuilderContract;
 use Wrkflow\GetValue\Exceptions\ArrayIsEmptyException;
 use Wrkflow\GetValue\Exceptions\MissingValueForKeyException;
-use Wrkflow\GetValue\Exceptions\NotAnArrayException;
+use Wrkflow\GetValue\Exceptions\NotSupportedDataException;
+use Wrkflow\GetValue\Exceptions\NotXMLException;
 use Wrkflow\GetValue\Exceptions\ValidationFailedException;
 
 class ExceptionBuilder implements ExceptionBuilderContract
@@ -25,7 +26,7 @@ public function arrayIsEmpty(string $key): Exception
 
     public function notAnArray(string $key): Exception
     {
-        return new NotAnArrayException($key);
+        return new NotSupportedDataException($key);
     }
 
     public function validationFailed(string $key, string $ruleClassName): Exception
@@ -35,4 +36,9 @@ public function validationFailed(string $key, string $ruleClassName): Exception
 
         return new ValidationFailedException($key, $shortClassName . ' failed');
     }
+
+    public function notXML(string $key): Exception
+    {
+        return new NotXMLException($key);
+    }
 }

src/Contracts/ExceptionBuilderContract.php

@@ -18,4 +18,6 @@ public function notAnArray(string $key): Exception;
      * @param class-string<RuleContract> $ruleClassName
      */
     public function validationFailed(string $key, string $ruleClassName): Exception;
+
+    public function notXML(string $key): Exception;
 }

src/Contracts/TransformerStrategy.php

@@ -35,4 +35,9 @@ public function float(): array;
      * @return array<TransformerContract>
      */
     public function array(): array;
+
+    /**
+     * @return array<TransformerContract>
+     */
+    public function xml(): array;
 }

src/DataHolders/AbstractData.php

@@ -4,13 +4,15 @@
 
 namespace Wrkflow\GetValue\DataHolders;
 
+use Wrkflow\GetValue\Enums\ValueType;
+
 abstract class AbstractData
 {
     public function __construct(private readonly string $parentKey = '')
     {
     }
 
-    abstract public function getValue(string|array $key): mixed;
+    abstract public function getValue(string|array $key, ValueType $expectedValueType): mixed;
 
     abstract public function get(): mixed;
 

src/DataHolders/ArrayData.php

@@ -4,6 +4,8 @@
 
 namespace Wrkflow\GetValue\DataHolders;
 
+use Wrkflow\GetValue\Enums\ValueType;
+
 class ArrayData extends AbstractData
 {
     public function __construct(
@@ -13,7 +15,7 @@ public function __construct(
         parent::__construct($parentKey);
     }
 
-    public function getValue(string|array $key): mixed
+    public function getValue(string|array $key, ValueType $expectedValueType): mixed
     {
         if (is_string($key) && str_contains($key, '.')) {
             $key = explode('.', $key);

src/DataHolders/XMLAttributesData.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Wrkflow\GetValue\DataHolders;
+
+use SimpleXMLElement;
+use Wrkflow\GetValue\Enums\ValueType;
+use Wrkflow\GetValue\Exceptions\AttributesDotNotationException;
+
+class XMLAttributesData extends AbstractData
+{
+    public function __construct(
+        private readonly SimpleXMLElement $data,
+        string $parentKey = ''
+    ) {
+        parent::__construct($parentKey);
+    }
+
+    public function getValue(string|array $key, ValueType $expectedValueType): ?string
+    {
+        if (is_array($key)) {
+            throw new AttributesDotNotationException(implode('.', $key));
+        } elseif (str_contains($key, '.')) {
+            throw new AttributesDotNotationException($key);
+        }
+
+        $value = $this->data->{$key};
+
+        if ($value instanceof SimpleXMLElement === false) {
+            return null;
+        }
+
+        return (string) $value;
+    }
+
+    public function get(): SimpleXMLElement
+    {
+        return $this->data;
+    }
+}

src/DataHolders/XMLData.php

@@ -5,6 +5,7 @@
 namespace Wrkflow\GetValue\DataHolders;
 
 use SimpleXMLElement;
+use Wrkflow\GetValue\Enums\ValueType;
 
 class XMLData extends AbstractData
 {
@@ -15,18 +16,14 @@ public function __construct(
         parent::__construct($parentKey);
     }
 
-    public function getValue(string|array $key): ?string
+    public function getValue(string|array $key, ValueType $expectedValueType): SimpleXMLElement|array|string|null
     {
         if (is_string($key) && str_contains($key, '.')) {
             $key = explode('.', $key);
         } elseif (is_string($key)) {
             $value = $this->data->{$key};
 
-            if ($value->count() !== 0) {
-                return (string) $value;
-            }
-
-            return null;
+            return $this->normalizeValue($expectedValueType, $value);
         }
 
         $element = $this->data;
@@ -41,11 +38,36 @@ public function getValue(string|array $key): ?string
             $element = $value;
         }
 
-        return (string) $element;
+        return $this->normalizeValue($expectedValueType, $element);
     }
 
     public function get(): SimpleXMLElement
     {
         return $this->data;
     }
+
+    protected function normalizeValue(ValueType $valueType, SimpleXMLElement $value): string|array|null|SimpleXMLElement
+    {
+        if ($valueType === ValueType::XML) {
+            if ($value->count() === 0) {
+                return null;
+            }
+
+            return $value;
+        } elseif ($valueType === ValueType::XMLAttributes) {
+            return $value;
+        } elseif ($valueType === ValueType::Array) {
+            $return = [];
+
+            foreach ($value as $val) {
+                $return[] = $val;
+            }
+
+            return $return;
+        } elseif ($value->count() !== 0) {
+            return (string) $value;
+        }
+
+        return null;
+    }
 }