Data Mapper Bundle Laravel Package

Getting Started

• Install with caution. The package is abandoned (last release 2016-02-29, 0 stars, 0 dependents). Before adding it, verify PHP and Symfony compatibility:

  composer require thruster/data-mapper-bundle
  

  If Composer fails on modern PHP/Symfony, you are likely looking at a Symfony 2.x/3.x-era bundle. Pin your platform config or avoid it for new projects.
• Register the bundle. In Symfony 2/3 add it to AppKernel.php; in Symfony 4+ add it to config/bundles.php only if the bundle is actually Flex-compatible. The bundle alias is likely ThrusterDataMapperBundle or thruster_data_mapper.
• Look first at:
  • vendor/thruster/data-mapper-bundle/README.md
  • DependencyInjection/Configuration.php and Extension.php to discover config keys and service aliases
  • Resources/config/services.xml/services.yml for the mapper service ID
  • Mapping/, Annotation/, or Resources/config/mapping for how mappings are declared
• First use case: map request/array payloads into DTOs or entities, then map entities back to response DTOs. A typical first flow:

  // controller or service
  $dto = $mapper->map($request->request->all(), CreateUserCommand::class);
  

  Confirm the actual method name (map, mapTo, hydrate, etc.) from the bundle’s public service. If autowiring is unavailable, inject the service by its configured ID or create a public alias.

Implementation Patterns

• DTO-first mapping. Define explicit DTOs/commands for input and output rather than mapping directly into Doctrine entities. This keeps mass-assignment risks down and makes mappings stable when entities change.
• Service injection. Inject the mapper service into controllers, handlers, or application services. In older Symfony setups this may require explicit service arguments; in newer setups create an alias:

  services:
    app.data_mapper:
      alias: thruster_data_mapper.mapper
      public: true
  

• Annotation/config-driven mappings. If the bundle supports annotations or YAML/XML mapping metadata, keep mapping files beside the DTOs and load them via bundle config. Use one mapping definition per DTO to avoid hidden coupling.
• Request-to-command flow. Use the mapper at the boundary: HTTP request array → command/DTO → domain service. Avoid passing mapped objects deep into domain logic if the mapper performs loose type coercion.
• Entity-to-response flow. Map entities or read models to response DTOs before serialization. This is useful for trimming fields, renaming API keys, and avoiding lazy-loading leaks.
• Collection mapping. For list endpoints, map arrays of rows to arrays of DTOs in a single loop or dedicated collection mapper. Keep an eye on performance because old mapper implementations often use reflection per item.
• Custom transformers. If the bundle exposes transformers/callbacks, use them for dates, enums, money, and ID normalization. Keep transformers small and unit-tested; they are often the only extension point.
• Validation integration. Map first, then validate the DTO with Symfony Validator. Do not rely on the mapper to validate required fields unless the bundle explicitly supports it.
• Testing pattern. Unit-test mappings with fixture arrays and expected DTOs. Because the package is unmaintained, tests protect you from surprises during PHP/Symfony upgrades.

Gotchas and Tips

• Abandonment is the biggest gotcha. No releases since 2016 means no PHP 8, Symfony 5/6/7, or annotation-reader fixes. Treat it as legacy code and budget for replacement.
• Symfony service visibility. Modern Symfony makes services private by default. If the mapper service cannot be autowired, define a public alias or inject it explicitly; do not rely on $container->get() in production code.
• Annotation reader deprecations. If mappings use Doctrine annotations, modern Symfony/PHP versions may warn or fail. Check composer show for doctrine/annotations compatibility and prefer attributes/YAML only if the bundle supports them.
• Cache staleness. Mapping metadata is often cached. After changing DTOs or mapping files, clear the Symfony cache (bin/console cache:clear) and check the bundle’s cache directory/config key.
• Silent mapping failures. Old mappers often leave properties null when a source key is missing or a type does not match. Add explicit tests for missing, null, and wrong-type input.
• Type coercion surprises. Numeric strings, booleans, and dates may be cast loosely. Normalize input before mapping or use custom transformers for critical fields.
• Circular references and nested mappings. Nested/relationship mapping can recurse indefinitely or trigger lazy loading. Map only scalar fields by default and handle relations explicitly.
• Performance on collections. Reflection-based mapping is slow at scale. Benchmark list endpoints and consider chunking or replacing with symfony/serializer for high-volume paths.
• Config path quirks. Mapping directories may need absolute paths or bundle-relative notation. Inspect Configuration.php rather than guessing YAML keys.
• Debugging tips. Enable Symfony debug mode, inspect the mapper service with debug:container, dump mapping metadata if available, and log source/target arrays during development. If mappings fail silently, temporarily wrap the mapper call to compare input and output.
• Security. Never map raw request data directly into entities with setters for privileged fields. Use DTOs and explicit allow-lists.
• Replacement path. For new work, evaluate symfony/serializer with custom normalizers or a maintained mapper. If you must keep this bundle, isolate it behind your own DataMapperInterface so you can swap implementations later.