Snelstartapi Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dsj/snelstartapi
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="Dsj\SnelstartApi\SnelstartApiServiceProvider"
   

2. Configuration Edit .env with your SnelStart API credentials:

   SNELSTART_API_KEY=your_api_key_here
   SNELSTART_API_SECRET=your_api_secret_here
   SNELSTART_API_URL=https://api.snelstart.nl/v1
   

3. First Use Case: Fetching a Customer

   use Dsj\SnelstartApi\Facades\SnelstartApi;
   
   $customer = SnelstartApi::customer()->find(123);
   dd($customer); // Returns customer data
   

4. Key Facades

   • SnelstartApi::customer() → Customer operations
   • SnelstartApi::order() → Order operations
   • SnelstartApi::product() → Product operations

Implementation Patterns

Workflow: Order Creation

// 1. Create order payload
$orderData = [
    'customer_id' => 123,
    'items' => [
        ['product_id' => 456, 'quantity' => 2],
    ],
];

// 2. Submit via API
$order = SnelstartApi::order()->create($orderData);

// 3. Handle response
if ($order->success()) {
    // Process success
} else {
    // Handle errors (e.g., $order->errors())
}

Integration Tips

1. Laravel Events Trigger custom events post-API calls:

   event(new OrderCreated($order));
   

2. API Rate Limiting Cache responses for non-critical data:

   $cachedProduct = cache()->remember("snelstart_product_{$id}", now()->addHours(1), fn() =>
       SnelstartApi::product()->find($id)
   );
   

3. Form Requests Validate API responses in FormRequest classes:

   public function rules()
   {
       return [
           'snelstart_order_id' => 'required|exists:snelstart_orders,id',
       ];
   }
   

4. Queue Jobs Offload API calls to queues for async processing:

   dispatch(new SyncSnelstartCustomer($customerId));
   

Gotchas and Tips

Pitfalls

1. Authentication

   • Ensure SNELSTART_API_KEY and SNELSTART_API_SECRET are never committed to version control.
   • Use Laravel’s env() helper to validate keys at runtime:

     if (empty(env('SNELSTART_API_KEY'))) {
         throw new \RuntimeException('SnelStart API keys are missing.');
     }
     

2. Pagination

   • The package may not handle pagination by default. Use ->paginate() if available or manually loop through ->all():

     $customers = SnelstartApi::customer()->all();
     foreach ($customers as $customer) { ... }
     

3. Error Handling

   • API errors may return null or throw exceptions. Normalize responses:

     $response = SnelstartApi::order()->find($id);
     if (is_null($response)) {
         // Handle missing resource
     }
     

4. Webhooks

   • SnelStart may send webhooks (e.g., for order updates). Use Laravel’s HandleIncomingWebhook trait or a dedicated route:

     Route::post('/snelstart/webhook', [SnelstartWebhookController::class, 'handle']);
     

Debugging

1. Enable Logging Add to config/snelstartapi.php:

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

   Logs will appear in storage/logs/laravel.log.

2. API Response Inspection Use dd() or dump() on raw responses:

   $rawResponse = SnelstartApi::order()->raw()->find($id);
   dd($rawResponse);
   

3. Testing Mock the API in PHPUnit:

   $mock = Mockery::mock('overload', Dsj\SnelstartApi\SnelstartApi::class);
   $mock->shouldReceive('get')->andReturn(['data' => 'test']);
   

Extension Points

1. Custom Endpoints Extend the base client:

   use Dsj\SnelstartApi\SnelstartApi;
   
   class CustomSnelstartApi extends SnelstartApi
   {
       public function customEndpoint($data)
       {
           return $this->post('/custom', $data);
       }
   }
   

2. Middleware Add middleware to API calls (e.g., for logging):

   SnelstartApi::withMiddleware(function ($request) {
       Log::info('SnelStart API call', ['data' => $request->data]);
   });
   

3. Model Observers Sync SnelStart data with Eloquent models:

   class CustomerObserver
   {
       public function saved(Customer $customer)
       {
           SnelstartApi::customer()->update($customer->id, $customer->toArray());
       }
   }