Ordertrackerbundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require atm/ordertrackerbundle
   

   Register the bundle in config/app.php under providers:

   ATM\OrderTrackerBundle\OrderTrackerServiceProvider::class,
   

   Publish migrations and config:

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

   Run migrations:

   php artisan migrate
   

2. First Use Case: Tracking an Order Inject the OrderTracker service into a controller or service:

   use ATM\OrderTrackerBundle\Services\OrderTracker;
   
   public function __construct(OrderTracker $orderTracker) {
       $this->orderTracker = $orderTracker;
   }
   

   Create a new order tracking record:

   $trackingData = [
       'order_id' => 'ORD12345',
       'status' => 'processing',
       'customer_id' => 1,
       'notes' => 'Initial order received',
   ];
   $this->orderTracker->createTrackingRecord($trackingData);
   

3. Key Configurations Check config/ordertracker.php for default settings (e.g., statuses, event listeners). Override as needed:

   'statuses' => [
       'processing' => 'Processing',
       'shipped' => 'Shipped',
       'delivered' => 'Delivered',
       'cancelled' => 'Cancelled',
   ],
   

Implementation Patterns

Core Workflows

1. Order Lifecycle Management Use the OrderTracker service to update statuses and log events:

   // Update status and log a note
   $this->orderTracker->updateStatus('ORD12345', 'shipped', 'Shipped via FedEx');
   
   // Add a custom event (e.g., for analytics)
   $this->orderTracker->logEvent('ORD12345', 'tracking_updated', ['carrier' => 'FedEx']);
   

2. Integration with Eloquent Models Attach the bundle to an existing Order model:

   use ATM\OrderTrackerBundle\Traits\Trackable;
   
   class Order extends Model {
       use Trackable;
   
       protected $trackableType = 'order';
   }
   

   Now, use trackable() to interact with tracking records:

   $order = Order::find(1);
   $order->trackable()->updateStatus('shipped');
   

3. Event-Driven Updates Listen for order events (e.g., order.placed) and trigger tracking updates:

   // In EventServiceProvider
   protected $listen = [
       'order.placed' => [
           'ATM\OrderTrackerBundle\Listeners\CreateTrackingRecord',
       ],
   ];
   

4. API Endpoints Expose tracking data via API:

   Route::get('/orders/{order}/track', function ($order) {
       return $order->trackable()->withStatusHistory()->first();
   });
   

Advanced Patterns

• Custom Statuses: Extend the statuses config array or create a dynamic loader.
• Webhooks: Use the OrderTracker to trigger webhooks on status changes:

  $this->orderTracker->onStatusChange('ORD12345', function ($oldStatus, $newStatus) {
      // Send webhook
  });
  

• Bulk Operations: Update multiple orders at once:

  $orderIds = ['ORD123', 'ORD456'];
  $this->orderTracker->bulkUpdateStatus($orderIds, 'shipped');
  

Gotchas and Tips

Common Pitfalls

1. Migration Conflicts

   • If you’ve customized the trackables table, ensure the bundle’s migrations don’t overwrite your schema. Use --force cautiously:

     php artisan migrate --force
     

   • Tip: Backup your database before running migrations if unsure.

2. Status Validation

   • The bundle validates against the statuses config array. If you add a new status dynamically, ensure it’s included in the config or handled via a custom validator:

     $this->orderTracker->setAllowedStatuses(['processing', 'shipped', 'custom_status']);
     

3. Performance with Large Datasets

   • Avoid eager-loading trackable() relationships on every request. Use with() selectively:

     // Bad: Loads all tracking records for every order
     $orders = Order::with('trackable')->get();
     
     // Good: Load only what you need
     $order = Order::with(['trackable' => function ($query) {
         $query->where('status', 'shipped');
     }])->find(1);
     

4. Event Listener Order

   • If multiple listeners react to the same event (e.g., order.status_updated), ensure the OrderTracker listener runs last to avoid race conditions.

Debugging Tips

• Log Tracking Events: Enable debug logging in config/ordertracker.php:

  'debug' => env('APP_DEBUG', false),
  

• Check for Silent Failures: Wrap OrderTracker calls in try-catch to log errors:

  try {
      $this->orderTracker->updateStatus($orderId, 'shipped');
  } catch (\Exception $e) {
      \Log::error("Tracking update failed: " . $e->getMessage());
  }
  

Extension Points

1. Custom Trackable Models Extend the Trackable trait to add model-specific logic:

   use ATM\OrderTrackerBundle\Traits\Trackable;
   
   class Order extends Model {
       use Trackable;
   
       protected function getTrackableType(): string {
           return 'custom_order_type';
       }
   }
   

2. Override Status Transitions Use the status_transitions config to enforce rules (e.g., prevent going from shipped to processing):

   'status_transitions' => [
       'processing' => ['shipped', 'cancelled'],
       'shipped' => ['delivered', 'cancelled'],
   ],
   

3. Add Custom Fields Extend the trackables table via a migration and update the Trackable model:

   // Migration
   Schema::table('trackables', function (Blueprint $table) {
       $table->string('custom_field')->nullable();
   });
   
   // Model
   protected $fillable = ['custom_field'];
   

4. Localization Override status labels in language files:

   // resources/lang/en/ordertracker.php
   return [
       'statuses' => [
           'processing' => 'Under Review',
           'shipped' => 'On Its Way',
       ],
   ];