From 8fa972d5fafb73321fc22d0db1625c8935164422 Mon Sep 17 00:00:00 2001
From: Eithel <tux.eithel@gmail.com>
Date: Fri, 5 Jun 2026 14:32:48 +0200
Subject: [PATCH] docs: add documentation for validateObject method

---
 docs/2-features/03-validation.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/docs/2-features/03-validation.md b/docs/2-features/03-validation.md
index d0d3900ea0..c91329cbcc 100644
--- a/docs/2-features/03-validation.md
+++ b/docs/2-features/03-validation.md
@@ -76,6 +76,30 @@ final class Book
 }
 ```
 
+## Validating an existing object instance
+
+When you already have an instantiated object, you may use the `validateObject()` method. Unlike `validateValuesForClass()`, this method takes an object instance and reads the actual values of its public properties directly.
+
+```php
+$config = $this->configRepository->find($id);
+
+$this->validator->validateObject($config);
+```
+
+This is particularly useful where an object carries validation rules as part of its invariants, and you want to enforce them after the object has been hydrated from a source.
+
+### Behavior differences from `validateValuesForClass()`
+
+There are a few important differences to be aware of:
+
+**It throws instead of returning.** When validation fails, `validateObject()` throws a {`\Tempest\Validation\Exceptions\ValidationFailed`} exception rather than returning a list of failures.
+
+**Uninitialized properties are skipped.** If a public property has not been initialized on the object, it is silently skipped.
+
+**`#[SkipValidation]` is not respected.** Unlike `validateValuesForClass()`, this method does not check for the {b`#[Tempest\Validation\SkipValidation]`} attribute: all initialized public properties are validated.
+
+**Nested objects are not recursed into.** If a property holds another object, that nested object's properties are not validated.
+
 ## Validating against specific rules
 
 If you don't have a model or data transfer object to validate data against, you may alternatively use the `validateValues()` and provide an array of rules.