Merge pull request #118 from Planetbiru/feature/3.14.6

Feature/3.14.6

Author: kamshory

CHANGELOG.md

@@ -1034,140 +1034,40 @@ class UserValidator extends MagicObject
 This enhancement makes the validator generator more expressive and future-proof, especially when building layered architectures or generating documentation automatically.
 
 
-# MagicObject Version 3.14.4
-
-## What's Fixed
-
-### Bug Fix: `numberFormat*` Methods Accept Single Parameter
-
-In version 3.14.4, a bug has been fixed in the internal magic method handling for `numberFormat*` methods (such as `numberFormatPercent`, `numberFormatTotal`, etc.).
-
-#### Previous Behavior (Before 3.14.4)
-
-Calling a `numberFormat*` method with **only one argument** would trigger warnings:
-
-```php
-$data = new MagicObject();
-$data->setPercent(2.123456);
-echo $data->numberFormatPercent(2);
-```
-
-**Result:**
-
-```txt
-Warning: Undefined index 1
-Warning: Undefined index 2
-```
-
-This occurred because the internal handler expected three parameters and did not check for their existence properly.
-
-#### New Behavior (Since 3.14.4)
-
-These methods now safely accept **a single argument**, defaulting the missing parameters to reasonable values internally. The example above now works as expected and outputs:
-
-```txt
-2.12
-```
-
-#### Benefits:
-
--   Improved developer experience when formatting numbers.
-    
--   No need to always pass three parameters for simple formatting.
-    
--   Prevents PHP warnings in production environments.
-
-This bug fix enhances robustness and backward compatibility for developers using dynamic number formatting features in MagicObject.
 
 
 # MagicObject Version 3.14.5
 
-## What's Changed
-
-### New Feature: URL-Based Database Credential Parsing
-
-MagicObject now supports importing database credentials from a **datasource URL** string using the new method `PicoDatabaseCredentials::importFromUrl()`.
-
-This enhancement simplifies configuration and integration with environment-based or externalized connection settings (e.g., `DATABASE_URL`).
-
-#### Supported URL Format
-
-driver://username:password@host:port/database?schema=public&charset=utf8&timezone=Asia/Jakarta
+## Improvements
 
+### Enhancement: Flexible Nested Retrieval in `retrieve()` Method
 
-#### Example
+The `retrieve(...$keys)` method now supports multiple input formats for accessing nested object properties:
 
-```php
-$credentials = new PicoDatabaseCredentials();
-$credentials->importFromUrl(
-    'mysql://user:secret@localhost:3306/myapp?schema=public&charset=utf8mb4&timezone=Asia/Jakarta'
-);
-```
-
-#### Optional Override
-
-Username and password can be passed directly to override the values in the URL:
-
-```php
-$credentials->importFromUrl($url, 'realuser', 'realpass');
-```
-
-This is useful when credentials are stored separately from the connection string.
-
-#### Special Handling for SQLite
-
-When using sqlite:///path/to/database.db, the file path is automatically mapped to databaseFilePath instead of host/port.
-
-```php
-$url = 'sqlite:///path/to/database.db';
-$credentials->importFromUrl($url);
-```
-
-### Why It Matters
+- Dot notation: `$obj->retrieve('user.profile.name')`
+- Arrow notation: `$obj->retrieve('user->profile->name')`
+- Multiple arguments: `$obj->retrieve('user', 'profile', 'name')`
 
--   Makes deployment and configuration more flexible in containerized or cloud environments.
+Each key is automatically camelized for consistent property access.  
+If any key in the chain does not exist or returns `null`, the method will return `null`.
 
--   Simplifies integration with .env files, environment variables, or external secrets managers.
+This enhancement improves developer ergonomics when working with deeply nested data structures.
 
--   Supports both traditional and SQLite-based databases.
+### Validation: New `@TimeRange` Annotation
 
-### Backward Compatibility
-
-This update is fully backward-compatible and does not change any existing behavior unless the new method is used explicitly.
-
-
-### Bug Fix: Class-Typed Default Parameters Now Compatible with PHP 5
-
-Fixed a **fatal error** caused by the use of default parameters with a class type hint (`MagicObject`, `SecretObject`, `SetterGetter`, `MagicDto`) and non-null default values in the `validate()` method.
-
-#### Before (Problematic in PHP 5):
-
-```php
-public function validate(
-    $parentPropertyName = null,
-    $messageTemplate = null,
-    MagicObject $reference = null,
-    bool $validateIfReferenceEmpty = true // ❌ Causes error in PHP 5
-)
-```
-
-After (PHP 5 Compatible):
+Added support for the `@TimeRange` validation annotation to validate time values within a specific range.
 
+**Usage Example:**
 ```php
-public function validate(
-    $parentPropertyName = null,
-    $messageTemplate = null,
-    MagicObject $reference = null,
-    $validateIfReferenceEmpty = true // ✅ Compatible with PHP 5
-)
-```
+/**
+ * @TimeRange(from="08:00", to="17:00")
+ */
+public $jamKerja;
+````
 
-> This change ensures full compatibility with legacy environments running PHP 5, while maintaining functionality in modern PHP versions.
+* Accepts time strings in `HH:MM` or `HH:MM:SS` format.
+* Ensures the value falls within the defined range (inclusive).
+* Useful for scheduling, availability windows, or working hours validation.
 
-### Backward Compatibility
+This new validation rule strengthens form-level data validation where time constraints are critical.
 
--   This version is **fully backward-compatible**.
-    
--   No breaking changes were introduced.
-    
--   Existing codebases will continue to function as-is unless the new functionality is explicitly invoked.

src/MagicObject.php

@@ -1297,46 +1297,53 @@ public function getOrDefault($propertyName, $defaultValue = null)
     }
 
     /**
-     * Retrieves a value from a nested object based on the provided keys.
-     * This function allows you to access nested properties of an object by passing the keys
-     * in a dot-notation-like fashion, where each key corresponds to a level in the object hierarchy.
-     * 
-     * The method will return the value at the deepest level if all the keys exist. If any key does not
-     * exist or the value at any level is not set, the function will return `null`.
-     * 
-     * @param string ...$keys The keys used to retrieve the value at various levels of the object.
-     * Each key corresponds to a property in the object, and the keys are automatically camelized.
-     * 
-     * @return mixed|null The value found at the specified keys in the object, or `null` if any key is not found.
+     * Retrieves a value from a nested object using a series of keys.
+     *
+     * This method allows you to access deeply nested properties of an object by specifying
+     * the keys either as multiple arguments or as a single string using dot (`.`) or arrow (`->`) notation.
+     * Each key will be automatically converted to camelCase before property access.
+     *
+     * Supported usage examples:
+     * - $obj->retrieve('user', 'profile', 'name')
+     * - $obj->retrieve('user.profile.name')
+     * - $obj->retrieve('user->profile->name')
+     *
+     * If all keys exist and the values are properly set, the final nested value is returned.
+     * If any key is missing or the chain is broken at any point, the method returns `null`.
+     *
+     * @param string ...$keys One or more keys, either as multiple arguments or a single string with separators.
+     * @return mixed|null The final nested value, or `null` if any key is not found.
      */
     public function retrieve(...$keys)
     {
-        // Start from the current object
         $currentData = $this;
-        
-        // Loop through all provided keys
+        $normalizedKeys = [];
+
         foreach ($keys as $key) {
-            // Convert key to camelCase format for consistency
-            if($key === null)
-            {
-                break;
+            if ($key === null) {
+                continue;
+            }
+
+            // Split string by common delimiters and add to normalized list
+            $parts = preg_split('/->|\./', $key);
+            foreach ($parts as $part) {
+                if (strlen(trim($part)) > 0) {
+                    $normalizedKeys[] = PicoStringUtil::camelize($part);
+                }
             }
-            $key = PicoStringUtil::camelize($key);
+        }
 
-            // Check if the current data object has the given key and the value is not null
+        foreach ($normalizedKeys as $key) {
             if (isset($currentData) && $currentData instanceof self && $currentData->hasValue($key)) {
-                // If the key exists, get the value at this level
                 $currentData = $currentData->get($key);
             } else {
-                // If any key is not found, return null
                 return null;
             }
         }
 
-        // Return the final value at the deepest level
         return $currentData;
     }
-
+    
     /**
      * Set property value (magic setter).
      *

src/Util/ValidationUtil.php

@@ -93,14 +93,15 @@ public function init($customTemplates = array())
             'ip' => "Field '\${property}' must be a valid IP address",
             'dateFormat' => "Field '\${property}' must match the date format '\${format}'",
             'phone' => "Field '\${property}' must be a valid phone number",
-            'enum' => "Field '\${property}' has an invalid value. Allowed values: \${allowedValues}.",
+            'enum' => "Field '\${property}' has an invalid value. Allowed values: \${allowedValues}",
             'alpha' => "Field '\${property}' must contain only alphabetic characters",
             'alphaNumeric' => "Field '\${property}' must contain only alphanumeric characters",
             'startsWith' => "Field '\${property}' must start with '\${prefix}'",
             'endsWith' => "Field '\${property}' must end with '\${suffix}'",
             'contains' => "Field '\${property}' must contain '\${substring}'",
             'beforeDate' => "Field '\${property}' must be before '\${date}'",
             'afterDate' => "Field '\${property}' must be after '\${date}'",
+            'timeRange' => "Field '\${property}' must be between \${min} and \${max}",
         );
 
         // Process custom templates to camelize keys
@@ -225,6 +226,7 @@ public function validate($object, $parentPropertyName = null) // NOSONAR
             $this->validateContainsAnnotation($fullPropertyName, $propertyValue, $docComment);
             $this->validateBeforeDateAnnotation($fullPropertyName, $propertyValue, $docComment);
             $this->validateAfterDateAnnotation($fullPropertyName, $propertyValue, $docComment);
+            $this->validateTimeRangeAnnotation($fullPropertyName, $propertyValue, $docComment);
             $this->validateSizeAnnotation($fullPropertyName, $propertyValue, $docComment);
             $this->validateMinAnnotation($fullPropertyName, $propertyValue, $docComment);
             $this->validateMaxAnnotation($fullPropertyName, $propertyValue, $docComment);
@@ -1371,4 +1373,40 @@ private function validateAfterDateAnnotation($propertyName, $propertyValue, $doc
             }
         }
     }
+    
+    /**
+     * Validates the **`TimeRange`** annotation.
+     * Ensures a time is within a specified range (min and max).
+     */
+    private function validateTimeRangeAnnotation($propertyName, $propertyValue, $docComment)
+    {
+        if (preg_match('/@TimeRange\(([^)]*)\)/', $docComment, $matches)) {
+            $params = $this->parseAnnotationParams($matches[1]);
+            $min = isset($params['min']) ? $params['min'] : '00:00'; // Default min to start of day
+            $max = isset($params['max']) ? $params['max'] : '23:59'; // Default max to end of day
+            $message = isset($params['message']) ? $params['message'] : null;
+
+            if ($this->isBlank($message)) {
+                $message = $this->createMessage('timeRange', array('property' => $propertyName, 'min' => $min, 'max' => $max));
+            }
+
+            // Convert propertyValue to a time string if it's a DateTime object
+            if ($propertyValue instanceof DateTimeInterface) {
+                $valueTime = $propertyValue->format('H:i');
+            } else {
+                $valueTime = (string) $propertyValue;
+            }
+
+            // Normalize time strings to HH:MM format for consistent comparison
+            $valueTime = date('H:i', strtotime($valueTime));
+            $minTime = date('H:i', strtotime($min));
+            $maxTime = date('H:i', strtotime($max));
+
+            // Perform the time range validation
+            // We compare as strings because 'H:i' format allows direct string comparison for time
+            if ($valueTime < $minTime || $valueTime > $maxTime) {
+                throw new InvalidValueException($propertyName, $message);
+            }
+        }
+    }
 }