Atol Client Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require anripuankare/atol-client
   

   Add the package to your config/app.php providers (if not auto-discovered):

   'providers' => [
       // ...
       Anripuankare\AtolClient\AtolServiceProvider::class,
   ],
   

2. Configuration Publish the config file:

   php artisan vendor:publish --provider="Anripuankare\AtolClient\AtolServiceProvider" --tag="config"
   

   Update .env with your ATOL credentials:

   ATOL_CLIENT_ID=your_client_id
   ATOL_CLIENT_SECRET=your_client_secret
   ATOL_SANDBOX=false
   

3. First Use Case: Authentication

   use Anripuankare\AtolClient\Facades\Atol;
   
   $token = Atol::auth()->getAccessToken();
   

Implementation Patterns

Workflows

1. API Requests Use the fluent interface for API calls:

   $response = Atol::api('v3')->get('/orders', [
       'filter' => ['status' => 'pending']
   ]);
   

2. Webhooks Handle ATOL webhook payloads:

   use Anripuankare\AtolClient\Events\WebhookReceived;
   
   Event::listen(WebhookReceived::class, function ($event) {
       $payload = $event->payload;
       // Process webhook (e.g., order updates)
   });
   

3. Order Management Create/update orders via the SDK:

   $order = Atol::api('v4')->post('/orders', [
       'order_number' => 'ORD-123',
       'items' => [
           ['sku' => 'SKU-001', 'quantity' => 2]
       ]
   ]);
   

Integration Tips

• Laravel Queues: Dispatch long-running ATOL operations to queues:

  dispatch(new ProcessAtolOrder($orderData));
  

• Middleware: Validate ATOL responses globally:

  Atol::extend(function ($client) {
      $client->after(function ($response) {
          if ($response->failed()) {
              Log::error('ATOL API Error', ['response' => $response->json()]);
          }
      });
  });
  

Gotchas and Tips

Pitfalls

1. Sandbox vs. Production

   • Forgetting to toggle ATOL_SANDBOX can cause unexpected API calls.
   • Fix: Use environment-specific config files or a feature flag.

2. Rate Limiting

   • ATOL enforces rate limits (e.g., 100 requests/minute).
   • Fix: Implement exponential backoff:

     Atol::retry(3, function () {
         return Atol::api()->get('/orders');
     });
     

3. Webhook Verification

   • Always verify webhook signatures:

     $isValid = Atol::webhook()->verify($request->getContent(), $request->header('X-Atol-Signature'));
     

Debugging

• Enable Logging

  Atol::setLogLevel(\Monolog\Logger::DEBUG);
  

• Inspect Raw Responses

  $rawResponse = Atol::api()->get('/orders', [], [], ['debug' => true]);
  

Extension Points

1. Custom API Clients Extend the base client for domain-specific logic:

   Atol::extend('custom', function () {
       return new CustomAtolClient(Atol::getClient());
   });
   

2. Mocking for Tests Use the AtolMock facade in tests:

   AtolMock::shouldReceive('getAccessToken')->andReturn('mock_token');
   

3. Event Hooks Listen for ATOL events (e.g., OrderCreated):

   Event::listen(AtolEvents::ORDER_CREATED, function ($order) {
       // Sync with your ERP
   });