fix(array-validator): preserve array indices in flattened error messages

Fixed ArrayValidator to collect all item validation errors with proper
indexing. Previously, array indices were lost in error paths (e.g.,
'symlinks.destination' instead of 'symlinks.0.destination') and only
the first error was collected.

- Changed from validate() to tryValidate() for item validation
- Collect all errors with proper array index keys
- Updated tests to reflect correct behavior
- Updated documentation with examples showing preserved indices

Author: lemmon

CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Fixed
+- **CRITICAL BUG**: Fixed array validator error handling to preserve array indices in flattened error messages
+  - **Issue**: Array item validation errors lost array index information, showing paths like `symlinks.destination` instead of `symlinks.0.destination`
+  - **Root Cause**: `ArrayValidator` used `validate()` which threw immediately on first error, losing index context and preventing error collection
+  - **Fix**: Changed to use `tryValidate()` for all items, collecting errors with proper indexing (similar to `AssociativeValidator` behavior)
+  - **Impact**: Flattened error messages now correctly identify which array item has validation errors (e.g., `symlinks.0.destination`, `symlinks.2.destination`)
+  - **Behavior**: All array item errors are now collected (not just the first), and indices are preserved in error paths
+  - **Real-World Benefit**: API error responses and form validation can now accurately pinpoint which array element failed validation
+
 ## [0.11.1] - 2025-12-28
 
 ### Fixed

docs/guides/array-validation.md

@@ -387,8 +387,18 @@ $validator = Validator::isArray()->items(Validator::isString());
 try {
     $validator->validate(['valid', 123, 'also valid']);
 } catch (ValidationException $e) {
-    // Error will indicate which item failed validation
+    // Errors preserve array indices to identify which item failed
     print_r($e->getErrors());
+    // Output:
+    // [
+    //     '1' => ['Value must be a string']
+    // ]
+
+    // Flattened errors show full path with index
+    $flattened = $e->getFlattenedErrors();
+    // [
+    //     ['path' => '1', 'message' => 'Value must be a string']
+    // ]
 }
 ```
 
@@ -402,12 +412,52 @@ $validator = Validator::isArray()->items(Validator::isInt());
 if (!$valid) {
     echo "Validation failed:\n";
     print_r($errors);
+    // Output:
+    // [
+    //     '1' => ['Value must be an integer']
+    // ]
+
+    // Flattened errors preserve array indices
+    $flattened = ValidationException::flattenErrors($errors);
+    // [
+    //     ['path' => '1', 'message' => 'Value must be an integer']
+    // ]
 } else {
     echo "Valid array:\n";
     print_r($result);
 }
 ```
 
+### Nested Array Item Errors
+
+For arrays with complex item validators (like associative arrays), errors preserve the full path including array indices:
+
+```php
+$schema = Validator::isAssociative([
+    'users' => Validator::isArray()->items(Validator::isAssociative([
+        'name' => Validator::isString()->required(),
+        'email' => Validator::isString()->email()->required(),
+    ])),
+]);
+
+$input = [
+    'users' => [
+        ['name' => 'John'], // Missing email
+        ['name' => 'Jane', 'email' => 'invalid-email'], // Invalid email
+    ],
+];
+
+try {
+    $schema->validate($input);
+} catch (ValidationException $e) {
+    $flattened = $e->getFlattenedErrors();
+    // [
+    //     ['path' => 'users.0.email', 'message' => 'Value is required'],
+    //     ['path' => 'users.1.email', 'message' => 'Value must be a valid email address']
+    // ]
+}
+```
+
 ## Advanced Examples
 
 ### File Upload Validation

docs/guides/error-handling.md

@@ -198,6 +198,65 @@ $invalidData = [
 // ]
 ```
 
+### Array Item Validation Errors
+
+For arrays with item validators, errors preserve array indices to identify which item failed:
+
+```php
+$schema = Validator::isAssociative([
+    'items' => Validator::isArray()->items(Validator::isInt()->min(1)),
+]);
+
+$input = [
+    'items' => [5, -2, 0, 10], // Items at index 1 and 2 are invalid
+];
+
+[$valid, $data, $errors] = $schema->tryValidate($input);
+
+// $errors structure preserves array indices:
+// [
+//     'items' => [
+//         '1' => ['Value must be at least 1'],
+//         '2' => ['Value must be at least 1']
+//     ]
+// ]
+
+// Flattened errors show full paths with indices:
+$flattened = ValidationException::flattenErrors($errors);
+// [
+//     ['path' => 'items.1', 'message' => 'Value must be at least 1'],
+//     ['path' => 'items.2', 'message' => 'Value must be at least 1']
+// ]
+```
+
+For nested structures with array items, the full path including indices is preserved:
+
+```php
+$schema = Validator::isAssociative([
+    'users' => Validator::isArray()->items(Validator::isAssociative([
+        'name' => Validator::isString()->required(),
+        'email' => Validator::isString()->email()->required(),
+    ])),
+]);
+
+$input = [
+    'users' => [
+        ['name' => 'John'], // Missing email at index 0
+        ['name' => 'Jane', 'email' => 'invalid'], // Invalid email at index 1
+    ],
+];
+
+try {
+    $schema->validate($input);
+} catch (ValidationException $e) {
+    $flattened = $e->getFlattenedErrors();
+    // [
+    //     ['path' => 'users.0.email', 'message' => 'Value is required'],
+    //     ['path' => 'users.1.email', 'message' => 'Value must be a valid email address']
+    // ]
+}
+```
+
 ## Error Message Customization
 
 ### Built-in Validator Messages

src/Lemmon/Validator/ArrayValidator.php

@@ -153,14 +153,29 @@ protected function validateType(mixed $value, string $key): mixed
         // If item validator is set, validate each item
         if ($this->itemValidator !== null) {
             $validatedItems = [];
+            $errors = [];
+
             foreach ($value as $index => $item) {
-                try {
-                    $itemKey = ($key ? $key . '.' : '') . $index;
-                    $validatedItems[] = $this->itemValidator->validate($item, $itemKey, []);
-                } catch (ValidationException $e) {
-                    throw $e;
+                $itemKey = ($key ? $key . '.' : '') . $index;
+                [$valid, $validatedItem, $itemErrors] = $this->itemValidator->tryValidate(
+                    $item,
+                    (string) $index,
+                    $value,
+                );
+
+                if (!$valid) {
+                    // Wrap item errors under the index key
+                    $errors[$index] = $itemErrors;
+                    continue;
                 }
+
+                $validatedItems[] = $validatedItem;
             }
+
+            if ($errors !== []) {
+                throw new ValidationException($errors);
+            }
+
             return $validatedItems;
         }
 

tests/ValidationExceptionTest.php

@@ -115,10 +115,10 @@
         $schema->validate($input);
     } catch (ValidationException $e) {
         $flattened = $e->getFlattenedErrors();
-        // Note: Currently array validation throws on first error
-        // The error is stored at 'items' key, not 'items.1'
+        // Array validation collects all errors with proper indices
         expect($flattened)->toBe([
-            ['path' => 'items', 'message' => 'Value must be at least 1'],
+            ['path' => 'items.1', 'message' => 'Value must be at least 1'],
+            ['path' => 'items.2', 'message' => 'Value must be at least 1'],
         ]);
     }
 });
@@ -141,11 +141,11 @@
         $schema->validate($input);
     } catch (ValidationException $e) {
         $flattened = $e->getFlattenedErrors();
-        // Note: Currently array item errors lose the index in the structure
-        // The error is stored as ['users' => ['email' => ['error']]]
-        // So the flattened path is 'users.email' not 'users.0.email'
+        // Array item errors preserve the index in the structure
+        // The error is stored as ['users' => ['0' => ['email' => ['error']]]]
+        // So the flattened path is 'users.0.email'
         expect($flattened)->toBe([
-            ['path' => 'users.email', 'message' => 'Value is required'],
+            ['path' => 'users.0.email', 'message' => 'Value is required'],
         ]);
     }
 });
@@ -199,8 +199,8 @@
         expect($paths)->toContain('title');
         expect($paths)->toContain('author.name');
         expect($paths)->toContain('author.contact.email');
-        // Array item errors will have path 'tags' (index lost in current implementation)
-        expect($paths)->toContain('tags');
+        // Array item errors preserve the index, so path is 'tags.0'
+        expect($paths)->toContain('tags.0');
     }
 });