From 6a29eaedf2433c9b9a72f6f2ff866fc402560479 Mon Sep 17 00:00:00 2001 From: Rico Sonntag Date: Fri, 14 Nov 2025 10:33:06 +0100 Subject: [PATCH] docs: clarify phpdoc for collection resolvers --- .../Collection/CollectionDocBlockTypeResolver.php | 9 +++++++-- src/JsonMapper/Collection/CollectionFactory.php | 12 +++++++++--- .../Collection/CollectionFactoryInterface.php | 12 ++++++++---- src/JsonMapper/Resolver/ClassResolver.php | 14 +++++++------- 4 files changed, 31 insertions(+), 16 deletions(-) diff --git a/src/JsonMapper/Collection/CollectionDocBlockTypeResolver.php b/src/JsonMapper/Collection/CollectionDocBlockTypeResolver.php index 3850226..3afd078 100644 --- a/src/JsonMapper/Collection/CollectionDocBlockTypeResolver.php +++ b/src/JsonMapper/Collection/CollectionDocBlockTypeResolver.php @@ -36,6 +36,11 @@ final class CollectionDocBlockTypeResolver { private DocBlockFactoryInterface $docBlockFactory; + /** + * @param DocBlockFactoryInterface|null $docBlockFactory Optional docblock factory used to parse collection annotations. + * @param ContextFactory $contextFactory Factory for building type resolution contexts for reflected classes. + * @param PhpDocTypeHelper $phpDocTypeHelper Helper translating DocBlock types into Symfony TypeInfo representations. + */ public function __construct( ?DocBlockFactoryInterface $docBlockFactory = null, private readonly ContextFactory $contextFactory = new ContextFactory(), @@ -56,9 +61,9 @@ public function __construct( /** * Attempts to resolve a {@see CollectionType} from the collection class PHPDoc. * - * @param class-string $collectionClassName + * @param class-string $collectionClassName Fully qualified class name of the collection wrapper to inspect. * - * @return CollectionType>|null + * @return CollectionType>|null Resolved collection metadata or null when no matching PHPDoc is available. */ public function resolve(string $collectionClassName): ?CollectionType { diff --git a/src/JsonMapper/Collection/CollectionFactory.php b/src/JsonMapper/Collection/CollectionFactory.php index 4680abb..e0b8496 100644 --- a/src/JsonMapper/Collection/CollectionFactory.php +++ b/src/JsonMapper/Collection/CollectionFactory.php @@ -54,7 +54,11 @@ public function __construct( /** * Converts the provided iterable JSON structure to a PHP array. * - * @return array|null + * @param mixed $json Raw JSON data representing the collection to hydrate. + * @param Type $valueType Type descriptor for individual collection entries. + * @param MappingContext $context Active mapping context providing path and strictness information. + * + * @return array|null Normalised collection data or null when conversion fails. */ public function mapIterable(mixed $json, Type $valueType, MappingContext $context): ?array { @@ -96,9 +100,11 @@ public function mapIterable(mixed $json, Type $valueType, MappingContext $contex /** * Builds a collection based on the specified collection type description. * - * @param CollectionType> $type + * @param CollectionType> $type Resolved collection metadata from docblocks or attributes. + * @param mixed $json Raw JSON payload containing the collection values. + * @param MappingContext $context Mapping context controlling strict mode and error tracking. * - * @return object|array|null + * @return object|array|null Instantiated collection wrapper or the normalised array values. */ public function fromCollectionType(CollectionType $type, mixed $json, MappingContext $context): array|object|null { diff --git a/src/JsonMapper/Collection/CollectionFactoryInterface.php b/src/JsonMapper/Collection/CollectionFactoryInterface.php index eee3018..1ca8fbf 100644 --- a/src/JsonMapper/Collection/CollectionFactoryInterface.php +++ b/src/JsonMapper/Collection/CollectionFactoryInterface.php @@ -32,18 +32,22 @@ interface CollectionFactoryInterface /** * Converts the provided iterable JSON structure to a PHP array. * - * @param Type $valueType The type description for the collection values. + * @param mixed $json Raw JSON data representing the iterable input to normalise. + * @param Type $valueType Type description for the collection values. + * @param MappingContext $context Active mapping context carrying strictness and error reporting configuration. * - * @return array|null + * @return array|null Normalised array representation or null when conversion fails. */ public function mapIterable(mixed $json, Type $valueType, MappingContext $context): ?array; /** * Builds a collection based on the specified collection type description. * - * @param CollectionType> $type The collection type metadata extracted from PHPStan/Psalm annotations. + * @param CollectionType> $type Resolved collection metadata from PHPDoc or attributes. + * @param mixed $json Raw JSON payload containing the collection values. + * @param MappingContext $context Mapping context controlling strict mode and error recording. * - * @return array|object|null + * @return array|object|null Instantiated collection wrapper or the normalised array values. */ public function fromCollectionType(CollectionType $type, mixed $json, MappingContext $context): mixed; } diff --git a/src/JsonMapper/Resolver/ClassResolver.php b/src/JsonMapper/Resolver/ClassResolver.php index c19bf7f..d481bbd 100644 --- a/src/JsonMapper/Resolver/ClassResolver.php +++ b/src/JsonMapper/Resolver/ClassResolver.php @@ -36,7 +36,7 @@ final class ClassResolver private array $classMap; /** - * @param array $classMap + * @param array $classMap Map of base class names to explicit targets or resolver callbacks. * * @phpstan-param array $classMap */ @@ -48,8 +48,8 @@ public function __construct(array $classMap = []) /** * Adds a custom resolution rule. * - * @param class-string $className - * @param Closure(mixed):class-string|Closure(mixed, MappingContext):class-string $resolver + * @param class-string $className Base class or interface the resolver handles. + * @param Closure(mixed):class-string|Closure(mixed, MappingContext):class-string $resolver Callback returning a concrete class based on the JSON payload and optional mapping context. * * @phpstan-param class-string $className * @phpstan-param Closure(mixed):class-string|Closure(mixed, MappingContext):class-string $resolver @@ -63,11 +63,11 @@ public function add(string $className, Closure $resolver): void /** * Resolves the class name for the provided JSON payload. * - * @param class-string $className - * @param mixed $json - * @param MappingContext $context + * @param class-string $className Base class name configured in the resolver map. + * @param mixed $json Raw JSON fragment inspected to determine the target class. + * @param MappingContext $context Mapping context passed to resolution callbacks when required. * - * @return class-string + * @return class-string Fully-qualified class name that should be instantiated for the payload. */ public function resolve(string $className, mixed $json, MappingContext $context): string {