Atol Client Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require anripuankare/atol-client-bundle
   

2. Register Bundles Add to config/bundles.php:

   return [
       // ...
       Lamoda\AtolClientBundle\AtolClientBundle::class => ['all' => true],
       JMS\SerializerBundle\JMSSerializerBundle::class => ['all' => true],
   ];
   

3. Configure Guzzle and ATOL In config/services.yaml:

   services:
       guzzle:
           class: GuzzleHttp\Client
   

   In config/packages/atol_client.yaml:

   atol_client:
       clients:
           default:
               version: !php/const Lamoda\AtolClientBundle\AtolClientBundle::API_CLIENT_VERSION_4
               guzzle_client: guzzle
               base_url: '%env(ATOL_API_URL)%'
               callback_url: '%env(ATOL_CALLBACK_URL)%'
   

4. First Use Case Inject the client in a service and call an API method:

   use Lamoda\AtolClientBundle\Client\AtolClientInterface;
   
   class MyService
   {
       public function __construct(private AtolClientInterface $atolClient) {}
   
       public function fetchOrderStatus(string $orderId): array
       {
           return $this->atolClient->getOrderStatus($orderId);
       }
   }
   

Implementation Patterns

Dependency Injection

• Inject the Client Use @atol_client.v4 (or .v3) in services or controllers:

  public function __construct(
      private AtolClientInterface $atolClient,
      private AtolClientV4Interface $atolClientV4
  ) {}
  

• Version-Specific Clients The bundle auto-registers AtolClientV3Interface and AtolClientV4Interface as separate services.

Common Workflows

1. Order Processing

   $order = $this->atolClient->createOrder([
       'order_id' => '123',
       'items' => [['product_id' => '456', 'quantity' => 2]],
   ]);
   

2. Webhook Handling Validate ATOL callbacks using the validateCallback method:

   $isValid = $this->atolClient->validateCallback($request->getContent());
   

3. Batch Operations Use createOrders or updateOrders for bulk requests:

   $results = $this->atolClient->createOrders([$order1, $order2]);
   

Integration Tips

• Environment Variables Store base_url, callback_url, and credentials in .env:

  ATOL_API_URL=https://api.atol.ru/v4
  ATOL_CALLBACK_URL=https://yourdomain.com/atol/callback
  ATOL_LOGIN=your_login
  ATOL_PASSWORD=your_password
  

• Logging Enable Guzzle middleware for logging:

  atol_client:
      clients:
          default:
              guzzle_client_options:
                  middleware: ['GuzzleHttp\Middleware\LogRequest']
  

• Validation Leverage Symfony’s validator for request payloads:

  use Symfony\Component\Validator\Validator\ValidatorInterface;
  
  public function __construct(private ValidatorInterface $validator) {}
  
  public function validateOrder(array $order): void
  {
      $errors = $this->validator->validate($order);
      if ($errors->count() > 0) {
          throw new \InvalidArgumentException('Invalid order data');
      }
  }
  

Gotchas and Tips

Pitfalls

1. Deprecated API (v3)

   • ATOL v3 is deprecated (unsupported since 2019). Avoid using AtolClientV3Interface unless maintaining legacy systems.
   • Fix: Use AtolClientV4Interface for new projects.

2. Callback Validation

   • ATOL callbacks must be validated server-side to prevent spoofing.
   • Fix: Always use validateCallback() and verify signatures:

     $isValid = $this->atolClient->validateCallback($rawPayload);
     if (!$isValid) {
         throw new \RuntimeException('Invalid ATOL callback');
     }
     

3. Guzzle Client Configuration

   • Misconfigured guzzle_client_options (e.g., wrong base_uri) will cause silent failures.
   • Fix: Test with curl first or enable Guzzle logging.

4. JMS Serializer Dependencies

   • The bundle requires jms/serializer-bundle for request/response serialization.
   • Fix: Ensure it’s installed and registered in bundles.php.

Debugging

• Enable API Debugging Add debug middleware to Guzzle:

  guzzle_client_options:
      middleware: ['GuzzleHttp\Middleware\LogRequest', 'GuzzleHttp\Middleware\LogResponse']
  

• Check ATOL API Responses ATOL returns structured errors (e.g., {"errors": ["Invalid order_id"]}). Parse responses carefully:

  try {
      $response = $this->atolClient->getOrderStatus($orderId);
  } catch (\Lamoda\AtolClientBundle\Exception\AtolClientException $e) {
      // Handle ATOL-specific errors
      $errors = json_decode($e->getMessage(), true);
  }
  

Extension Points

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

   class CustomAtolClient implements AtolClientInterface
   {
       private AtolClientV4Interface $client;
   
       public function __construct(AtolClientV4Interface $client) {
           $this->client = $client;
       }
   
       public function getOrderStatus(string $orderId): array
       {
           $response = $this->client->getOrderStatus($orderId);
           return $this->transformResponse($response);
       }
   
       private function transformResponse(array $data): array
       {
           // Add custom logic (e.g., mapping fields)
           return $data;
       }
   }
   

2. Override Configuration Use Symfony’s compiler passes or decorators to modify the client behavior at runtime.

3. Add Middleware Inject custom middleware into Guzzle for pre/post-processing:

   atol_client:
       clients:
           default:
               guzzle_client_options:
                   middleware: ['App\Middleware\AddAuthHeader']
   

Configuration Quirks

• Base URL Ensure base_url ends with / (e.g., https://api.atol.ru/v4/). Missing slashes may cause 404s.

• Callback URL Must be publicly accessible and HTTPS. ATOL will POST callbacks to this URL.

• Credentials Login/password are not configurable via services.yaml. Use environment variables or a custom factory:

  // config/services.yaml
  services:
      atol_client.factory:
          class: App\Factory\AtolClientFactory
          arguments:
              - '%env(ATOL_LOGIN)%'
              - '%env(ATOL_PASSWORD)%'