feat: add form-safe empty string coercion for objects and arrays

- ObjectValidator: Empty strings ('') now coerce to empty stdClass objects
- AssociativeValidator: Empty strings ('') now coerce to empty arrays []
- Real-world benefit: Form parameters like ?settings= create empty structures instead of failing
- Type safety maintained: Non-empty strings still fail validation as expected
- Composable with nullifyEmpty(): coerce().nullifyEmpty() converts empty structures to null

Examples:
- Validator::isObject()->coerce()->validate('') → new stdClass()
- Validator::isAssociative()->coerce()->validate('') → []
- Validator::isObject()->coerce()->nullifyEmpty()->validate('') → null

- Add comprehensive test coverage (6 new tests, 23 new assertions)
- Update project documentation with enhanced form-safe coercion details
- Total test suite: 126 tests, 358 assertions

Author: lemmon

AGENTS.md

@@ -24,7 +24,7 @@ A comprehensive, fluent validation library for PHP inspired by Valibot and Zod.
 ### Validation Capabilities
 - **Static Logical Combinators** - `Validator::allOf()`, `Validator::anyOf()`, `Validator::not()` for complex rule composition and mixed-type validation
 - **Instance Logical Combinators** - `allOf()`, `anyOf()`, `not()` instance methods for chaining validation rules
-- **Form-Safe Coercion** - Empty strings convert to `null` (not dangerous `0`/`0.0`/`false`) for real-world form safety
+- **Form-Safe Coercion** - Empty strings convert to `null` (not dangerous `0`/`0.0`/`false`) for primitives, empty structures for objects/arrays
 - **Array Filtering** - `filterEmpty()` method removes empty values while maintaining indexed array structure
 - **Type-Aware Transformations** - Revolutionary `transform()` and `pipe()` system with intelligent type context switching
 - **Custom Validation** - `satisfies()` method for business logic integration with optional error messages
@@ -65,7 +65,7 @@ A comprehensive, fluent validation library for PHP inspired by Valibot and Zod.
 ## 🔧 Development Workflow
 
 ### Code Quality
-- **Testing** - Pest PHP with organized test suite (10 focused test files, 120 tests, 335 assertions)
+- **Testing** - Pest PHP with organized test suite (10 focused test files, 126 tests, 358 assertions)
 - **Static Analysis** - PHPStan at maximum level for type safety
 - **Code Style** - PHP-CS-Fixer for consistent formatting
 - **Performance** - Optimized validation logic with eliminated code duplication
@@ -110,7 +110,7 @@ tests/
 - **8 validator types** covering all PHP data types
 - **35+ built-in validation methods** including static logical combinators, array filtering, type-aware transformations, form-safe coercion, and intuitive custom validation
 - **5,000+ lines of documentation** with practical examples and comprehensive coverage
-- **120 unit tests** with comprehensive coverage (335 assertions)
+- **126 unit tests** with comprehensive coverage (358 assertions)
 - **Zero technical debt** with modern PHP 8.1+ codebase
 - **Zero dead links** in documentation with seamless navigation
 - **Complete API documentation** with accurate method signatures and examples

CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Added
+- **Form-Safe Empty String Coercion**: Enhanced ObjectValidator and AssociativeValidator coercion for better form handling
+  - `ObjectValidator::coerce()`: Empty strings (`''`) now coerce to empty `stdClass` objects
+  - `AssociativeValidator::coerce()`: Empty strings (`''`) now coerce to empty arrays `[]`
+  - **Real-World Benefit**: Form parameters like `?settings=` now create empty structures instead of failing validation
+  - **Type Safety Maintained**: Non-empty strings still fail validation as expected
+  - Added comprehensive test coverage (6 new tests, 23 new assertions)
+
 ### Fixed
 - **CRITICAL BUG**: Fixed schema validation field inclusion behavior in ObjectValidator and AssociativeValidator
   - **Issue**: Validators were incorrectly including ALL schema fields in results, even when not provided in input

IDEAS.md

@@ -48,13 +48,14 @@ $formatted = Validator::isString()
 - ✅ Smart array coercion (indexed arrays auto-reindex, associative keys preserved)
 - ✅ Clean variadic syntax with `pipe(...$transformers)`
 - ✅ Perfect integration with external libraries (Laravel, Symfony)
-- ✅ Comprehensive test coverage (120 tests, 335 assertions)
+- ✅ Comprehensive test coverage (126 tests, 358 assertions)
 - ✅ Complete documentation overhaul with comprehensive coverage across all guides
 - ✅ Fixed all dead links in documentation for seamless navigation
 - ✅ Added type-aware transformation system documentation with detailed examples
 - ✅ Documented `filterEmpty()` method with practical use cases
 - ✅ Updated API reference to match actual implementation
 - ✅ Fixed critical schema validation bug - only include provided fields or fields with defaults in results
+- ✅ Enhanced form-safe coercion - empty strings coerce to empty objects/arrays for better form handling
 
 ### Intuitive Custom Validation (v0.6.0)
 **Status**: ✅ **IMPLEMENTED**

src/Lemmon/AssociativeValidator.php

@@ -37,6 +37,11 @@ protected function coerceValue(mixed $value): mixed
             return (array) $value;
         }
 
+        // Form-safe: empty string becomes empty array
+        if ($value === '') {
+            return [];
+        }
+
         // For other types (including arrays), return as-is.
         // The subsequent validateType method will handle non-array errors.
         return $value;

src/Lemmon/ObjectValidator.php

@@ -37,6 +37,11 @@ protected function coerceValue(mixed $value): mixed
             return (object) $value;
         }
 
+        // Form-safe: empty string becomes empty object
+        if ($value === '') {
+            return new \stdClass();
+        }
+
         // For other types (including objects), return as-is.
         // The subsequent validateType method will handle non-object errors.
         return $value;

tests/AssociativeValidatorTest.php

@@ -196,3 +196,36 @@
     expect(fn() => $schema->validate($input))
         ->toThrow(Lemmon\ValidationException::class, 'Value is required');
 });
+
+it('should coerce empty string to empty array when coerce is enabled', function () {
+    $schema = Validator::isAssociative()->coerce();
+
+    $result = $schema->validate('');
+
+    expect($result)->toBeArray();
+    expect($result)->toHaveCount(0);
+});
+
+it('should coerce empty string to array with defaults when schema has defaults', function () {
+    $schema = Validator::isAssociative([
+        'name' => Validator::isString(),
+        'status' => Validator::isString()->default('active'),
+        'role' => Validator::isString()->default('user')
+    ])->coerce();
+
+    $result = $schema->validate('');
+
+    expect($result)->toBeArray();
+    expect($result)->toHaveKey('status');
+    expect($result)->toHaveKey('role');
+    expect($result['status'])->toBe('active');
+    expect($result['role'])->toBe('user');
+    expect($result)->not->toHaveKey('name'); // Not provided, no default
+});
+
+it('should reject non-empty strings even with coerce enabled', function () {
+    $schema = Validator::isAssociative()->coerce();
+
+    expect(fn() => $schema->validate('not-empty'))
+        ->toThrow(Lemmon\ValidationException::class, 'Input must be an associative array');
+});

tests/ObjectValidatorTest.php

@@ -169,3 +169,34 @@
     expect(fn() => $schema->validate($input))
         ->toThrow(Lemmon\ValidationException::class, 'Value is required');
 });
+
+it('should coerce empty string to empty object when coerce is enabled', function () {
+    $schema = Validator::isObject()->coerce();
+
+    $result = $schema->validate('');
+
+    expect($result)->toBeInstanceOf(stdClass::class);
+    expect(get_object_vars($result))->toHaveCount(0);
+});
+
+it('should coerce empty string to object with defaults when schema has defaults', function () {
+    $schema = Validator::isObject([
+        'name' => Validator::isString(),
+        'status' => Validator::isString()->default('active'),
+        'role' => Validator::isString()->default('user')
+    ])->coerce();
+
+    $result = $schema->validate('');
+
+    expect($result)->toBeInstanceOf(stdClass::class);
+    expect($result)->toHaveProperty('status', 'active');
+    expect($result)->toHaveProperty('role', 'user');
+    expect($result)->not->toHaveProperty('name'); // Not provided, no default
+});
+
+it('should reject non-empty strings even with coerce enabled', function () {
+    $schema = Validator::isObject()->coerce();
+
+    expect(fn() => $schema->validate('not-empty'))
+        ->toThrow(Lemmon\ValidationException::class, 'Input must be an object');
+});