Data Mapper Bundle Laravel Package

Getting Started

Read this first: the package is deprecated. The upstream project is closed and the README explicitly points new applications at troytft/rest-api-bundle. Treat this assessment as guidance for maintaining an existing integration or for a short-lived migration, not for greenfield adoption.

Minimal steps for a legacy project:

1. Pin an exact version in composer.json — there will be no patch releases:

   composer require troytft/data-mapper-bundle:0.13.*
   

2. Register the bundle in config/bundles.php:

   Troytf\DataMapperBundle\DataMapperBundle::class => ['all' => true],
   

3. Look at tests/ in the repository before the README. With 8 stars and no docs site, the test suite is the only reliable specification of supported mapping features and edge cases.
4. Check composer.json for the PHP and Symfony constraints. This package predates Symfony 6 attributes in many places, so verify it actually boots on your Symfony version before writing any code against it.
5. First use case: map an incoming request array (e.g. a decoded JSON payload) into a typed DTO or entity. Instantiate the mapper service, pass the array and target class, and confirm the result before layering validation or persistence on top.

If you are on a modern Symfony stack and only need array→object hydration, evaluate symfony/serializer with the ObjectNormalizer first — it is maintained, documented, and covers most of what this bundle offers.

Implementation Patterns

Inject the mapper, don't instantiate it. The bundle's value is the DI wiring around the underlying troytft/data-mapper library. Resolve the mapper from the container so configuration and custom type handlers are picked up:

public function __construct(private DataMapper $dataMapper) {}

Request → DTO in a controller. The typical day-to-day flow is: decode the payload, map to a DTO, validate, then hand off to a service. Keep the mapping as the first step so downstream code only ever sees typed objects.

$dto = $this->dataMapper->map(CreateUserRequest::class, $request->toArray());

Nested objects and collections. The mapper's main differentiator over plain reflection hydration is nested mapping — a property typed as another DTO, or array<ItemDTO>, gets mapped recursively. Model your DTOs so nesting is explicit in property types; rely on that rather than manual foreach post-processing, which defeats the purpose.

DTO → Entity as a separate step. Resist mapping straight into Doctrine entities. Map into a DTO, validate it, then have a dedicated service copy fields onto the entity. This keeps the mapper away from proxy objects and lazy collections, which are a common source of confusing failures.

Custom type handlers for value objects. For Money, Email, Uuid, etc., register a custom mapper/normalizer rather than accepting stringly-typed properties. This is the intended extension point and the cleanest way to keep mapping logic out of controllers.

Wrap it in your own thin service. Because the package is unmaintained, put a single App\Mapping\Mapper facade in front of it. When you eventually migrate to the Symfony serializer, you change one class instead of grepping every controller.

Gotchas and Tips

• No security or bug fixes will ever land. If the mapper touches user-supplied arrays, audit it yourself. Do not expose it to untrusted input without validation on the other side.
• Missing vs. null vs. empty. Decide early whether an absent key should leave the property at its default, set it to null, or throw. Verify actual behavior in the tests — this is where most silent bugs originate, especially for nullable nested DTOs and empty collections.
• Strict types and coercion. Scalar coercion (string "1" → int, "true" → bool) is convenient but can mask bad client payloads. If your DTOs declare strict_types=1, test what happens with mismatched input rather than assuming an exception.
• Recursion. Circular or self-referencing DTO graphs can loop or blow the stack. Keep DTO graphs acyclic and shallow.
• Autowiring surprises. If the mapper service isn't autowirable, check services.xml/services.yaml inside the bundle's Resources/config and alias the service ID explicitly in your app config.
• Debugging tips. Dump the raw input array and the mapped object side by side; failures are usually a key-name mismatch (snake_case payload vs. camelCase property, or a typo) rather than a mapper bug. Symfony's profiler and debug:container will confirm which mapper service you actually got.
• Version pinning. Composer will happily resolve a stale transitive dependency. Commit composer.lock and treat upgrades as manual review, not composer update.
• Migration path. Plan the move to symfony/serializer (ObjectNormalizer + custom normalizers) or to troytft/rest-api-bundle if you want to stay in the same ecosystem. The DTOs you write here port over almost unchanged; it is the mapping configuration and custom handlers that need rewriting — so keep custom handler classes small and single-purpose.
• Document your usage internally. With no upstream docs and an abandoned codebase, a short internal README describing which mapping features you rely on is worth more than any external resource.