From 7ca9b6cfd9b3a02979655516bdcd70e17f8b2745 Mon Sep 17 00:00:00 2001 From: Rico Sonntag Date: Fri, 14 Nov 2025 10:32:37 +0100 Subject: [PATCH] docs(context): expand mapping phpdoc coverage --- .../Configuration/JsonMapperConfiguration.php | 62 ++++++++++++++- src/JsonMapper/Context/MappingContext.php | 79 +++++++++++++++++-- src/JsonMapper/Context/MappingError.php | 20 +++++ 3 files changed, 152 insertions(+), 9 deletions(-) diff --git a/src/JsonMapper/Configuration/JsonMapperConfiguration.php b/src/JsonMapper/Configuration/JsonMapperConfiguration.php index e06578f..a240670 100644 --- a/src/JsonMapper/Configuration/JsonMapperConfiguration.php +++ b/src/JsonMapper/Configuration/JsonMapperConfiguration.php @@ -23,6 +23,14 @@ final class JsonMapperConfiguration { /** * Creates a new configuration instance with optional overrides. + * + * @param bool $strictMode Whether unknown/missing properties should trigger errors + * @param bool $collectErrors Whether encountered mapping errors should be collected + * @param bool $emptyStringIsNull Whether empty strings are converted to null + * @param bool $ignoreUnknownProperties Whether properties missing in the destination type are ignored + * @param bool $treatNullAsEmptyCollection Whether null collections are replaced with empty collections + * @param string $defaultDateFormat Default `DateTimeInterface` format used for serialization/deserialization + * @param bool $allowScalarToObjectCasting Whether scalars can be coerced into objects when supported */ public function __construct( private bool $strictMode = false, @@ -37,6 +45,8 @@ public function __construct( /** * Returns a lenient configuration with default settings. + * + * @return self Configuration tuned for permissive mappings */ public static function lenient(): self { @@ -45,6 +55,8 @@ public static function lenient(): self /** * Returns a strict configuration that reports unknown and missing properties. + * + * @return self Configuration tuned for strict validation */ public static function strict(): self { @@ -55,6 +67,8 @@ public static function strict(): self * Restores a configuration instance from the provided array. * * @param array $data Configuration values indexed by property name + * + * @return self Configuration populated with the provided overrides */ public static function fromArray(array $data): self { @@ -77,6 +91,8 @@ public static function fromArray(array $data): self /** * Restores a configuration instance based on the provided mapping context. + * + * @return self Configuration aligned with the supplied context options */ public static function fromContext(MappingContext $context): self { @@ -94,7 +110,7 @@ public static function fromContext(MappingContext $context): self /** * Serializes the configuration into an array representation. * - * @return array + * @return array Scalar configuration flags indexed by option name */ public function toArray(): array { @@ -112,7 +128,7 @@ public function toArray(): array /** * Converts the configuration to mapping context options. * - * @return array + * @return array Mapping context option bag compatible with {@see MappingContext} */ public function toOptions(): array { @@ -129,6 +145,8 @@ public function toOptions(): array /** * Indicates whether strict mode is enabled. + * + * @return bool True when unknown or missing properties are treated as failures */ public function isStrictMode(): bool { @@ -137,6 +155,8 @@ public function isStrictMode(): bool /** * Indicates whether errors should be collected during mapping. + * + * @return bool True when mapper should aggregate errors instead of failing fast */ public function shouldCollectErrors(): bool { @@ -145,6 +165,8 @@ public function shouldCollectErrors(): bool /** * Indicates whether empty strings should be treated as null values. + * + * @return bool True when empty string values are mapped to null */ public function shouldTreatEmptyStringAsNull(): bool { @@ -153,6 +175,8 @@ public function shouldTreatEmptyStringAsNull(): bool /** * Indicates whether unknown properties should be ignored. + * + * @return bool True when incoming properties without a target counterpart are skipped */ public function shouldIgnoreUnknownProperties(): bool { @@ -161,6 +185,8 @@ public function shouldIgnoreUnknownProperties(): bool /** * Indicates whether null collections should be converted to empty collections. + * + * @return bool True when null collection values are normalised to empty collections */ public function shouldTreatNullAsEmptyCollection(): bool { @@ -169,6 +195,8 @@ public function shouldTreatNullAsEmptyCollection(): bool /** * Returns the default date format used for date conversions. + * + * @return string Date format string compatible with {@see DateTimeInterface::format()} */ public function getDefaultDateFormat(): string { @@ -177,6 +205,8 @@ public function getDefaultDateFormat(): string /** * Indicates whether scalar values may be cast to objects. + * + * @return bool True when scalar-to-object coercion should be attempted */ public function shouldAllowScalarToObjectCasting(): bool { @@ -185,6 +215,10 @@ public function shouldAllowScalarToObjectCasting(): bool /** * Returns a copy with the strict mode flag toggled. + * + * @param bool $enabled Whether strict mode should be enabled for the clone + * + * @return self Cloned configuration reflecting the requested strictness */ public function withStrictMode(bool $enabled): self { @@ -196,6 +230,10 @@ public function withStrictMode(bool $enabled): self /** * Returns a copy with the error collection flag toggled. + * + * @param bool $collect Whether errors should be aggregated in the clone + * + * @return self Cloned configuration applying the collection behaviour */ public function withErrorCollection(bool $collect): self { @@ -207,6 +245,10 @@ public function withErrorCollection(bool $collect): self /** * Returns a copy with the empty-string-as-null flag toggled. + * + * @param bool $enabled Whether empty strings should become null for the clone + * + * @return self Cloned configuration applying the string handling behaviour */ public function withEmptyStringAsNull(bool $enabled): self { @@ -218,6 +260,10 @@ public function withEmptyStringAsNull(bool $enabled): self /** * Returns a copy with the ignore-unknown-properties flag toggled. + * + * @param bool $enabled Whether unknown properties should be ignored in the clone + * + * @return self Cloned configuration reflecting the requested behaviour */ public function withIgnoreUnknownProperties(bool $enabled): self { @@ -229,6 +275,10 @@ public function withIgnoreUnknownProperties(bool $enabled): self /** * Returns a copy with the treat-null-as-empty-collection flag toggled. + * + * @param bool $enabled Whether null collections should be normalised for the clone + * + * @return self Cloned configuration applying the collection normalisation behaviour */ public function withTreatNullAsEmptyCollection(bool $enabled): self { @@ -240,6 +290,10 @@ public function withTreatNullAsEmptyCollection(bool $enabled): self /** * Returns a copy with a different default date format. + * + * @param string $format Desired default format compatible with {@see DateTimeInterface::format()} + * + * @return self Cloned configuration containing the new date format */ public function withDefaultDateFormat(string $format): self { @@ -251,6 +305,10 @@ public function withDefaultDateFormat(string $format): self /** * Returns a copy with the scalar-to-object casting flag toggled. + * + * @param bool $enabled Whether scalar values should be coerced to objects in the clone + * + * @return self Cloned configuration defining the scalar coercion behaviour */ public function withScalarToObjectCasting(bool $enabled): self { diff --git a/src/JsonMapper/Context/MappingContext.php b/src/JsonMapper/Context/MappingContext.php index 352fe78..e163424 100644 --- a/src/JsonMapper/Context/MappingContext.php +++ b/src/JsonMapper/Context/MappingContext.php @@ -54,8 +54,8 @@ final class MappingContext private array $options; /** - * @param mixed $rootInput The original JSON payload - * @param array $options Context options + * @param mixed $rootInput The original JSON payload handed to the mapper + * @param array $options Context options influencing mapping behaviour */ public function __construct(private readonly mixed $rootInput, array $options = []) { @@ -64,6 +64,8 @@ public function __construct(private readonly mixed $rootInput, array $options = /** * Returns the root JSON input value. + * + * @return mixed Original payload that initiated the current mapping run */ public function getRootInput(): mixed { @@ -72,6 +74,8 @@ public function getRootInput(): mixed /** * Returns the current path inside the JSON structure. + * + * @return string Dot-separated path beginning with the root symbol */ public function getPath(): string { @@ -85,7 +89,10 @@ public function getPath(): string /** * Executes the callback while appending the provided segment to the path. * - * @param callable(self):mixed $callback + * @param string|int $segment Segment appended to the path for the callback execution + * @param callable(self):mixed $callback Callback executed while the segment is in place + * + * @return mixed Result produced by the callback */ public function withPathSegment(string|int $segment, callable $callback): mixed { @@ -100,6 +107,11 @@ public function withPathSegment(string|int $segment, callable $callback): mixed /** * Stores the error message for later consumption. + * + * @param string $message Human-readable description of the failure + * @param MappingException|null $exception Optional exception associated with the failure + * + * @return void */ public function addError(string $message, ?MappingException $exception = null): void { @@ -112,6 +124,10 @@ public function addError(string $message, ?MappingException $exception = null): /** * Stores the exception and message for later consumption. + * + * @param MappingException $exception Exception raised during mapping + * + * @return void */ public function recordException(MappingException $exception): void { @@ -121,7 +137,7 @@ public function recordException(MappingException $exception): void /** * Returns collected mapping errors. * - * @return list + * @return list Error messages collected so far */ public function getErrors(): array { @@ -131,26 +147,51 @@ public function getErrors(): array ); } + /** + * Indicates whether mapping errors should be collected instead of throwing immediately. + * + * @return bool True when error aggregation is enabled + */ public function shouldCollectErrors(): bool { return (bool) ($this->options[self::OPTION_COLLECT_ERRORS] ?? true); } + /** + * Indicates whether the mapper operates in strict mode. + * + * @return bool True when missing or unknown properties result in failures + */ public function isStrictMode(): bool { return (bool) ($this->options[self::OPTION_STRICT_MODE] ?? false); } + /** + * Indicates whether unknown properties from the input should be ignored. + * + * @return bool True when extra input properties are silently skipped + */ public function shouldIgnoreUnknownProperties(): bool { return (bool) ($this->options[self::OPTION_IGNORE_UNKNOWN_PROPERTIES] ?? false); } + /** + * Indicates whether null collections should be normalised to empty collections. + * + * @return bool True when null collections are replaced with empty instances + */ public function shouldTreatNullAsEmptyCollection(): bool { return (bool) ($this->options[self::OPTION_TREAT_NULL_AS_EMPTY_COLLECTION] ?? false); } + /** + * Returns the default date format used for date conversions. + * + * @return string Date format string compatible with {@see DateTimeInterface::format()} + */ public function getDefaultDateFormat(): string { $format = $this->options[self::OPTION_DEFAULT_DATE_FORMAT] ?? DateTimeInterface::ATOM; @@ -162,6 +203,11 @@ public function getDefaultDateFormat(): string return $format; } + /** + * Indicates whether scalar values are allowed to be coerced into objects when possible. + * + * @return bool True when scalar-to-object casting is enabled + */ public function shouldAllowScalarToObjectCasting(): bool { return (bool) ($this->options[self::OPTION_ALLOW_SCALAR_TO_OBJECT_CASTING] ?? false); @@ -170,7 +216,7 @@ public function shouldAllowScalarToObjectCasting(): bool /** * Returns all options. * - * @return array + * @return array Associative array of context options */ public function getOptions(): array { @@ -179,6 +225,11 @@ public function getOptions(): array /** * Returns a single option by name. + * + * @param string $name Option name as defined by the {@see self::OPTION_*} constants + * @param mixed $default Fallback value returned when the option is not set + * + * @return mixed Stored option value or the provided default */ public function getOption(string $name, mixed $default = null): mixed { @@ -188,7 +239,9 @@ public function getOption(string $name, mixed $default = null): mixed /** * Replaces the stored options. * - * @param array $options + * @param array $options Complete set of options to store + * + * @return void */ public function replaceOptions(array $options): void { @@ -198,18 +251,30 @@ public function replaceOptions(array $options): void /** * Returns collected mapping errors with contextual details. * - * @return list + * @return list Error records including message, path, and exception */ public function getErrorRecords(): array { return $this->errorRecords; } + /** + * Returns the number of collected errors currently stored in the context. + * + * @return int Count of collected errors + */ public function getErrorCount(): int { return count($this->errorRecords); } + /** + * Truncates the stored errors to the given number of entries. + * + * @param int $count Maximum number of records to retain + * + * @return void + */ public function trimErrors(int $count): void { $this->errorRecords = array_slice($this->errorRecords, 0, $count); diff --git a/src/JsonMapper/Context/MappingError.php b/src/JsonMapper/Context/MappingError.php index 568bcbe..6aa9065 100644 --- a/src/JsonMapper/Context/MappingError.php +++ b/src/JsonMapper/Context/MappingError.php @@ -18,6 +18,11 @@ */ final readonly class MappingError { + /** + * @param string $path JSON path pointing to the failing property + * @param string $message Human-readable description of the failure + * @param MappingException|null $exception Exception that triggered the error, when available + */ public function __construct( private string $path, private string $message, @@ -25,16 +30,31 @@ public function __construct( ) { } + /** + * Returns the JSON path that triggered the error. + * + * @return string Path formatted using dot notation starting at the root symbol + */ public function getPath(): string { return $this->path; } + /** + * Returns the descriptive error message. + * + * @return string Human-readable explanation of the failure + */ public function getMessage(): string { return $this->message; } + /** + * Returns the exception instance associated with the error, when one was recorded. + * + * @return MappingException|null Underlying exception or null when only a message was recorded + */ public function getException(): ?MappingException { return $this->exception;