From d6005dc1a599db3cfe3196defd4dadf991d31477 Mon Sep 17 00:00:00 2001 From: Rico Sonntag Date: Fri, 14 Nov 2025 10:57:51 +0100 Subject: [PATCH] docs(exception): clarify exception phpdoc --- .../Exception/CollectionMappingException.php | 12 +++++++++++ src/JsonMapper/Exception/MappingException.php | 14 +++++++++++++ .../Exception/MissingPropertyException.php | 18 +++++++++++++++- .../Exception/ReadonlyPropertyException.php | 5 +++++ .../Exception/TypeMismatchException.php | 21 +++++++++++++++++++ .../Exception/UnknownPropertyException.php | 19 ++++++++++++++++- 6 files changed, 87 insertions(+), 2 deletions(-) diff --git a/src/JsonMapper/Exception/CollectionMappingException.php b/src/JsonMapper/Exception/CollectionMappingException.php index 22824db..30add6e 100644 --- a/src/JsonMapper/Exception/CollectionMappingException.php +++ b/src/JsonMapper/Exception/CollectionMappingException.php @@ -18,6 +18,10 @@ */ final class CollectionMappingException extends MappingException { + /** + * @param string $path Path to the collection that failed to map. + * @param string $actualType Type reported for the value that was expected to be iterable. + */ public function __construct(string $path, private readonly string $actualType) { parent::__construct( @@ -26,6 +30,14 @@ public function __construct(string $path, private readonly string $actualType) ); } + /** + * Returns the detected type of the value that could not be treated as iterable. + * + * Callers can surface the type to API consumers to explain why the mapper refused + * to process the collection. + * + * @return string Type information describing the non-iterable value. + */ public function getActualType(): string { return $this->actualType; diff --git a/src/JsonMapper/Exception/MappingException.php b/src/JsonMapper/Exception/MappingException.php index 6327a43..4931852 100644 --- a/src/JsonMapper/Exception/MappingException.php +++ b/src/JsonMapper/Exception/MappingException.php @@ -19,6 +19,12 @@ */ abstract class MappingException extends RuntimeException { + /** + * @param string $message Human readable description of the failure scenario. + * @param string $path JSON pointer or dotted path identifying the failing value. + * @param int $code Optional error code to bubble up to the caller. + * @param Throwable|null $previous Underlying cause, if the exception wraps another failure. + */ public function __construct( string $message, private readonly string $path, @@ -28,6 +34,14 @@ public function __construct( parent::__construct($message, $code, $previous); } + /** + * Returns the JSON path pointing to the value that could not be mapped. + * + * Callers can use the path to inform end users about the exact location of the + * mapping problem or to log structured diagnostics. + * + * @return string JSON pointer or dotted path describing the failing location. + */ public function getPath(): string { return $this->path; diff --git a/src/JsonMapper/Exception/MissingPropertyException.php b/src/JsonMapper/Exception/MissingPropertyException.php index bc3344d..8e3a72e 100644 --- a/src/JsonMapper/Exception/MissingPropertyException.php +++ b/src/JsonMapper/Exception/MissingPropertyException.php @@ -18,6 +18,11 @@ */ final class MissingPropertyException extends MappingException { + /** + * @param string $path Path indicating where the missing property should have been present. + * @param string $propertyName Name of the required property defined on the PHP target. + * @param class-string $className Fully qualified name of the DTO or object declaring the property. + */ public function __construct( string $path, private readonly string $propertyName, @@ -30,13 +35,24 @@ public function __construct( ); } + /** + * Returns the required property name that could not be resolved from the JSON input. + * + * Use this to inform API clients about the field they need to provide. + * + * @return string Name of the missing property. + */ public function getPropertyName(): string { return $this->propertyName; } /** - * @return class-string + * Provides the class in which the missing property is declared. + * + * Consumers may use the information to scope the validation error when working with nested DTOs. + * + * @return class-string Fully qualified class name declaring the missing property. */ public function getClassName(): string { diff --git a/src/JsonMapper/Exception/ReadonlyPropertyException.php b/src/JsonMapper/Exception/ReadonlyPropertyException.php index 48e5256..80c2687 100644 --- a/src/JsonMapper/Exception/ReadonlyPropertyException.php +++ b/src/JsonMapper/Exception/ReadonlyPropertyException.php @@ -18,6 +18,11 @@ */ final class ReadonlyPropertyException extends MappingException { + /** + * @param string $path Path pointing to the JSON field that tried to set the readonly property. + * @param string $property Name of the property that cannot be written. + * @param string $className Fully qualified class declaring the readonly property. + */ public function __construct(string $path, string $property, string $className) { parent::__construct( diff --git a/src/JsonMapper/Exception/TypeMismatchException.php b/src/JsonMapper/Exception/TypeMismatchException.php index 4c76130..14d9aae 100644 --- a/src/JsonMapper/Exception/TypeMismatchException.php +++ b/src/JsonMapper/Exception/TypeMismatchException.php @@ -18,6 +18,11 @@ */ final class TypeMismatchException extends MappingException { + /** + * @param string $path Path to the offending value inside the JSON payload. + * @param string $expectedType Type declared on the PHP target (FQCN or scalar type name). + * @param string $actualType Detected type of the JSON value that failed conversion. + */ public function __construct( string $path, private readonly string $expectedType, @@ -29,11 +34,27 @@ public function __construct( ); } + /** + * Returns the PHP type the mapper attempted to hydrate. + * + * Callers may use the information to build error messages that mirror the + * DTO or property contract. + * + * @return string Declared PHP type expected for the JSON value. + */ public function getExpectedType(): string { return $this->expectedType; } + /** + * Returns the actual type the mapper observed in the JSON payload. + * + * Consumers can combine the value with {@see getExpectedType()} to explain + * why the assignment failed. + * + * @return string Type reported for the source value. + */ public function getActualType(): string { return $this->actualType; diff --git a/src/JsonMapper/Exception/UnknownPropertyException.php b/src/JsonMapper/Exception/UnknownPropertyException.php index 2d81044..6661abd 100644 --- a/src/JsonMapper/Exception/UnknownPropertyException.php +++ b/src/JsonMapper/Exception/UnknownPropertyException.php @@ -18,6 +18,11 @@ */ final class UnknownPropertyException extends MappingException { + /** + * @param string $path Path to the JSON value that references the unknown property. + * @param string $propertyName Name of the property that does not exist on the PHP target. + * @param class-string $className Fully qualified name of the object that lacks the property. + */ public function __construct( string $path, private readonly string $propertyName, @@ -30,13 +35,25 @@ public function __construct( ); } + /** + * Returns the unknown property name as provided by the JSON payload. + * + * Callers can expose the value in validation errors so clients can remove + * unsupported fields. + * + * @return string Property name that could not be mapped. + */ public function getPropertyName(): string { return $this->propertyName; } /** - * @return class-string + * Provides the class for which the property is unknown. + * + * Consumers may use this to highlight which DTO rejected the incoming property. + * + * @return class-string Fully qualified class name without the referenced property. */ public function getClassName(): string {