Stuart Client Php Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require stuartapp/stuart-client-php
   

   Requires PHP 7.2+ and Laravel 6+ (or Lumen).

2. Configuration Publish the config file:

   php artisan vendor:publish --provider="Stuart\Client\StuartServiceProvider"
   

   Update .env with your Stuart API credentials:

   STUART_API_KEY=your_api_key_here
   STUART_API_SECRET=your_api_secret_here
   STUART_API_URL=https://api.stuart.com
   

3. First Use Case: Creating a Delivery

   use Stuart\Client\StuartClient;
   
   $client = app(StuartClient::class);
   $delivery = $client->deliveries()->create([
       'pickup' => [
           'address' => '123 Main St, London',
           'latitude' => 51.5074,
           'longitude' => -0.1278,
           'contact_name' => 'John Doe',
           'contact_phone' => '+441234567890',
       ],
       'dropoff' => [
           'address' => '456 High St, Manchester',
           'latitude' => 53.4808,
           'longitude' => -2.2426,
       ],
       'size' => 'medium',
       'weight' => 5,
       'ready_by' => now()->addMinutes(30)->toIso8601String(),
       'notes' => 'Fragile items',
   ]);
   

Implementation Patterns

Core Workflows

1. Delivery Management

   • Create: Use deliveries()->create() for instant bookings.
   • List: Fetch active deliveries with deliveries()->all().
   • Track: Poll delivery status via deliveries()->show($id).
   • Cancel: Use deliveries()->cancel($id) with a reason.

2. Webhooks Integrate Stuart’s webhooks for real-time updates:

   Route::post('/stuart/webhook', function (Request $request) {
       $client = app(StuartClient::class);
       $client->webhooks()->handle($request->all());
   });
   

   Verify signatures using StuartClient::verifyWebhook($payload, $signature).

3. Batch Processing For bulk operations (e.g., updating multiple deliveries):

   $client->deliveries()->update($deliveryId, ['status' => 'completed']);
   

Integration Tips

• Laravel Service Container: Bind the client to the container for dependency injection:

  $this->app->singleton(StuartClient::class, function ($app) {
      return new StuartClient(config('stuart.api_key'), config('stuart.api_secret'));
  });
  

• Queued Jobs: Offload delivery creation to queues:

  Dispatch(new CreateStuartDelivery($data))->onQueue('stuart');
  

• API Rate Limiting: Handle 429 Too Many Requests by implementing exponential backoff:

  try {
      $delivery = $client->deliveries()->create($data);
  } catch (RateLimitExceededException $e) {
      sleep($e->getRetryAfter());
      retry();
  }
  

Gotchas and Tips

Pitfalls

1. Deprecated API The package is archived (last release in 2021). Verify Stuart’s current API docs for breaking changes. Use try-catch for undocumented endpoints:

   try {
       $client->deliveries()->create($data);
   } catch (InvalidArgumentException $e) {
       // Handle deprecated fields (e.g., 'ready_by' vs 'ready_at')
   }
   

2. Webhook Verification Stuart’s webhook signatures use HMAC-SHA256. Always verify:

   if (!$client->verifyWebhook($payload, $request->header('X-Stuart-Signature'))) {
       abort(403, 'Invalid webhook signature');
   }
   

3. Timezone Mismatches Stuart expects timestamps in UTC. Convert Laravel’s Carbon instances:

   'ready_by' => now()->setTimezone('UTC')->addMinutes(30)->toIso8601String(),
   

Debugging

• Enable Debug Mode: Set STUART_DEBUG=true in .env to log raw API requests/responses.
• Mock Testing: Use Laravel’s HTTP client to mock Stuart’s API:

  $client->setHttpClient(new MockHttpClient());
  

• Common Errors:
  • 401 Unauthorized: Check STUART_API_KEY/SECRET.
  • 400 Bad Request: Validate size (must be small, medium, or large) and weight (max 30kg).

Extension Points

1. Custom Responses Extend the base client to add domain-specific logic:

   class CustomStuartClient extends StuartClient {
       public function createDeliveryWithRetry($data, $retries = 3) {
           try {
               return parent::deliveries()->create($data);
           } catch (Exception $e) {
               if ($retries > 0) {
                   sleep(2);
                   return $this->createDeliveryWithRetry($data, $retries - 1);
               }
               throw $e;
           }
       }
   }
   

2. Event Dispatching Trigger Laravel events for Stuart webhooks:

   $client->webhooks()->on('delivery.created', function ($data) {
       event(new StuartDeliveryCreated($data));
   });
   

3. Fallback Logic Implement retries with jitter for transient failures:

   $client->setRetryConfig([
       'max_attempts' => 3,
       'delay' => 1000, // ms
       'jitter' => true,
   ]);