Object Mapper Laravel Package

Product Decisions This Supports

• DTO/DTO Pattern Standardization: Eliminates manual mapping between entities and DTOs (e.g., User ↔ UserResponseDTO), reducing boilerplate in controllers and services. Example: Replace return new UserResponseDTO($user->name, $user->email) with @MapEntity attributes, enforcing consistency across the codebase.
• API Layer Decoupling: Enables clean separation between domain models and API contracts, critical for microservices, GraphQL, or headless architectures. Aligns with roadmaps to decouple business logic from presentation layers (e.g., Laravel + API Platform).
• Build vs. Buy Decision: Justifies open-source adoption over custom solutions for teams using Symfony components (e.g., HTTPFoundation, Messenger) or PHP 8+. Avoids reinventing mapping logic for nested objects, collections, or type conversions (e.g., string → Carbon).
• Use Cases:
  • Laravel API Development: Replace manual array_map or create() chains in controllers with attribute-driven mapping (e.g., @MapProperty, @Ignore).
  • Legacy System Integration: Bridge gaps between outdated database schemas and modern Laravel models (e.g., mapping legacy User tables to UserProfileDTO).
  • Testing: Dynamically generate test data by mapping between fixtures and application objects (e.g., UserFactory → User).
  • Event-Driven Architectures: Map between domain events and command/query objects (e.g., OrderCreatedEvent → OrderCommand).
  • Form Handling: Automatically map form submissions to domain objects (e.g., Request → UserUpdateCommand).

When to Consider This Package

• Adopt if:

  • Your Laravel app uses Symfony components (e.g., HTTPFoundation, UX, Messenger) or targets PHP 8.1+ for attribute support.
  • You frequently handle complex object transformations (e.g., nested DTOs, collections, or type conversions like string → DateTime).
  • Your team prioritizes developer velocity over micro-optimizations (e.g., avoiding manual setName() chains in controllers).
  • You need declarative mapping rules via PHP attributes (e.g., @MapEntity, @Ignore) to reduce boilerplate.
  • Your roadmap includes microservices, API Platform, or domain-driven design (DDD) where object mapping is critical.
  • You’re using Laravel with Symfony integration (e.g., via symfony/dependency-injection or symfony/http-client).

• Look elsewhere if:

  • Your project is simple CRUD with no DTOs or complex mappings (overkill for basic Model::find() → json_encode()).
  • You require high-performance mapping (benchmark against alternatives like Mapperly or JMS Serializer).
  • You’re not using PHP 8+ (attributes are required for full functionality).
  • You prefer Laravel-native solutions like spatie/laravel-data or php-http/message for tighter integration.
  • Your objects have dynamic or runtime-defined structures (e.g., JSON Schema-based APIs; consider symfony/serializer instead).
  • You’re heavily invested in Laravel’s Eloquent and need zero-config mapping (e.g., fill() or create()).

How to Pitch It (Stakeholders)

For Executives: "This package reduces API development time by 50% by automating the manual mapping between database records, internal objects, and API responses. For example, converting a UserEntity to a UserResponseDTO—which today requires 20+ lines of boilerplate—can be done in 2 lines with attributes. This directly supports our goals to [reduce technical debt and accelerate feature delivery] while keeping code clean and maintainable. It’s a low-risk, high-reward choice, backed by Symfony’s stability, and MIT-licensed for full flexibility. The ROI comes from faster iterations, fewer bugs, and easier maintenance in our API layer."

For Engineers: "Symfony’s Object Mapper lets us replace repetitive mapping logic with declarative attributes (e.g., @MapEntity, @Ignore), cutting cognitive load and runtime errors. It integrates seamlessly with Laravel’s DI system (via symfony/dependency-injection) and supports nested objects/collections out of the box. For teams using Symfony components or PHP 8+, this is a no-brainer—it’s battle-tested, actively maintained, and avoids reinventing the wheel. If we’re not using Symfony, we could evaluate alternatives like spatie/laravel-data, but this gives us the most ‘batteries-included’ experience for complex mappings. It’s especially useful for APIs, DDD, or legacy integrations where object transformation is a pain point."

For Architects: *"This package aligns with clean architecture principles by enforcing separation between domain models and API contracts. Key benefits include:

• Microservices: Decoupling services with standardized mapping rules.
• Legacy Modernization: Bridging outdated schemas to modern Laravel models.
• Event-Driven Systems: Mapping between domain events and commands/queries.
• Form Handling: Automatically mapping form submissions to domain objects. The trade-off is a minor learning curve for attributes, but the long-term gains in maintainability and scalability outweigh the cost. It’s particularly valuable for teams adopting Symfony components or migrating to PHP 8+."*