Order Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ekyna/order-bundle
   

   Add to config/app.php under ExtraBundles:

   Ekyna\OrderBundle\EkynaOrderBundle::class,
   

2. Database Migration The bundle requires a database table for orders. Check the migrations/ folder in the bundle for the schema. Run:

   php artisan migrate
   

3. First Use Case Create an order via the bundle’s service:

   use Ekyna\OrderBundle\Service\OrderService;
   
   $orderService = app(OrderService::class);
   $order = $orderService->createOrder([
       'customer_id' => 1,
       'items' => [
           ['product_id' => 1, 'quantity' => 2],
           ['product_id' => 3, 'quantity' => 1],
       ],
   ]);
   

Implementation Patterns

Core Workflows

1. Order Creation Use OrderService to create orders with items, customer references, and metadata:

   $order = $orderService->createOrder([
       'customer_id' => $customerId,
       'items' => [
           ['product_id' => $productId, 'quantity' => 5, 'price' => 19.99],
       ],
       'status' => 'pending', // Optional; defaults to 'draft'
       'metadata' => ['note' => 'Gift order'],
   ]);
   

2. Order Retrieval Fetch orders by ID or filter by status/customer:

   // Single order
   $order = $orderService->getOrder($orderId);
   
   // Filtered collection
   $pendingOrders = $orderService->getOrders(['status' => 'pending']);
   

3. Order Updates Modify order status, items, or metadata:

   $orderService->updateOrder($orderId, [
       'status' => 'shipped',
       'metadata' => ['tracking_number' => '12345'],
   ]);
   

4. Order Items Management Add/remove items dynamically:

   $orderService->addItemToOrder($orderId, $productId, $quantity);
   $orderService->removeItemFromOrder($orderId, $itemId);
   

Integration Tips

• Events: Listen for order lifecycle events (e.g., order.created, order.status.updated) via Laravel’s event system.

  // In EventServiceProvider
  protected $listen = [
      'Ekyna\OrderBundle\Event\OrderCreated' => [
          'App\Listeners\NotifyCustomerOrderCreated',
      ],
  ];
  

• Validation: Extend the bundle’s validation rules by overriding the OrderValidator class or using Laravel’s built-in validation.
• APIs: Pair with Laravel’s API resources to expose order endpoints:

  Route::apiResource('orders', OrderController::class);
  

Gotchas and Tips

Pitfalls

1. Missing Documentation

   • The README lacks installation/configuration details. Check the src/ directory for undocumented classes (e.g., OrderService, OrderRepository).
   • Workaround: Inspect the tests/ folder for usage examples or reverse-engineer from the bundle’s codebase.

2. Database Schema Assumptions

   • The bundle expects tables like orders, order_items, and customers. Ensure these exist or alias them in the bundle’s configuration.
   • Fix: Override the OrderRepository to point to custom tables:

     $bundle->setRepository(new CustomOrderRepository());
     

3. Status Transitions

   • The bundle may not enforce strict status transitions (e.g., draft → pending → shipped). Validate transitions manually or extend the OrderService:

     if (!$orderService->isValidStatusTransition($order, 'pending', 'shipped')) {
         throw new \RuntimeException('Invalid transition');
     }
     

4. Dependency Injection

   • The bundle uses Laravel’s container but lacks explicit binding for all services. Manually bind custom services if needed:

     $this->app->bind(OrderService::class, function ($app) {
         return new CustomOrderService($app->make(OrderRepository::class));
     });
     

Debugging Tips

• Log Order Events: Add logging to event listeners to trace order flows:

  public function handle(OrderCreated $event) {
      \Log::info('Order created', ['order_id' => $event->order->id]);
  }
  

• Check for Exceptions: Wrap bundle calls in try-catch blocks to catch undocumented exceptions:

  try {
      $order = $orderService->createOrder($data);
  } catch (\Exception $e) {
      \Log::error('Order creation failed', ['error' => $e->getMessage()]);
  }
  

Extension Points

1. Custom Fields Add fields to the orders table and extend the Order entity:

   // In a service provider
   $order = new Order();
   $order->setCustomField('priority', 'high');
   

   Update the OrderRepository to handle these fields.

2. Payment Integration Hook into the order.status.updated event to trigger payment processing:

   public function handle(OrderStatusUpdated $event) {
       if ($event->newStatus === 'paid') {
           $this->processPayment($event->order);
       }
   }
   

3. Testing Use the bundle’s test suite as a reference. Mock the OrderRepository in unit tests:

   $repository = Mockery::mock(OrderRepository::class);
   $service = new OrderService($repository);