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"

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);
  }
  

Gotchas and Tips

New in v1.2.0

• Automatic Snake-to-CamelCase: No manual configuration needed. The mapper now auto-converts snake_case keys to camelCase properties (e.g., user_name → userName).
  • Edge Case: If your model uses 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.

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,
      ],
  ];