Add dot notation support

Author: pionl

README.md

@@ -10,20 +10,12 @@ Get typed (strict mode) values from an Array / XML with basic validation.
 composer require wrkflow/php-get-typed-value
 ```
 
-I've created this project as part of my mission to create `work flow` tools / libraries to make my (and yours) **dev
-life easier and more enjoyable**.
-
-Want more tools or want to help? Check [wrk-flow.com](https://wrk-flow.com) or [CONTRIBUTE](CONTRIBUTION.md) (I need
-help with the documentation, new features, tests).
-
 ## Main features
 
-- 🚀 Retrieve values from Array (JSON) / XML with correct return type
-- 🏆 Makes PHPStan / IDE happy due the return types
-- 🤹‍ Validation: Ensures that desired value is in correct type (without additional loop validation. Validation is always on
-  while calling get* method).
-- 🛠 Transformers: Ensures that values are in expected type (ensures that string is trimmed and empty string converted to
-  null, accepts bool as string, can be changed.)
+- 🚀 Retrieve values from Array (JSON) / XML with correct return type with **dot notation** support.
+- 🏆 **Makes PHPStan / IDE** happy due the type strict return types.
+- 🤹‍ **Validation:** Ensures that desired value is in correct type (without additional loop validation).
+- 🛠 **Transformers:** Ensures that values are in expected type
 
 ```php
 $data = new \Wrkflow\GetValue\GetValue(new \Wrkflow\GetValue\DataHolders\ArrayData([
@@ -52,3 +44,12 @@ foreach ($items as $item) {
 ## Documentation
 
 Documentation is hosted on [GitHub Pages](https://php-get-typed-value.wrk-flow.com).
+
+## Comment
+
+I've created this project as part of my mission to create `work flow` tools / libraries to make my (and yours) **dev
+life easier and more enjoyable**.
+
+Want more tools or want to help? Check [wrk-flow.com](https://wrk-flow.com) or [CONTRIBUTE](CONTRIBUTION.md). You can
+help me improve the documentation, add new tests and features. Are you junior developer? Don't be scared, get in touch
+and I will guide you in your first contribution.

docs/content/en/customization/custom-data-holder.md

@@ -7,7 +7,7 @@ position: 11
 
 1. Create an object in DataHolders namespace
 2. Extend `\Wrkflow\GetValue\DataHolders`
-3. Implement `getValue(string $key): mixed` that should return required value (make it nullable).
+3. Implement `getValue(string|array $key): mixed` that should return required value (make it nullable).
 4. Implement `public function get(): array` that should return whole data when you need it.
 
 ```php
@@ -19,18 +19,18 @@ namespace Wrkflow\GetValue\DataHolders;
 
 class ArrayData extends AbstractData
 {
-    public function __construct(private readonly array $array)
+    public function __construct(private readonly array $flatArray)
     {
     }
 
-    public function getValue(string $key): mixed
+    public function getValue(string|array $key): mixed
     {
-        return $this->array[$key] ?? null;
+        return $this->flatArray[implode('.', $key)] ?? null;
     }
 
     public function get(): array
     {
-        return $this->array;
+        return $this->flatArray;
     }
 }
 

docs/content/en/customization/custom-exceptions.md

@@ -14,25 +14,25 @@ class CustomExceptionBuilder extends
 {
     public function __construct(private readonly array $customLogContext) {}
 
-    public function missingValue(string $key): Exception
+    public function missingValue(string|array $key): Exception
     {
         return new MissingValueForKeyException($key, $this->customLogContext);
     }
 
-    public function arrayIsEmpty(string $key): Exception
+    public function arrayIsEmpty(string|array $key): Exception
     {
         return new ArrayIsEmptyException($key, $this->customLogContext);
     }
 
-    public function notAnArray(string $key): Exception
+    public function notAnArray(string|array $key): Exception
     {
         return new NotAnArrayException($key, $this->customLogContext);
     }
 
     /**
      * @param class-string<RuleContract> $ruleClassName
      */
-    public function validationFailed(string $key, string $ruleClassName): Exception;
+    public function validationFailed(string|array $key, string $ruleClassName): Exception;
     {
         return new ValidationFailedException($key, $this->customLogContext);
     }

docs/content/en/index.md

@@ -10,13 +10,10 @@ position: 1
 
 ## Main features
 
-- 🚀 Retrieve values from Array (JSON) / XML with correct return type
-- 🏆 Makes PHPStan / IDE happy due the return types
-- 🤹‍ Validation: Ensures that desired value is in correct type (without additional loop validation. Validation is always
-  on
-  while calling get* method).
-- 🛠 Transformers: Ensures that values are in expected type (ensures that string is trimmed and empty string converted to
-  null, accepts bool as string, can be changed.)
+- 🚀 Retrieve values from Array (JSON) / XML with correct return type with **safe dot notation** support.
+- 🏆 **Makes PHPStan / IDE** happy due the type strict return types.
+- 🤹‍ **Validation:** Ensures that desired value is in correct type (without additional loop validation).
+- 🛠 **Transformers:** Ensures that values are in expected type
 
 ## Installation
 
@@ -54,6 +51,42 @@ $simpleXMLElement = new SimpleXMLElement('<root><title>test</title><test attribu
 $data = new \Wrkflow\GetValue\GetValue(new \Wrkflow\GetValue\DataHolders\XMLData($simpleXMLElement));
 ```
 
+## Dot notation
+
+Dot notation is implemented in safe manner (may differ from Laravel and other implementations when edge cases occurs).
+
+String that is separated by '.' will always be converted to path of exact path keys. If you '.' in your array key / XML
+node name
+then you need to use array as a key. Examples below:
+
+```php
+$getValue = new \Wrkflow\GetValue\GetValue(new \Wrkflow\GetValue\DataHolders\ArrayData([
+    'get.key' => 'test',
+    'get' => [
+        'key' => 'child'
+    ],
+    'co.uk' => 'domain',
+]));
+$getValue->getString('get.key') // Returns: child
+$getValue->getString('co.uk') // Returns: null
+$getValue->getString(['get.key']) // Returns: test
+$getValue->getString(['co.uk']) // Returns: domain
+```
+
+This implementation ensures.
+
+You can instead of dot notation use array path:
+
+```php
+$getValue = new \Wrkflow\GetValue\GetValue(new \Wrkflow\GetValue\DataHolders\ArrayData([
+    'get' => [
+        'key' => 'child'
+    ],
+]));
+$getValue->getString(['get', 'key']) // Returns: test
+$getValue->getString(['get', 'no_value']) // Returns: null
+```
+
 ## Values
 
 > All values are validated within its type definition (int will be checked by IntegerRule, string by StringRule, etc).
@@ -73,7 +106,7 @@ Check [Validation documentation](/validation) for more.
 Get nullable int.
 
 ```php
-$value = $data->getInt('key', rules: [new \Wrkflow\GetValue\Rules\MinRule(0)]);
+$value = $data->getInt('key');
 ```
 
 Get required int value. Throws `MissingValueForKeyException` exception if missing.
@@ -100,7 +133,8 @@ $value = $data->getRequiredFloat('key');
 
 ### Bool
 
-> Throws `ValidationFailedException` if value is not bool (only on non-null values).
+> **In default strategy string [bool variants](https://php-get-typed-value.wrk-flow.com/transformers/#transformtobool)
+are converted to bool**. Throws `ValidationFailedException` if value is not bool (only on non-null values).
 
 Get nullable bool value.
 
@@ -116,8 +150,8 @@ $value = $data->getRequiredBool('key');
 
 ### String
 
-> Throws `ValidationFailedException` if value is not string (only on non-null values). In default strategy empty string
-> is treated as null.
+> **In default strategy string is trimmed and empty string is transformed to null**. Throws `ValidationFailedException`
+> if value is not string (only on non-null values).
 
 Get nullable string value.
 
@@ -209,3 +243,20 @@ missing.
 ```php
 $value = $data->getRequiredArrayGetter('key');
 ```
+
+## Exceptions
+
+> All exceptions receive full key that was used for getting data. You can receive it by using `$exception->getKey()`
+
+- ArrayIsEmptyException
+- MissingValueForKeyException
+- NotAnArrayException
+- ValidationFailedException
+
+## Notes
+
+- **Full key format**:
+    - Parent full key is prepended to the key with '.' separator (if the GetValue instance was constructed from parent
+      data).
+    - Array notation is converted to dot notation string.
+  

docs/content/en/transformers.md

@@ -176,6 +176,7 @@ You can create your own transformer by extending:
 
 - For array `Wrkflow\GetValue\Contracts\TransformerArrayContract`
 - Reset of values `Wrkflow\GetValue\Contracts\TransformerContract`
+- `$key` contains full path key from the root data. Array notation is converted to dot notation.
 
 Then implement `public function transform(mixed $value, string $key): mixed;`. Expect invalid value and make do not
 transform the value if it is invalid. Just return it.

src/Actions/GetValidatedValueAction.php

@@ -19,15 +19,16 @@ public function __construct(
      * @param array<RuleContract>        $rules
      * @param array<TransformerContract> $transforms
      */
-    public function execute(GetValue $getValue, string $key, array $rules, array $transforms): mixed
+    public function execute(GetValue $getValue, string|array $key, array $rules, array $transforms): mixed
     {
         $value = $getValue->data->getValue($key);
+        $fullKey = $getValue->data->getKey($key);
 
         $afterValidationTransforms = [];
 
         foreach ($transforms as $transform) {
-            if ($rules === [] || $transform->beforeValidation(value: $value, key: $key)) {
-                $value = $transform->transform(value: $value, key: $key, getValue: $getValue);
+            if ($rules === [] || $transform->beforeValidation(value: $value, key: $fullKey)) {
+                $value = $transform->transform(value: $value, key: $fullKey, getValue: $getValue);
             } else {
                 $afterValidationTransforms[] = $transform;
             }
@@ -42,10 +43,10 @@ public function execute(GetValue $getValue, string $key, array $rules, array $tr
             return null;
         }
 
-        $this->validateAction->execute(rules: $rules, value: $value, key: $key);
+        $this->validateAction->execute(rules: $rules, value: $value, key: $fullKey);
 
         foreach ($afterValidationTransforms as $transform) {
-            $value = $transform->transform(value: $value, key: $key, getValue: $getValue);
+            $value = $transform->transform(value: $value, key: $fullKey, getValue: $getValue);
         }
 
         return $value;

src/DataHolders/AbstractData.php

@@ -6,7 +6,29 @@
 
 abstract class AbstractData
 {
-    abstract public function getValue(string $key): mixed;
+    public function __construct(private readonly string $parentKey = '')
+    {
+    }
+
+    abstract public function getValue(string|array $key): mixed;
 
     abstract public function get(): mixed;
+
+    /**
+     * Builds full key path with parent key
+     */
+    public function getKey(string|array $key = ''): string
+    {
+        if ($key === '') {
+            return $this->parentKey;
+        }
+
+        $fullKey = is_array($key) ? implode('.', $key) : $key;
+
+        if ($this->parentKey === '') {
+            return $fullKey;
+        }
+
+        return $this->parentKey . '.' . $fullKey;
+    }
 }

src/DataHolders/ArrayData.php

@@ -6,13 +6,36 @@
 
 class ArrayData extends AbstractData
 {
-    public function __construct(private readonly array $array)
-    {
+    public function __construct(
+        private readonly array $array,
+        string $parentKey = ''
+    ) {
+        parent::__construct($parentKey);
     }
 
-    public function getValue(string $key): mixed
+    public function getValue(string|array $key): mixed
     {
-        return $this->array[$key] ?? null;
+        if (is_string($key) && str_contains($key, '.')) {
+            $key = explode('.', $key);
+        } elseif (is_string($key)) {
+            if (array_key_exists($key, $this->array)) {
+                return $this->array[$key];
+            }
+
+            return null;
+        }
+
+        $items = $this->array;
+
+        foreach ($key as $segment) {
+            if (is_array($items) === false || array_key_exists($segment, $items) === false) {
+                return null;
+            }
+
+            $items = $items[$segment];
+        }
+
+        return $items;
     }
 
     public function get(): array

src/DataHolders/XMLData.php

@@ -8,16 +8,40 @@
 
 class XMLData extends AbstractData
 {
-    public function __construct(private readonly SimpleXMLElement $data)
-    {
+    public function __construct(
+        private readonly SimpleXMLElement $data,
+        string $parentKey = ''
+    ) {
+        parent::__construct($parentKey);
     }
 
-    public function getValue(string $key): string
+    public function getValue(string|array $key): ?string
     {
-        $value = $this->data->{$key};
+        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;
+        }
+
+        $element = $this->data;
+
+        foreach ($key as $segment) {
+            $value = $element->{$segment};
+
+            if ($value->count() === 0) {
+                return null;
+            }
+
+            $element = $value;
+        }
 
-        // TODO figure out how to properly detect "child" exists instead of getting empty string...
-        return (string) $value;
+        return (string) $element;
     }
 
     public function get(): SimpleXMLElement

src/Exceptions/AbstractGetValueException.php

@@ -5,7 +5,21 @@
 namespace Wrkflow\GetValue\Exceptions;
 
 use Exception;
+use Throwable;
 
 abstract class AbstractGetValueException extends Exception
 {
+    public function __construct(
+        private readonly string $key,
+        string $message,
+        int $code = 400,
+        ?Throwable $previous = null
+    ) {
+        parent::__construct($message, $code, $previous);
+    }
+
+    public function getKey(): string
+    {
+        return $this->key;
+    }
 }