Refactor mapper responsibilities into dedicated services

composer.json

@@ -19,8 +19,7 @@
         "symfony/property-info": "^7.3",
         "symfony/property-access": "^7.3",
         "symfony/type-info": "^7.3",
-        "doctrine/inflector": "^2.0",
-        "doctrine/annotations": "^2.0"
+        "doctrine/inflector": "^2.0"
     },
     "require-dev": {
         "friendsofphp/php-cs-fixer": "^3.65",
@@ -77,7 +76,7 @@
             "@ci:rector --dry-run"
         ],
         "ci:test:php:cpd": [
-            "npx -y jscpd@latest --config .jscpd.json"
+            "npx jscpd --config .jscpd.json"
         ],
         "ci:test:php:unit": [
             "phpunit --configuration phpunit.xml"

docs/API.md

@@ -0,0 +1,149 @@
+# JsonMapper API reference
+
+This document summarises the public surface of the JsonMapper package. All classes are namespaced under `MagicSunday\\JsonMapper` unless stated otherwise.
+
+## JsonMapper (final)
+The `JsonMapper` class is the main entry point for mapping arbitrary JSON structures to PHP objects. The class is `final`; prefer composition over inheritance.
+
+### Factory helper
+```php
+<?php
+declare(strict_types=1);
+
+use MagicSunday\JsonMapper;
+
+$mapper = JsonMapper::createWithDefaults();
+```
+
+The helper wires the Symfony `PropertyInfoExtractor` (reflection + PhpDoc) and a default `PropertyAccessor`. Use the constructor described below when you need custom extractors, caches, or accessors.
+
+### Constructor
+```php
+<?php
+declare(strict_types=1);
+
+use MagicSunday\JsonMapper;
+use Symfony\Component\Cache\Adapter\ArrayAdapter;
+use Symfony\Component\PropertyAccess\PropertyAccess;
+use Symfony\Component\PropertyInfo\Extractor\PhpDocExtractor;
+use Symfony\Component\PropertyInfo\Extractor\ReflectionExtractor;
+use Symfony\Component\PropertyInfo\PropertyInfoExtractor;
+
+// Describe DTO metadata and wiring through Symfony extractors.
+$propertyInfo = new PropertyInfoExtractor(
+    listExtractors: [new ReflectionExtractor()],
+    typeExtractors: [new PhpDocExtractor()],
+);
+$propertyAccessor = PropertyAccess::createPropertyAccessor();
+
+// Cache resolved Type metadata for subsequent mappings.
+$typeCache = new ArrayAdapter();
+
+$mapper = new JsonMapper($propertyInfo, $propertyAccessor, classMap: [], typeCache: $typeCache);
+
+var_dump($mapper::class);
+```
+
+* `$classMap` allows overriding resolved target classes. Use `addCustomClassMapEntry()` for runtime registration.
+* `$typeCache` enables caching of resolved Symfony `Type` instances. Any PSR-6 cache pool is supported.
+* `$config` provides the default configuration that will be cloned for every mapping operation.
+
+### Methods
+
+| Method | Description |
+| --- | --- |
+| `addTypeHandler(TypeHandlerInterface $handler): self` | Registers a reusable conversion strategy for a specific type. |
+| `addType(string $type, Closure $closure): self` | Deprecated shortcut for registering closure-based handlers. Prefer `addTypeHandler()`. |
+| `addCustomClassMapEntry(string $className, Closure $resolver): self` | Adds or replaces a class map entry. The resolver receives JSON data (and optionally the current `MappingContext`). |
+| `map(mixed $json, ?string $className = null, ?string $collectionClassName = null, ?MappingContext $context = null, ?JsonMapperConfiguration $configuration = null): mixed` | Maps the provided JSON payload to the requested class or collection. |
+| `mapWithReport(mixed $json, ?string $className = null, ?string $collectionClassName = null, ?JsonMapperConfiguration $configuration = null): MappingResult` | Maps data and returns a `MappingResult` containing both the mapped value and an error report. |
+
+> `map()` and `mapWithReport()` accept JSON decoded into arrays or objects (`json_decode(..., associative: false)` is recommended). Collections require either an explicit collection class name or collection PHPDoc (`@extends`) metadata.
+
+## JsonMapperConfiguration (final)
+The `JsonMapperConfiguration` class encapsulates mapping options. All configuration methods return a **new** instance; treat instances as immutable value objects.
+
+### Factory helpers
+* `JsonMapperConfiguration::lenient()` – default, tolerant configuration.
+* `JsonMapperConfiguration::strict()` – enables strict mode (missing and unknown properties raise `MappingException`).
+* `JsonMapperConfiguration::fromArray(array $data)` – rebuilds a configuration from persisted values.
+* `JsonMapperConfiguration::fromContext(MappingContext $context)` – reconstructs a configuration for an existing mapping run.
+
+### Withers
+Each `with*` method toggles a single option and returns a clone:
+
+| Method | Purpose |
+| --- | --- |
+| `withStrictMode(bool $enabled)` | Enable strict validation. |
+| `withCollectErrors(bool $enabled)` | Collect errors instead of failing fast. Required for `mapWithReport()`. |
+| `withTreatEmptyStringAsNull(bool $enabled)` | Map empty strings to `null`. |
+| `withIgnoreUnknownProperties(bool $enabled)` | Skip unmapped JSON keys. |
+| `withTreatNullAsEmptyCollection(bool $enabled)` | Replace `null` collections with their default value. |
+| `withDefaultDateFormat(string $format)` | Configure the default `DateTimeInterface` parsing format. |
+| `withScalarToObjectCasting(bool $enabled)` | Allow casting scalar values to object types when possible. |
+
+Use `toOptions()` to feed configuration data into a `MappingContext`, or `toArray()` to persist settings.
+
+## Property name converters
+`CamelCasePropertyNameConverter` implements `PropertyNameConverterInterface` and is declared `final`. Instantiate it when JSON keys use snake case:
+
+```php
+<?php
+declare(strict_types=1);
+
+require __DIR__ . '/vendor/autoload.php';
+
+use MagicSunday\JsonMapper;
+use MagicSunday\JsonMapper\Converter\CamelCasePropertyNameConverter;
+
+// Translate snake_case JSON keys into camelCase DTO properties.
+$nameConverter = new CamelCasePropertyNameConverter();
+
+$mapper = JsonMapper::createWithDefaults($nameConverter);
+
+var_dump($mapper::class);
+```
+
+## Custom type handlers
+Implement `Value\TypeHandlerInterface` to plug in custom conversion logic:
+
+```php
+<?php
+declare(strict_types=1);
+
+require __DIR__ . '/vendor/autoload.php';
+
+use MagicSunday\JsonMapper\Context\MappingContext;
+use MagicSunday\JsonMapper\Value\TypeHandlerInterface;
+use Symfony\Component\TypeInfo\Type;
+use Symfony\Component\TypeInfo\Type\ObjectType;
+
+final class FakeUuid
+{
+    private function __construct(private string $value)
+    {
+    }
+
+    public static function fromString(string $value): self
+    {
+        return new self($value);
+    }
+}
+
+final class UuidTypeHandler implements TypeHandlerInterface
+{
+    public function supports(Type $type, mixed $value): bool
+    {
+        // Only handle FakeUuid targets to keep conversion focused.
+        return $type instanceof ObjectType && $type->getClassName() === FakeUuid::class;
+    }
+
+    public function convert(Type $type, mixed $value, MappingContext $context): FakeUuid
+    {
+        // Build the value object from the incoming scalar payload.
+        return FakeUuid::fromString((string) $value);
+    }
+}
+```
+
+Register handlers via `JsonMapper::addTypeHandler()` to make them available for all mappings.

docs/recipes/custom-name-converter.md

@@ -0,0 +1,49 @@
+# Using a custom name converter
+
+Property name converters translate JSON keys to PHP property names. JsonMapper provides `CamelCasePropertyNameConverter` out of the box and allows you to supply your own implementation of `PropertyNameConverterInterface`.
+
+```php
+<?php
+declare(strict_types=1);
+
+namespace App\Converter;
+
+use MagicSunday\JsonMapper\Converter\PropertyNameConverterInterface;
+
+final class UpperSnakeCaseConverter implements PropertyNameConverterInterface
+{
+    public function convert(string $name): string
+    {
+        // Normalise keys by removing underscores and lowercasing them.
+        return strtolower(str_replace('_', '', $name));
+    }
+}
+```
+
+```php
+<?php
+declare(strict_types=1);
+
+require __DIR__ . '/vendor/autoload.php';
+
+use App\Converter\UpperSnakeCaseConverter;
+use MagicSunday\JsonMapper;
+use Symfony\Component\PropertyAccess\PropertyAccess;
+use Symfony\Component\PropertyInfo\Extractor\PhpDocExtractor;
+use Symfony\Component\PropertyInfo\Extractor\ReflectionExtractor;
+use Symfony\Component\PropertyInfo\PropertyInfoExtractor;
+
+// Collect metadata and provide the custom converter.
+$propertyInfo = new PropertyInfoExtractor(
+    listExtractors: [new ReflectionExtractor()],
+    typeExtractors: [new PhpDocExtractor()],
+);
+$propertyAccessor = PropertyAccess::createPropertyAccessor();
+$converter = new UpperSnakeCaseConverter();
+
+$mapper = new JsonMapper($propertyInfo, $propertyAccessor, $converter);
+```
+
+Name converters are stateless and should be declared `final`. They are applied to every property access during mapping, so keep the implementation idempotent and efficient.
+
+Test coverage: `tests/JsonMapper/DocsCustomNameConverterTest.php`.

docs/recipes/mapping-with-enums.md

@@ -0,0 +1,60 @@
+# Mapping JSON to PHP enums
+
+JsonMapper can map backed enums transparently when the target property is typed with the enum class. The built-in `EnumValueConversionStrategy` handles the conversion from scalars to enum cases.
+
+```php
+<?php
+declare(strict_types=1);
+
+namespace App\Dto;
+
+enum Status: string
+{
+    case Draft = 'draft';
+    case Published = 'published';
+}
+
+final class Article
+{
+    public string $title;
+    public Status $status;
+}
+```
+
+```php
+<?php
+declare(strict_types=1);
+
+require __DIR__ . '/vendor/autoload.php';
+
+use App\Dto\Article;
+use App\Dto\Status;
+use MagicSunday\JsonMapper;
+use Symfony\Component\PropertyAccess\PropertyAccess;
+use Symfony\Component\PropertyInfo\Extractor\PhpDocExtractor;
+use Symfony\Component\PropertyInfo\Extractor\ReflectionExtractor;
+use Symfony\Component\PropertyInfo\PropertyInfoExtractor;
+
+// Decode the incoming JSON payload into an object.
+$json = json_decode('{
+    "title": "Enum mapping",
+    "status": "published"
+}', associative: false, flags: JSON_THROW_ON_ERROR);
+
+// Wire up the mapper with reflection and PhpDoc metadata.
+$propertyInfo = new PropertyInfoExtractor(
+    listExtractors: [new ReflectionExtractor()],
+    typeExtractors: [new PhpDocExtractor()],
+);
+$propertyAccessor = PropertyAccess::createPropertyAccessor();
+
+$mapper = new JsonMapper($propertyInfo, $propertyAccessor);
+$article = $mapper->map($json, Article::class);
+
+assert($article instanceof Article);
+assert($article->status === Status::Published);
+```
+
+The mapper validates enum values. In strict mode (`JsonMapperConfiguration::strict()`), an invalid enum value results in a `TypeMismatchException` instead of populating the property.
+
+Test coverage: `tests/JsonMapperTest.php::mapBackedEnumFromString` and `tests/JsonMapper/JsonMapperErrorHandlingTest.php::itReportsInvalidEnumValuesInLenientMode`.

docs/recipes/nested-collections.md

@@ -0,0 +1,92 @@
+# Mapping nested collections
+
+Collections of collections require explicit metadata so JsonMapper can determine the element types at every level.
+
+```php
+<?php
+declare(strict_types=1);
+
+namespace App\Dto;
+
+use ArrayObject;
+
+final class Tag
+{
+    public string $name;
+}
+
+/**
+ * @extends ArrayObject<int, Tag>
+ */
+final class TagCollection extends ArrayObject
+{
+}
+
+/**
+ * @extends ArrayObject<int, TagCollection>
+ */
+final class NestedTagCollection extends ArrayObject
+{
+}
+
+final class Article
+{
+    /** @var NestedTagCollection */
+    public NestedTagCollection $tags;
+}
+
+/**
+ * @extends ArrayObject<int, Article>
+ */
+final class ArticleCollection extends ArrayObject
+{
+}
+```
+
+```php
+<?php
+declare(strict_types=1);
+
+require __DIR__ . '/vendor/autoload.php';
+
+use App\Dto\Article;
+use App\Dto\ArticleCollection;
+use App\Dto\NestedTagCollection;
+use App\Dto\TagCollection;
+use MagicSunday\JsonMapper;
+use Symfony\Component\PropertyAccess\PropertyAccess;
+use Symfony\Component\PropertyInfo\Extractor\PhpDocExtractor;
+use Symfony\Component\PropertyInfo\Extractor\ReflectionExtractor;
+use Symfony\Component\PropertyInfo\PropertyInfoExtractor;
+
+// Decode an array of nested tag collections.
+$json = json_decode('[
+    {
+        "tags": [
+            [{"name": "php"}],
+            [{"name": "json"}]
+        ]
+    }
+]', associative: false, flags: JSON_THROW_ON_ERROR);
+
+// Configure JsonMapper with the extractors that understand collection metadata.
+$propertyInfo = new PropertyInfoExtractor(
+    listExtractors: [new ReflectionExtractor()],
+    typeExtractors: [new PhpDocExtractor()],
+);
+$propertyAccessor = PropertyAccess::createPropertyAccessor();
+
+
+// Map the nested structure into DTOs and typed collections.
+$mapper = new JsonMapper($propertyInfo, $propertyAccessor);
+$articles = $mapper->map($json, Article::class, ArticleCollection::class);
+
+assert($articles instanceof ArticleCollection);
+assert($articles[0] instanceof Article);
+assert($articles[0]->tags instanceof NestedTagCollection);
+```
+
+Each custom collection advertises its value type through the `@extends` PHPDoc annotation, allowing the mapper to recurse through nested structures.
+
+Test coverage: `tests/JsonMapper/DocsNestedCollectionsTest.php`.
+