Vdm Library Doctrine Odm Transport Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your Laravel project via Composer:

   composer require 3slab/vdm-library-doctrine-odm-transport-bundle
   

   Register the bundle in config/app.php under providers (if not auto-discovered).

2. Configuration Publish the default config:

   php artisan vendor:publish --provider="3slab\VdmLibraryDoctrineOdmTransportBundle\VdmLibraryDoctrineOdmTransportBundle" --tag="config"
   

   Update config/vdm_library_doctrine_odm_transport.php with your Doctrine ODM connection details (e.g., MongoDB URI, database name).

3. First Use Case Use the bundle to hydrate a Doctrine ODM document from a Laravel model or DTO:

   use VdmLibrary\DoctrineOdmTransportBundle\Transport\DocumentTransport;
   
   $transport = app(DocumentTransport::class);
   $document = $transport->hydrateFromArray($arrayData, 'YourDocumentClass');
   $transport->persist($document); // Save to MongoDB
   

Implementation Patterns

1. Data Transport Workflows

• Laravel ↔ Doctrine ODM Sync Use DocumentTransport to convert between Laravel arrays (e.g., API payloads) and Doctrine ODM documents:

  // Convert Laravel array to ODM document
  $document = $transport->hydrateFromArray($request->all(), 'UserProfile');
  
  // Convert ODM document to array (e.g., for API response)
  $arrayData = $transport->extractToArray($document);
  

• Bulk Operations Leverage batch processing for efficiency:

  $documents = [];
  foreach ($request->all() as $item) {
      $documents[] = $transport->hydrateFromArray($item, 'Product');
  }
  $transport->persistAll($documents); // Bulk save
  

2. Integration with Laravel Services

• Form Request Validation Validate incoming data before transport:

  public function rules(): array
  {
      return [
          'name' => 'required|string',
          'email' => 'required|email',
      ];
  }
  
  public function hydrate(Validator $validator)
  {
      $data = $validator->validated();
      $document = $this->transport->hydrateFromArray($data, 'User');
      return $document;
  }
  

• API Resource Transformation Use the transport in Illuminate\Http\Resources\Json\Resource:

  public function toArray($request)
  {
      return $this->transport->extractToArray($this->resource);
  }
  

3. Event-Driven Patterns

• Listen for Document Events Hook into Doctrine ODM lifecycle events (e.g., prePersist) via Laravel events:

  // In EventServiceProvider
  protected $listen = [
      'odm.document.prePersist' => [
          \App\Listeners\LogDocumentCreation::class,
      ],
  ];
  

Gotchas and Tips

Pitfalls

1. Type Mismatches

   • Doctrine ODM expects strict types (e.g., DateTime for timestamps). Ensure Laravel arrays match:

     // Bad: String timestamp
     $data = ['created_at' => '2023-01-01'];
     
     // Good: Convert to DateTime object
     $data = ['created_at' => new \DateTime('2023-01-01')];
     

2. Missing Document Classes

   • The bundle requires fully qualified class names (e.g., App\Documents\User). Use:

     $transport->hydrateFromArray($data, \App\Documents\User::class);
     

3. MongoDB Schema Changes

   • If your ODM documents change, clear the transport cache:

     php artisan cache:clear
     

Debugging Tips

• Enable Doctrine Debugging Add to config/monolog.php:

  'channels' => [
      'doctrine' => [
          'path' => storage_path('logs/doctrine.log'),
          'level' => 'debug',
      ],
  ],
  

  Then log ODM events:

  $this->container->get('doctrine')->getManager()->getEventManager()->addEventListener(
      array('prePersist', 'preUpdate'),
      new \Doctrine\ODM\MongoDB\Event\LifecycleEventListener()
  );
  

Extension Points

1. Custom Hydrators Extend VdmLibrary\DoctrineOdmTransportBundle\Transport\Hydrator\HydratorInterface for custom logic:

   class CustomHydrator implements HydratorInterface
   {
       public function hydrate(array $data, string $class): object
       {
           // Custom logic (e.g., nested object hydration)
       }
   }
   

   Register in config:

   'hydrators' => [
       'custom' => \App\Hydrators\CustomHydrator::class,
   ],
   

2. Override Default Config Use environment variables to customize:

   VDM_ODM_TRANSPORT_DEFAULT_DOCUMENT=App\Documents\User
   

3. Laravel Service Container Binding Bind custom transports:

   $this->app->bind(DocumentTransport::class, function ($app) {
       return new CustomDocumentTransport($app['doctrine']);
   });