From 39daa97fc2e226906dc3f6bae4654d4b37ec0a72 Mon Sep 17 00:00:00 2001
From: George Steel <george@net-glue.co.uk>
Date: Fri, 1 May 2026 16:07:01 +0100
Subject: [PATCH 1/2] `HydratorException` should be `Throwable`

This is a technical BC break, but it's extremely unlikely that users will have implemented this interface on a non-throwable.

This fixes code for static analysers such as:

```php
try {
   return $hydrator->extract($object);
} catch(HydratorException $e) {
   throw new MyException('Foo', 0, $e);
}
```
---
 src/HydratorException.php | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/HydratorException.php b/src/HydratorException.php
index 5cc9811c..7b080a8d 100644
--- a/src/HydratorException.php
+++ b/src/HydratorException.php
@@ -4,6 +4,8 @@
 
 namespace Patchlevel\Hydrator;
 
-interface HydratorException
+use Throwable;
+
+interface HydratorException extends Throwable
 {
 }

From 32954333568a74087ff0729bd70413f79eef336d Mon Sep 17 00:00:00 2001
From: George Steel <george@net-glue.co.uk>
Date: Fri, 1 May 2026 16:41:23 +0100
Subject: [PATCH 2/2] Improve documentation of thrown exceptions via `Hydrator`

---
 src/Hydrator.php            |  9 ++++++++-
 src/HydratorWithContext.php |  5 +++++
 src/MetadataHydrator.php    | 13 +++++++++++++
 3 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/src/Hydrator.php b/src/Hydrator.php
index 60fb29ee..ae9a8a7a 100644
--- a/src/Hydrator.php
+++ b/src/Hydrator.php
@@ -13,11 +13,18 @@ interface Hydrator
      * @return T
      *
      * @throws ClassNotSupported if the class is not supported or not found.
+     * @throws DenormalizationFailure if any normalizers throw an exception.
+     * @throws TypeMismatch if a TypeError occurs when setting a property value.
+     * @throws HydratorException Any other thrown exceptions should implement HydratorException.
      *
      * @template T of object
      */
     public function hydrate(string $class, array $data): object;
 
-    /** @return array<string, mixed> */
+    /**
+     * @return array<string, mixed>
+     *
+     * @throws HydratorException
+     */
     public function extract(object $object): array;
 }
diff --git a/src/HydratorWithContext.php b/src/HydratorWithContext.php
index 6fea9dd6..86d18773 100644
--- a/src/HydratorWithContext.php
+++ b/src/HydratorWithContext.php
@@ -16,6 +16,9 @@ interface HydratorWithContext extends Hydrator
      * @return T
      *
      * @throws ClassNotSupported if the class is not supported or not found.
+     * @throws DenormalizationFailure if any normalizers throw an exception.
+     * @throws TypeMismatch if a TypeError occurs when setting a property value.
+     * @throws HydratorException Any other thrown exceptions should implement HydratorException.
      *
      * @template T of object
      */
@@ -25,6 +28,8 @@ public function hydrate(string $class, array $data, array $context = []): object
      * @param array<string, mixed> $context
      *
      * @return array<string, mixed>
+     *
+     * @throws HydratorException
      */
     public function extract(object $object, array $context = []): array;
 }
diff --git a/src/MetadataHydrator.php b/src/MetadataHydrator.php
index bab3ff40..2b91b21e 100644
--- a/src/MetadataHydrator.php
+++ b/src/MetadataHydrator.php
@@ -62,6 +62,11 @@ public function __construct(
      *
      * @return T
      *
+     * @throws ClassNotSupported if the target class does not exist.
+     * @throws DenormalizationFailure if any normalizers throw an exception.
+     * @throws TypeMismatch if a TypeError occurs when setting a property value.
+     * @throws HydratorException Any other thrown exceptions should implement HydratorException.
+     *
      * @template T of object
      */
     public function hydrate(string $class, array $data, array $context = []): object
@@ -96,6 +101,9 @@ function () use ($metadata, $data, $context): object {
      *
      * @return T
      *
+     * @throws DenormalizationFailure if any normalizers throw an exception.
+     * @throws TypeMismatch if a TypeError occurs when setting a property value.
+     *
      * @template T of object
      */
     private function doHydrate(ClassMetadata $metadata, array $data, array $context = []): object
@@ -179,6 +187,11 @@ private function doHydrate(ClassMetadata $metadata, array $data, array $context
      * @param array<string, mixed> $context
      *
      * @return array<string, mixed>
+     *
+     * @throws CircularReference
+     * @throws NormalizationFailure
+     * @throws NormalizationMissing
+     * @throws ClassNotFound
      */
     public function extract(object $object, array $context = []): array
     {