Laravel Object Mapper Laravel Package

Getting Started

Install via Composer:

composer require shureban/laravel-object-mapper

Publish the config (optional):

php artisan vendor:publish --provider="Shureban\ObjectMapper\ObjectMapperServiceProvider"

Version note (v2.0.1): The current line is 2.x, which adds Laravel 13 support. If you are on an older Laravel release, check the package's compatibility matrix before upgrading — 1.x and 2.x are separate major lines, so pin your constraint deliberately (^2.0 vs ^1.2) rather than using *.

First Use Case: Transforming arrays to objects with automatic snake_case-to-camelCase conversion:

use Shureban\ObjectMapper\Facades\ObjectMapper;

$data = ['user_name' => 'john_doe', 'user_age' => 30];
$user = ObjectMapper::map($data, \App\Models\User::class);
// $user now has properties: userName, userAge

Implementation Patterns

Core Workflow

1. Mapping Arrays to Objects:

   $object = ObjectMapper::map($arrayData, $targetClass);
   

2. Nested Transformations:

   $complexObject = ObjectMapper::map($nestedArray, \App\Models\Order::class);
   // Automatically handles nested snake_case keys
   

3. Custom Mappers (via config):

   // config/object-mapper.php
   'mappers' => [
       'App\Models\User' => \App\Mappers\UserMapper::class,
   ],
   

Integration Tips

• Form Requests: Use with Laravel's FormRequest to auto-map validated input:

  public function rules() { /* ... */ }
  public function map(array $data) {
      return ObjectMapper::map($data, \App\Models\User::class);
  }
  

• API Resources: Transform collections efficiently:

  public function toArray($request) {
      return ObjectMapper::mapCollection($this->collection, \App\DTO\UserDTO::class);
  }
  

• Upgrading within 2.x: Patch releases in this line are compatibility-focused (v2.0.1 is purely Laravel 13 support), so they are low-risk. Treat the 1.x → 2.x jump as the real migration boundary — run your mapper test suite and check custom TransformerInterface implementations against the v2 API before switching.

Gotchas and Tips

Compatibility (v2.0.1)

• Laravel 13 support landed in v2.0.1, but the release contains no mapper API changes — pinning ^2.0 is safe for day-to-day work.
• Lockstep upgrades: If you bump Laravel to 13, bump this package in the same deploy. Older 1.x installs are not covered by the Laravel 13 support commit.
• Automatic Snake-to-CamelCase (introduced in v1.2.0) remains the default behavior — no manual configuration needed. The mapper auto-converts snake_case keys to camelCase properties (e.g., user_name → userName).
  • Edge Case: If your model has explicit protected $fillable = ['user_name'], ensure your setter methods match the auto-converted names (e.g., setUserName()).

Common Pitfalls

1. Reserved Words: Keys like class or static may cause issues. Rename them in your source data.
2. Circular References: Avoid recursive object structures without custom logic.
3. Type Mismatches: The mapper casts types (e.g., strings to booleans for true/false). Override with explicit type hints in your model/DTO.
4. Silent version drift: Because the package sits between Laravel and your DTOs, a mismatched Laravel/package combination surfaces as confusing property-mapping errors rather than a clear dependency failure. Run composer why shureban/laravel-object-mapper first when mappings start behaving unexpectedly after an upgrade.

Debugging

• Enable Verbose Logging:

  ObjectMapper::setDebug(true); // Logs transformations to storage/logs/object-mapper.log
  

• Inspect Mapped Data:

  $mappedData = ObjectMapper::getMappedData(); // Returns the last transformation result
  

Extension Points

• Custom Transformers: Extend \Shureban\ObjectMapper\Transformers\TransformerInterface for complex logic.
• Pre/Post Hooks: Use the mapped and mapping events in your EventServiceProvider:

  protected $listen = [
      'Shureban\ObjectMapper\Events\Mapping' => [
          \App\Listeners\LogMapping::class,
      ],
  ];