Shipment Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ekyna/shipment-bundle
   

   Add to config/bundles.php:

   Ekyna\ShipmentBundle\EkynaShipmentBundle::class => ['all' => true],
   

2. Publish Config & Migrations

   php artisan vendor:publish --provider="Ekyna\ShipmentBundle\EkynaShipmentBundle" --tag="config"
   php artisan vendor:publish --provider="Ekyna\ShipmentBundle\EkynaShipmentBundle" --tag="migrations"
   php artisan migrate
   

3. First Use Case Create a shipment via CLI:

   php artisan shipment:create --name="Test Shipment" --reference="REF123"
   

   Verify in database (shipments table) or via Tinker:

   $shipment = \Ekyna\ShipmentBundle\Entity\Shipment::first();
   

Implementation Patterns

Core Workflows

1. Shipment Creation

   • Manual: Use ShipmentFactory (service) or CLI command.
   • Automated: Trigger via event listeners (e.g., OrderPlaced).

     use Ekyna\ShipmentBundle\Event\ShipmentEvents;
     
     event(new ShipmentEvents\ShipmentCreated($shipment));
     

2. Tracking & Status Updates

   • Update status via repository:

     $shipment->setStatus('delivered');
     $this->shipmentRepository->save($shipment);
     

   • Log tracking events:

     $shipment->addTrackingEvent('scanned', 'Warehouse A', new \DateTime());
     

3. Integration with Orders

   • Link shipments to orders via ManyToMany relationship:

     $shipment->addOrder($order);
     $this->shipmentRepository->save($shipment);
     

   • Fetch shipments for an order:

     $shipments = $order->getShipments();
     

4. Carrier Integration

   • Extend CarrierInterface for custom carriers:

     class CustomCarrier implements CarrierInterface {
         public function generateLabel(Shipment $shipment) { ... }
         public function getTrackingUrl(Shipment $shipment) { ... }
     }
     

   • Register in config:

     ekyna_shipment:
         carriers:
             custom:
                 class: App\Carrier\CustomCarrier
     

5. API Exposure

   • Use FOSRestBundle or Laravel’s built-in API resources:

     namespace App\Http\Resources;
     use Ekyna\ShipmentBundle\Entity\Shipment;
     use Illuminate\Http\Resources\Json\JsonResource;
     
     class ShipmentResource extends JsonResource {
         public function toArray($request) {
             return [
                 'id' => $this->id,
                 'reference' => $this->reference,
                 'status' => $this->status,
                 'tracking_url' => $this->getTrackingUrl(),
             ];
         }
     }
     

Gotchas and Tips

Pitfalls

1. Missing Configuration

   • Symptom: Commands fail with Configuration not found.
   • Fix: Always publish config (php artisan vendor:publish) and verify config/ekyna_shipment.php exists.

2. Entity Not Found

   • Symptom: Shipment entity not autowired or EntityManager errors.
   • Fix: Ensure EkynaShipmentBundle is loaded in config/bundles.php before your bundle if using Symfony.

3. Carrier-Specific Quirks

   • Symptom: Labels/tracking URLs fail silently.
   • Debug: Check CarrierInterface implementation and log carrier-specific errors:

     try {
         $carrier->generateLabel($shipment);
     } catch (\Exception $e) {
         \Log::error("Carrier {$carrier->getName()} failed: " . $e->getMessage());
     }
     

4. Migration Conflicts

   • Symptom: Schema::hasTable('shipments') fails during migration.
   • Fix: Run migrations in isolation:

     php artisan migrate --path=/vendor/ekyna/shipment-bundle/src/Resources/migrations
     

Tips

1. Custom Fields Extend the Shipment entity via traits or inheritance:

   namespace App\Entity;
   use Ekyna\ShipmentBundle\Entity\Shipment as BaseShipment;
   
   class Shipment extends BaseShipment {
       /**
        * @ORM\Column(type="string", nullable=true)
        */
       private $customField;
   }
   

2. Event-Driven Workflows Listen for shipment events to trigger notifications or updates:

   // In a service provider
   $this->eventDispatcher->addListener(
       ShipmentEvents::SHIPMENT_CREATED,
       function ($event) {
           // Send email, update inventory, etc.
       }
   );
   

3. Testing Use factories for shipments:

   $shipment = ShipmentFactory::create()
       ->withName('Test')
       ->withStatus('pending')
       ->create();
   

4. Performance

   • Bulk Operations: Use repository methods like updateStatusBulk() if available.
   • Eager Loading: Avoid N+1 queries when fetching shipments with orders:

     $shipments = $this->shipmentRepository->findBy([], ['orders' => 'id']);
     

5. Debugging

   • Enable debug mode in config:

     ekyna_shipment:
         debug: true
     

   • Check logs for carrier-specific errors or entity lifecycle events.