Shipment Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dywee/shipment-bundle
   

   Add to config/bundles.php (Symfony) or config/app.php (Laravel via bridge):

   Dywee\ShipmentBundle\DyweeShipmentBundle::class => ['all' => true],
   

2. Database Migration Run the bundle’s migrations (check vendor/dywee/shipment-bundle/migrations/ for raw SQL or use Doctrine migrations if integrated):

   php artisan migrate  # (if using Laravel bridge)
   

   Key tables: shipments, shipment_items, shipment_statuses.

3. First Use Case: Create a Shipment

   use Dywee\ShipmentBundle\Entity\Shipment;
   use Dywee\ShipmentBundle\Entity\ShipmentItem;
   
   $shipment = new Shipment();
   $shipment->setSender('John Doe');
   $shipment->setRecipient('Jane Smith');
   $shipment->setTrackingNumber('TRK12345');
   
   $item = new ShipmentItem();
   $item->setProduct('Laptop');
   $item->setQuantity(1);
   $shipment->addItem($item);
   
   $entityManager->persist($shipment);
   $entityManager->flush();
   

Implementation Patterns

Core Workflows

1. CRUD Operations Use the bundle’s repository (Dywee\ShipmentBundle\Repository\ShipmentRepository) for common queries:

   $shipments = $shipmentRepo->findBy(['status' => 'pending']);
   

2. Status Management Define custom statuses via YAML/Doctrine extensions (see Resources/config/shipment_statuses.yml):

   # config/packages/dywee_shipment.yaml
   dywee_shipment:
       statuses:
           - { name: 'pending', label: 'Pending' }
           - { name: 'shipped', label: 'Shipped' }
   

3. Integration with Orders Link shipments to order IDs (extend Shipment entity):

   $shipment->setOrderId($order->getId());
   

4. API Endpoints Use Symfony’s serializers (or Laravel’s API resources) to expose shipments:

   // Symfony Controller
   #[Route('/api/shipments', methods: ['GET'])]
   public function listShipments(ShipmentRepository $repo): JsonResponse
   {
       return $this->json($repo->findAll());
   }
   

Advanced Patterns

• Event Listeners Hook into shipment status changes (e.g., trigger notifications):

  // src/EventListener/ShipmentStatusListener.php
  public function onShipmentStatusChange(ShipmentStatusEvent $event)
  {
      if ($event->getNewStatus() === 'shipped') {
          $this->notifyCustomer($event->getShipment());
      }
  }
  

• Batch Processing Use Doctrine’s BATCH_SIZE for bulk updates:

  $shipments = $shipmentRepo->findBy(['status' => 'pending'], null, 100);
  foreach ($shipments as $shipment) {
      $shipment->setStatus('processed');
  }
  $entityManager->flush();
  

Gotchas and Tips

Common Pitfalls

1. Entity Manager Conflicts

   • If using Laravel, ensure the bundle’s EntityManager is properly bridged (check config/packages/doctrine.yaml for custom EM names).
   • Fix: Configure a separate EM for the bundle or use Laravel’s Eloquent as a facade.

2. Status Validation

   • The bundle assumes statuses are predefined. Custom statuses must be registered in dywee_shipment.yaml before first use.
   • Tip: Clear cache after adding new statuses:

     php artisan cache:clear  # (Laravel bridge)
     

3. Tracking Number Uniqueness

   • The bundle does not enforce uniqueness by default. Add a unique constraint in your migration:

     $table->string('tracking_number')->unique();
     

4. Translation Issues

   • Status labels (e.g., pending) rely on Symfony’s translation system. Ensure locales are configured in config/packages/framework.yaml.

Debugging Tips

• Log Entity Changes Enable Doctrine logging to track persisted changes:

  # config/packages/doctrine.yaml
  doctrine:
      dbal:
          logging: true
          logging_format: '%%timestamp%% %%sql%%'
  

• Check Event Dispatching Verify listeners are subscribed in services.yaml:

  services:
      App\EventListener\ShipmentStatusListener:
          tags:
              - { name: kernel.event_listener, event: dywee.shipment.status_change, method: onShipmentStatusChange }
  

Extension Points

1. Custom Fields Extend the Shipment entity (e.g., add estimatedDeliveryDate):

   // src/Entity/Shipment.php
   #[ORM\Column(type: 'date')]
   private ?\DateTimeInterface $estimatedDeliveryDate = null;
   

2. Carrier Integration Override the Shipment class to add carrier-specific fields (e.g., dhlTrackingUrl):

   public function getCarrierUrl(): ?string
   {
       return $this->carrier === 'dhl' ? "https://track.dhl.com/..." : null;
   }
   

3. Validation Rules Add constraints via Symfony’s validator (e.g., validate tracking number format):

   use Symfony\Component\Validator\Constraints as Assert;
   
   #[Assert\Regex("/^[A-Z0-9]{6,}$/")]
   private ?string $trackingNumber;