Marshaller Bridge Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require spiral/marshaller-bridge
   

   Register the MarshallerBridge service provider in config/app.php under providers:

   Spiral\Marshaller\MarshallerBridge::class,
   

2. First Use Case: Basic Marshalling Inject the MarshallerInterface into a Spiral handler or service:

   use Spiral\Marshaller\MarshallerInterface;
   
   class MyHandler
   {
       public function __construct(private MarshallerInterface $marshaller) {}
   
       public function __invoke($data)
       {
           // Convert object to array
           $array = $this->marshaller->marshal($data);
   
           // Convert array back to object
           $object = $this->marshaller->unmarshal($array, MyModel::class);
   
           return $object;
       }
   }
   

3. Where to Look First

   • Documentation: Check Spiral Framework’s Marshaller docs for core concepts.
   • Config: Review config/marshaller.php (if auto-generated) for default settings like strict_mode or ignore_properties.
   • Tests: Browse the package’s tests (if available) for real-world examples.

Implementation Patterns

Common Workflows

1. DTO Marshalling Use the marshaller to convert between DTOs and arrays for API requests/responses:

   // Incoming request → DTO
   $dto = $this->marshaller->unmarshal($request->all(), CreateUserDto::class);
   
   // DTO → Response array
   $responseData = $this->marshaller->marshal($dto);
   

2. Database Hydration Automate model hydration from database results:

   $users = $this->marshaller->unmarshal(
       $dbResults,
       User::class,
       ['collection' => true] // For collections
   );
   

3. Nested Object Handling Leverage MarshallerBridge to handle nested objects/arrays recursively:

   $complexData = $this->marshaller->unmarshal($input, ComplexModel::class);
   

Integration Tips

• Validation: Combine with Spiral’s ValidatorInterface to validate marshalled data before processing.
• Caching: Cache marshalled results for performance-critical paths (e.g., API responses).
• Custom Types: Extend the marshaller for custom types (e.g., DateTime, Uuid) via MarshallerBridge::extend().

Gotchas and Tips

Pitfalls

1. Strict Mode

   • If strict_mode is true (default in some configs), unmarshalling will throw exceptions for missing/extra properties.
   • Fix: Set strict_mode: false in config or handle exceptions gracefully:

     try {
         $obj = $this->marshaller->unmarshal($data, MyClass::class);
     } catch (MarshallerException $e) {
         // Fallback logic
     }
     

2. Circular References

   • Marshalling objects with circular references (e.g., Parent → Child → Parent) may cause infinite loops.
   • Fix: Use ignore_properties or implement a custom MarshallerBridge extension.

3. Type Mismatches

   • Unmarshalling an array into an object with incompatible types (e.g., string → int) will fail silently or throw errors.
   • Fix: Validate input data before unmarshalling or use MarshallerBridge::setTypeMapper().

Debugging Tips

• Enable Logging: Configure the marshaller to log unmarshalling errors:

  $this->marshaller->setLogger(new MonologLogger());
  

• Inspect Config: Dump the marshaller’s config to debug behavior:

  dd($this->marshaller->getConfig());
  

• Test Edge Cases: Test with null, empty arrays, and deeply nested structures.

Extension Points

1. Custom Marshaller Create a custom marshaller by extending MarshallerBridge:

   class CustomMarshaller extends MarshallerBridge
   {
       protected function getTypeMapper(): TypeMapperInterface
       {
           return new CustomTypeMapper();
       }
   }
   

2. Property Transformations Use MarshallerBridge::setPropertyTransformer() to modify properties during marshalling:

   $this->marshaller->setPropertyTransformer(
       fn (string $property, $value) => strtoupper($value)
   );
   

3. Event Listeners Attach listeners to marshal/unmarshal events for pre/post-processing:

   $this->marshaller->on(MarshallerEvents::UNMARSHAL, function ($context) {
       // Modify $context->data before unmarshalling
   });