feat: Add ObjectValidator and refactor for API consistency

This major feature release introduces the `ObjectValidator` and refactors the existing `SchemaValidator` to `AssociativeValidator` for a more consistent and symmetrical API.

- **feat(ObjectValidator):** Add new `ObjectValidator` for validating `stdClass` objects, created via `Validator::isObject()`.
- **feat(Coercion):** Implement cross-coercion. `ObjectValidator` can now coerce arrays to objects, and `AssociativeValidator` can coerce objects to arrays.
- **refactor(SchemaValidator):** Rename `SchemaValidator` to `AssociativeValidator` to align with the factory method `isAssociative()` and improve API clarity.
- **fix(Validator):** Loosen the type hint on the internal `FieldValidator::tryValidate()` method to allow both array and object payloads, fixing a TypeError.
- **docs:** Update README, CHANGELOG, and project roadmap. Add Packagist badge and installation instructions.
- **chore:** Add IDEAS.md to version control.
- **chore:** Improve PHPDoc blocks to fix all static analysis errors.

Author: lemmon

CHANGELOG.md

@@ -2,13 +2,27 @@
 
 All notable changes to this project will be documented in this file.
 
-## [0.1.0] - 2025-09-05
+## [Unreleased]
+
+## [0.2.0] - 2025-09-07
 
 ### Added
 
-- Initial release of the `lemmon/validator` package.
+- `ObjectValidator` for validating `stdClass` objects, created with `Validator::isObject()`.
+- Coercion support for `ObjectValidator` to convert associative arrays into `stdClass` objects.
+- Coercion support for `AssociativeValidator` to convert `stdClass` objects into associative arrays.
 
-## [Unreleased]
+### Changed
+
+- **BREAKING**: Renamed `SchemaValidator` to `AssociativeValidator` for better API consistency.
+- The factory method `Validator::isAssociative()` now returns an `AssociativeValidator` instance.
+- Improved error message for associative array type validation to be more specific.
+
+### Fixed
+
+- Changed the type hint on `FieldValidator::tryValidate()` to `mixed` to correctly accept both array and object payloads as context.
+
+## [0.1.0] - 2025-09-05
 
 ### Added
 

GEMINI.md

@@ -1,21 +1,21 @@
 # Lemmon Validator Project Summary
 
-This project is a lightweight, fluent validation library for PHP, inspired by Valibot and Zod. It provides a structured way to validate various data types, including associative arrays, plain arrays, strings, integers, and booleans, with support for coercion, required fields, default values, and `oneOf` constraints.
+This project is a lightweight, fluent validation library for PHP, inspired by Valibot and Zod. It provides a structured way to validate various data types, including associative arrays, `stdClass` objects, plain arrays, strings, integers, and booleans. It features a symmetrical and predictable API for handling different data structures.
 
 ## Key Components:
 
-*   **`Validator.php`**: Acts as a factory for creating different validator instances (e.g., `isAssociative()`, `isArray()`, `isString()`). The `isAssociative()` method can now be called without arguments to create an empty schema.
-*   **`SchemaValidator.php`**: Handles validation for associative arrays, allowing definition of a schema with `FieldValidator` instances. **Crucially, it now extends `FieldValidator.php`**, inheriting its `validate()` and `tryValidate()` methods. Its core schema validation logic resides in its `validateType()` method.
-*   **`FieldValidator.php`**: An abstract base class for individual field validators. It defines common validation methods like `required()`, `default()`, `coerce()`, and `oneOf()`. It implements a unified `validate()` (throws exception) and `tryValidate()` (returns status, data, errors) pattern. Error messages are now generic, with field context provided by the error object's structure.
-*   **Specific Validators (e.g., `StringValidator.php`, `IntValidator.php`, `BoolValidator.php`, `ArrayValidator.php`)**: Implement the abstract methods from `FieldValidator.php` to provide type-specific validation and coercion logic. The `ArrayValidator.php` now coerces empty strings to empty arrays.
-*   **`ValidationException.php`**: Custom exception class used to report validation errors.
+*   **`Validator.php`**: Acts as a factory for creating different validator instances (e.g., `isAssociative()`, `isObject()`, `isArray()`).
+*   **`AssociativeValidator.php`**: Handles validation for associative arrays. It can be configured with `->coerce()` to automatically convert a `stdClass` object into an associative array before validation.
+*   **`ObjectValidator.php`**: Handles validation for `stdClass` objects. It can be configured with `->coerce()` to automatically convert an associative array into a `stdClass` object before validation.
+*   **`FieldValidator.php`**: An abstract base class for all individual validators. It defines common validation methods like `required()`, `default()`, `coerce()`, and `oneOf()`. It implements a unified `validate()` (throws exception) and `tryValidate()` (returns result tuple) pattern.
+*   **Specific Validators (e.g., `StringValidator.php`, `IntValidator.php`, `ArrayValidator.php`)**: Implement type-specific validation and coercion logic.
+*   **`ValidationException.php`**: Custom exception class used to report validation errors, capable of holding a nested structure of error messages.
 
 ## Development Setup:
 
 *   **Dependencies**: Managed by Composer (`composer.json`).
-*   **Testing**: Uses Pest PHP (`tests/ValidatorTest.php`).
-*   **Code Style**: Enforced by PHP-CS-Fixer.
-*   **Static Analysis**: Performed by PHPStan.
-*   **Local Testing**: A `temp/` directory is used for ad-hoc CLI tests, with a `_bootstrap.php` file for common setup (Composer autoloader, Symfony ErrorHandler). The `temp/` directory is excluded from Git via `.gitignore`.
-*   **Debugging**: `symfony/var-dumper` is included as a dev dependency for easy debugging.
-*   **Error Handling**: `symfony/error-handler` is included as a dev dependency and registered in the bootstrap for improved error reporting.
+*   **Testing**: Uses Pest PHP (`tests/ValidatorTest.php`). The test suite is run with `composer test`.
+*   **Code Style**: Enforced by PHP-CS-Fixer. Can be checked with `composer lint` and fixed with `composer fix`.
+*   **Static Analysis**: Performed by PHPStan. Can be run with `composer analyse`.
+*   **Debugging**: `symfony/var-dumper` is included as a dev dependency.
+*   **Error Handling**: `symfony/error-handler` is included as a dev dependency.

IDEAS.md

@@ -0,0 +1,29 @@
+# Lemmon Validator - Future Ideas and Suggestions
+
+This document captures ideas and suggestions for potential future enhancements to the Lemmon Validator library, beyond the current roadmap. These are not prioritized but serve as a backlog of possibilities for further development.
+
+## 1. Data Transformation / Piping
+
+*   **Concept**: Introduce a more general `transform(callable $callback)` method (or a `pipe()` concept) that allows users to apply arbitrary transformations to the validated data *after* validation but *before* it's returned. This is distinct from `coerce()` which is typically about type conversion.
+*   **Benefit**: Very powerful for data normalization, sanitization, or shaping. For example, you could validate a string, then transform it into a `DateTime` object, or encrypt it, all within the validation chain.
+*   **Example**: `Validator::isString()->datetime()->transform(fn($value) => new DateTime($value))`
+
+## 2. Enhanced Error Pathing for Nested Schemas
+
+*   **Concept**: For errors in nested schemas, enhance the error reporting to include the full "path" to the invalid field.
+*   **Benefit**: When dealing with deeply nested data structures, knowing the exact path (e.g., `user.address.street` instead of just `street`) to an error is invaluable for debugging and user feedback.
+*   **Example**: Instead of `['street' => ['Value is required.']]`, the error object could contain a `path` property (e.g., `['path' => 'user.address.street', 'message' => 'Value is required.']`) or the error key could be the full path.
+
+## 3. Schema Manipulation Methods
+
+*   **Concept**: Introduce methods on `SchemaValidator` (or `FieldValidator` for `partial()`) that allow for easy manipulation and reuse of existing schemas.
+*   **`partial()`**: Makes all fields in a schema (or a specific validator) optional. Useful for PATCH requests where only a subset of fields might be sent.
+*   **`pick(array $keys)`**: Creates a new schema containing only the specified keys from an existing schema.
+*   **`omit(array $keys)`**: Creates a new schema excluding the specified keys from an existing schema.
+*   **`merge(SchemaValidator $otherSchema)`**: Combines two schemas into one.
+*   **Benefit**: Promotes schema reusability and reduces boilerplate when you need slightly different versions of a base schema.
+
+## 4. Error Codes
+
+*   **Concept**: Assign unique, programmatic error codes to common validation failures (e.g., `STRING_TOO_SHORT`, `INVALID_EMAIL_FORMAT`).
+*   **Benefit**: Allows for easier programmatic handling of specific error types in the application layer, beyond just parsing the human-readable message.

README.md

@@ -1,10 +1,19 @@
 # Lemmon Validator
 
 [![CI](https://github.com/lemmon/validator-php/actions/workflows/ci.yml/badge.svg)](https://github.com/lemmon/validator-php/actions/workflows/ci.yml)
+[![Latest Stable Version](https://img.shields.io/packagist/v/lemmon/validator.svg)](https://packagist.org/packages/lemmon/validator)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 A lightweight, fluent validation library for PHP, inspired by Valibot and Zod.
 
+## Installation
+
+Install the package with Composer:
+
+```bash
+composer require lemmon/validator
+```
+
 ## Usage
 
 ### Associative array validation
@@ -41,6 +50,28 @@ $emptyData = $emptySchema->validate([]); // Validates an empty array
 // $validNull will be true, $dataNull will be null, $errorsNull will be null
 ```
 
+### Object validation
+
+Similar to associative arrays, you can validate `stdClass` objects.
+
+```php
+use Lemmon\Validator;
+
+// Define a schema for an object
+$schema = Validator::isObject([
+  'name' => Validator::isString()->required(),
+  'age'  => Validator::isInt()->coerce(),
+]);
+
+// Validate a stdClass object
+$object = (object)['name' => 'John Doe', 'age' => '42'];
+$validatedObject = $schema->validate($object); // ✓ $validatedObject->age is now (int) 42
+
+// Coerce an associative array into a stdClass object
+$array = ['name' => 'Jane Doe', 'age' => 30];
+$coercedObject = $schema->coerce()->validate($array); // ✓
+```
+
 ### Array validation
 
 ```php

TODO.md

@@ -3,9 +3,10 @@
 This roadmap outlines the planned features for future releases, prioritizing commonly needed functionalities for application development.
 
 **Released:**
+- `0.2.0` - Added `ObjectValidator`, refactored `SchemaValidator` to `AssociativeValidator`, and enabled cross-coercion between them.
 - `0.1.0` - Initial release.
 
-## Release 0.2: Common Formats & Utility Constraints
+## Common Formats & Utility Constraints
 
 This release focuses on introducing highly practical format validators for strings and other frequently used utility constraints.
 
@@ -26,11 +27,11 @@ This release focuses on introducing highly practical format validators for strin
     *   Implement `enum(array $allowedValues)`: Validates that a value is one of a predefined set of values (for all `FieldValidator` types).
     *   Implement `const(mixed $constantValue)`: Validates that a value is exactly equal to a specific constant.
 
-## Release 0.3: Advanced Structure & Relationships
+## Advanced Structure & Relationships
 
 This release introduces more sophisticated validation rules for complex data structures and their interdependencies.
 
-*   **SchemaValidator (Object Properties)**:
+*   **AssociativeValidator & ObjectValidator**:
     *   Implement `additionalProperties(FieldValidator|bool $validatorOrBoolean)`: Controls whether properties not explicitly defined in the schema are allowed, and optionally validates them against a subschema.
     *   Implement `patternProperties(array $regexToValidatorMap)`: Validates properties whose names match a given regular expression against a subschema.
     *   Implement `propertyNames(StringValidator $validator)`: Validates the names of all properties in an object against a string schema.
@@ -39,7 +40,7 @@ This release introduces more sophisticated validation rules for complex data str
     *   Implement `contains(FieldValidator $validator)`: Validates that an array contains at least one item that matches a given subschema.
     *   Implement `additionalItems(FieldValidator|bool $validatorOrBoolean)`: Controls whether items beyond those defined in `items` (when `items` is an array of schemas) are allowed, and optionally validates them.
 
-## Release 0.4: Logical Combinators
+## Logical Combinators
 
 This release introduces the powerful logical combinators for expressing complex validation rules.
 

composer.json

@@ -3,6 +3,8 @@
     "description": "A lightweight, fluent validation library for PHP.",
     "type": "library",
     "license": "MIT",
+    "homepage": "https://github.com/lemmon/validator-php",
+    "keywords": ["validation", "validator", "schema", "zod", "valibot"],
     "authors": [
         {
             "name": "Jakub Pelák",

src/Lemmon/SchemaValidator.php src/Lemmon/AssociativeValidator.phpsrc/Lemmon/SchemaValidator.php renamed to src/Lemmon/AssociativeValidator.php

@@ -2,7 +2,7 @@
 
 namespace Lemmon;
 
-class SchemaValidator extends FieldValidator
+class AssociativeValidator extends FieldValidator
 {
     private bool $coerceAll = false;
 
@@ -25,11 +25,12 @@ public function coerceAll(): self
      */
     protected function coerceValue(mixed $value): mixed
     {
-        // If it's already an array, return as-is
-        if (is_array($value)) {
-            return $value;
+        if (is_object($value)) {
+            return (array) $value;
         }
-        // For other types, return as-is; validateType will handle the error
+
+        // For other types (including arrays), return as-is.
+        // The subsequent validateType method will handle non-array errors.
         return $value;
     }
 
@@ -39,7 +40,7 @@ protected function coerceValue(mixed $value): mixed
     protected function validateType(mixed $value, string $key): mixed
     {
         if (!is_array($value)) {
-            throw new ValidationException(['Value must be an array.']);
+            throw new ValidationException(['Input must be an associative array.']);
         }
 
         $data = [];
@@ -63,4 +64,4 @@ protected function validateType(mixed $value, string $key): mixed
 
         return $data;
     }
-}
+}

src/Lemmon/FieldValidator.php

@@ -85,7 +85,7 @@ public function validate(mixed $value, string $key = '', array $input = []): mix
     {
         [$valid, $data, $errors] = $this->tryValidate($value, $key, $input);
         if (!$valid) {
-            throw new ValidationException($errors);
+            throw new ValidationException($errors ?? ['Validation failed.']);
         }
         return $data;
     }
@@ -95,13 +95,13 @@ public function validate(mixed $value, string $key = '', array $input = []): mix
      *
      * @param mixed $value The value to validate.
      * @param string $key The key of the field being validated.
-     * @param array<string, mixed> $input The entire input array.
+     * @param mixed|null $input The entire input payload (array or object).
      * @return array{bool, mixed, array<string>|null} A tuple containing:
      *                                                 - bool: true if validation is successful, false otherwise.
      *                                                 - mixed: The validated and potentially coerced value, or the original value on failure.
      *                                                 - array|null: An array of error messages on failure, or null on success.
      */
-    public function tryValidate(mixed $value, string $key = '', array $input = []): array
+    public function tryValidate(mixed $value, string $key = '', mixed $input = null): array
     {
         if ($this->nullifyEmpty && (($value === '') || (is_array($value) && empty($value)))) {
             $value = null;
@@ -142,4 +142,4 @@ abstract protected function coerceValue(mixed $value): mixed;
      * @throws ValidationException If the type validation fails.
      */
     abstract protected function validateType(mixed $value, string $key): mixed;
-}
+}

src/Lemmon/ObjectValidator.php

@@ -0,0 +1,71 @@
+<?php
+
+namespace Lemmon;
+
+class ObjectValidator extends FieldValidator
+{
+    private bool $coerceAll = false;
+
+    /**
+     * @param array<string, FieldValidator> $schema
+     */
+    public function __construct(
+        private array $schema
+    ) {
+    }
+
+    public function coerceAll(): self
+    {
+        $this->coerceAll = true;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    protected function coerceValue(mixed $value): mixed
+    {
+        if (is_array($value)) {
+            return (object) $value;
+        }
+
+        // For other types (including objects), return as-is.
+        // The subsequent validateType method will handle non-object errors.
+        return $value;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    protected function validateType(mixed $value, string $key): mixed
+    {
+        if (!is_object($value)) {
+            throw new ValidationException(['Input must be an object.']);
+        }
+
+        $data = new \stdClass();
+        $errors = [];
+
+        foreach ($this->schema as $fieldKey => $validator) {
+            if ($this->coerceAll) {
+                $validator->coerce();
+            }
+
+            $fieldValue = $value->{$fieldKey} ?? null;
+
+            [$valid, $validatedFieldValue, $fieldErrors] = $validator->tryValidate($fieldValue, $fieldKey, $value);
+
+            if (!$valid) {
+                $errors[$fieldKey] = $fieldErrors;
+            } elseif (isset($validatedFieldValue)) {
+                $data->{$fieldKey} = $validatedFieldValue;
+            }
+        }
+
+        if (!empty($errors)) {
+            throw new ValidationException($errors);
+        }
+
+        return $data;
+    }
+}

src/Lemmon/ValidationException.php

@@ -5,7 +5,7 @@
 class ValidationException extends \Exception
 {
     /**
-     * @param array<string> $errors
+     * @param array<array-key, mixed> $errors
      */
     public function __construct(
         private array $errors
@@ -15,7 +15,7 @@ public function __construct(
     }
 
     /**
-     * @return array<string>
+     * @return array<array-key, mixed>
      */
     public function getErrors(): array
     {