Ordertrackerbundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require xlabs/ordertrackerbundle
   

   Add to config/app.php under providers:

   Xlabs\OrderTrackerBundle\OrderTrackerServiceProvider::class,
   

   Publish the config:

   php artisan vendor:publish --provider="Xlabs\OrderTrackerBundle\OrderTrackerServiceProvider" --tag="config"
   

2. First Use Case

   • Track an Order: Use the facade in a controller:

     use Xlabs\OrderTrackerBundle\Facades\OrderTracker;
     
     public function trackOrder(Request $request) {
         $orderId = OrderTracker::createOrder([
             'order_id' => 'ORD123',
             'status' => 'pending',
             'customer_id' => 1,
             'items' => [['product_id' => 1, 'quantity' => 2]],
         ]);
         return response()->json(['order_id' => $orderId]);
     }
     

   • Check Status: Query via API or facade:

     $status = OrderTracker::getOrderStatus('ORD123');
     

3. Key Configs Review config/ordertracker.php for:

   • Default statuses (e.g., pending, shipped, delivered).
   • Event listeners (e.g., OrderStatusUpdated).
   • Database table names (default: order_tracker).

Implementation Patterns

Core Workflows

1. Order Lifecycle Management

   • Create/Update: Use OrderTracker::createOrder() or OrderTracker::updateOrderStatus().

     OrderTracker::updateOrderStatus('ORD123', 'shipped', ['carrier' => 'FedEx']);
     

   • Bulk Actions: Leverage OrderTracker::updateStatusForOrders() for batch updates (e.g., "mark all pending orders as shipped").

2. Event-Driven Extensions

   • Listen to status changes via events:

     // In EventServiceProvider
     protected $listen = [
         'Xlabs\OrderTrackerBundle\Events\OrderStatusUpdated' => [
             'App\Listeners\SendShippingNotification',
         ],
     ];
     

   • Trigger custom events:

     event(new \App\Events\CustomOrderEvent($orderData));
     

3. API Integration

   • REST Endpoints: Use the bundle’s built-in routes (if enabled in config) or extend with custom routes:

     Route::get('/orders/{id}/status', [OrderTrackerController::class, 'getStatus']);
     

   • Webhooks: Subscribe to OrderStatusUpdated events to push updates to external systems (e.g., ERP, CRM).

4. Reporting

   • Query historical statuses:

     $history = OrderTracker::getOrderHistory('ORD123');
     

   • Generate reports via Eloquent:

     $reports = \Xlabs\OrderTrackerBundle\Models\Order::where('status', 'delivered')
         ->with('customer')
         ->get();
     

Integration Tips

• Database: Ensure the order_tracker table matches the bundle’s migrations (customize via php artisan migrate).
• Validation: Extend the OrderTracker facade’s validation rules by overriding the validateOrderData() method in a service.
• Testing: Use the OrderTrackerTestCase trait for unit/feature tests:

  use Xlabs\OrderTrackerBundle\Tests\OrderTrackerTestCase;
  
  class OrderTest extends OrderTrackerTestCase { ... }
  

Gotchas and Tips

Pitfalls

1. Status Transitions

   • The bundle enforces strict status transitions (e.g., pending → shipped → delivered). Bypassing this (e.g., pending → delivered) requires custom logic or extending the StatusTransition class.
   • Fix: Use OrderTracker::forceUpdateStatus() sparingly (logs a warning).

2. Event Order

   • Events fire after database updates. For pre-update logic, use model observers on \Xlabs\OrderTrackerBundle\Models\Order.

3. Performance

   • Avoid loading full order history in loops. Use select() or with() to limit columns:

     $order = Order::with(['items' => function($query) {
         $query->select('id', 'product_id', 'quantity');
     }])->find($id);
     

4. Config Overrides

   • Custom statuses must be registered in config/ordertracker.php under statuses before first use. Dynamic additions aren’t supported.

Debugging

• Log Events: Enable debug mode in config/ordertracker.php to log all status changes to storage/logs/ordertracker.log.
• SQL Queries: Use Laravel’s debugbar or DB::enableQueryLog() to inspect complex queries (e.g., bulk updates).

Extension Points

1. Custom Fields

   • Add fields to the order_tracker table via migrations, then extend the Order model:

     class Order extends \Xlabs\OrderTrackerBundle\Models\Order {
         protected $casts = ['custom_field' => 'array'];
     }
     

2. Status Logic

   • Override transition rules by publishing and extending the status_transitions.php config:

     'transitions' => [
         'pending' => ['shipped', 'cancelled'],
         'shipped' => ['delivered', 'returned'], // Custom addition
     ],
     

3. Notifications

   • Extend the OrderStatusUpdated event listener to add SMS/email alerts:

     class CustomNotificationListener {
         public function handle(OrderStatusUpdated $event) {
             if ($event->newStatus === 'delivered') {
                 Notification::route('mail', $event->order->customer->email)
                     ->notify(new OrderDelivered($event->order));
             }
         }
     }
     

4. API Responses

   • Customize JSON responses by overriding the OrderTrackerController or using middleware to transform responses:

     Response::macro('customOrderResponse', function ($order) {
         return response()->json([
             'id' => $order->order_id,
             'status' => $order->status,
             'metadata' => $order->custom_fields ?? [],
         ]);
     });