Stuart Api Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require ddb/stuart-api-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       DdB\StuartApiBundle\StuartApiBundle::class => ['all' => true],
   ];
   

2. Configure Stuart API Add your credentials to config/packages/ddb_stuart_api.yaml:

   stuart_api:
       private_key: "%env(STUART_PRIVATE_KEY)%"
       public_key: "%env(STUART_PUBLIC_KEY)%"
       environment: "%env(STUART_ENV)%" # "SANDBOX" or "PRODUCTION"
       vat_rate: 20
   

3. First Use Case: Fetch Next Pickup Slot Call the pre-configured route:

   curl http://your-app.test/api/stuart/next-pickup-slot/Bordeaux
   

   Or use the controller directly in your code:

   $nextSlot = $this->get('ddb_stuart_api.controller.stuart_api')->nextPickupSlot('Paris');
   

Implementation Patterns

Core Workflows

1. Job Creation & Dispatch

   • Use StuartApi service to create and add jobs:

     $job = $this->get('ddb_stuart_api.stuart_api')->createJobObjectFromRequest($request);
     $this->get('ddb_stuart_api.stuart_api')->addJob($job);
     

   • For manual job creation:

     $job = $this->get('ddb_stuart_api.stuart_api')->createJobObject([
         'pickup_address' => '123 Rue de Paris',
         'delivery_address' => '456 Av. des Champs',
         'pickup_date' => '2023-12-31T10:00:00',
     ]);
     

2. Webhook Handling

   • Subscribe to StuartApiEvents::WEBHOOK_RECEIVED to process Stuart’s webhook payloads:

     // src/EventSubscriber/StuartWebhookSubscriber.php
     class StuartWebhookSubscriber implements EventSubscriberInterface
     {
         public static function getSubscribedEvents()
         {
             return [
                 StuartApiEvents::WEBHOOK_RECEIVED => 'onWebhookReceived',
             ];
         }
     
         public function onWebhookReceived(WebhookEvent $event)
         {
             $data = $event->getData();
             // Update your order status, notify users, etc.
         }
     }
     

3. Price & Validate Jobs

   • Use the controller methods for pre-flight checks:

     $price = $this->get('ddb_stuart_api.controller.stuart_api')->priceJob($request);
     $validation = $this->get('ddb_stuart_api.controller.stuart_api')->validateJob($request);
     

Integration Tips

• Environment Awareness: Always test in SANDBOX first. The bundle auto-validates webhook IPs based on the environment.
• Dependency Injection: Prefer injecting StuartApi service over instantiating the controller directly for better testability.
• Error Handling: Wrap API calls in try-catch blocks to handle Stuart’s exceptions (e.g., Stuart\Exception\ApiException).

Gotchas and Tips

Pitfalls

1. Webhook IP Validation

   • Webhook requests from unwhitelisted IPs will 403 silently. Verify your environment’s IPs in config/packages/ddb_stuart_api.yaml match Stuart’s production/sandbox IPs.
   • Debugging: Log the incoming IP in your WebhookEvent subscriber to confirm:

     $ip = $event->getRequest()->getClientIp();
     

2. Private/Public Key Sensitivity

   • Never commit these keys to version control. Use .env or a secrets manager:

     # config/packages/ddb_stuart_api.yaml
     private_key: "%env(STUART_PRIVATE_KEY)%"
     

   • Validation: The bundle does not validate key formats on config load. Stuart’s PHP SDK will throw an exception if invalid.

3. Job Object Requirements

   • createJobObject() expects a strict array structure. Missing fields (e.g., pickup_date) will cause silent failures. Refer to Stuart’s API docs for required fields.

4. Event Dispatching

   • Webhook events are only dispatched for whitelisted IPs. Test locally by adding your dev IP to the sandbox list temporarily.

Debugging Tips

• Enable API Debugging: Stuart’s PHP SDK supports debug mode:

  $client = $this->get('ddb_stuart_api.stuart_api')->getClient();
  $client->setDebug(true); // Logs requests/responses to `var/log/stuart.log`
  

• Log Webhook Payloads: Add this to your subscriber for debugging:

  file_put_contents(
      'var/log/stuart_webhook.log',
      print_r($event->getData(), true),
      FILE_APPEND
  );
  

Extension Points

1. Custom Job Fields

   • Extend the job object by overriding the bundle’s Job class or using a decorator pattern:

     // src/Service/ExtendedJob.php
     class ExtendedJob extends \DdB\StuartApiBundle\Model\Job
     {
         public function setCustomField(string $key, $value): self
         {
             $this->customFields[$key] = $value;
             return $this;
         }
     }
     

   • Bind your class in services.yaml:

     DdB\StuartApiBundle\Model\Job: '@App\Service\ExtendedJob'
     

2. Webhook Payload Processing

   • Override the default WebhookEvent logic by creating a custom subscriber that implements onWebhookReceived with your business logic.

3. Environment-Specific Config

   • Use Symfony’s parameter bags to dynamically load environment-specific configs:

     # config/packages/ddb_stuart_api.yaml
     authorized_webhook_ips: "%kernel.environment%_webhook_ips%"
     

     # config/packages/dev/ddb_stuart_api.yaml
     parameters:
         dev_webhook_ips:
           - "127.0.0.1" # Local dev IP