Acs Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require answear/acs-bundle
   

   Symfony Flex auto-registers the bundle in config/bundles.php.

2. Configure credentials in config/packages/answear_acs.yaml:

   answear_gls:
       apiKey: "your_api_key"
       companyId: "your_company_id"
       companyPassword: "your_company_password"
       userId: "your_user_id"
       userPassword: "your_user_password"
       language: "GR" # Default (Greece)
   

3. First use case: Fetch parcel shops for Greece (default country):

   use Answear\AcsBundle\Service\ParcelShopsService;
   use Answear\AcsBundle\Enum\CountryIdEnum;
   
   $parcelShopService = $this->container->get(ParcelShopsService::class);
   $shops = $parcelShopService->getList(CountryIdEnum::GREECE);
   

Key Classes to Know

• ParcelShopsService: Core service for fetching parcel shops.
• CountryIdEnum: Enumeration for supported countries (e.g., GREECE, CYPRUS).
• ParcelShop DTO: Response object containing shop details (ID, address, etc.).

Implementation Patterns

Common Workflows

1. Fetching Parcel Shops by Country:

   // All shops in Greece
   $shops = $parcelShopService->getList(CountryIdEnum::GREECE);
   
   // Only convenience shops (kind=1)
   $shops = $parcelShopService->getList(CountryIdEnum::GREECE, 1);
   

2. Integration with Laravel:

   • Service Container Binding: Bind the service in AppServiceProvider:

     $this->app->bind(ParcelShopsService::class, function ($app) {
         return new ParcelShopsService(
             $app->get('answear_acs.client'),
             $app->get('answear_acs.serializer')
         );
     });
     

   • Dependency Injection: Inject ParcelShopsService into controllers/services:

     public function __construct(private ParcelShopsService $parcelShopService) {}
     

3. Caching Responses (Recommended for Performance):

   use Symfony\Component\Cache\Adapter\AdapterInterface;
   
   public function getList(CountryIdEnum $countryId, ?int $kind = null): array
   {
       $cacheKey = "acs_shops_{$countryId->value}_{$kind}";
       if ($cache = $this->cache->get($cacheKey)) {
           return $cache;
       }
   
       $shops = parent::getList($countryId, $kind);
       $this->cache->set($cacheKey, $shops, 3600); // Cache for 1 hour
       return $shops;
   }
   

4. Handling Pagination (If ACS API supports it):

   // Extend the service to support pagination tokens
   public function getListWithPagination(CountryIdEnum $countryId, ?int $kind = null, ?string $token = null): array
   {
       $response = $this->client->request('GET', '/shops', [
           'query' => [
               'country' => $countryId->value,
               'kind' => $kind,
               'token' => $token,
           ],
       ]);
       // Parse response and return shops + next token
   }
   

Gotchas and Tips

Pitfalls

1. Configuration Errors:

   • Missing or invalid credentials (apiKey, companyId, etc.) will throw GuzzleException.
   • Fix: Validate config in config/packages/answear_acs.yaml before use.

2. Country/Kind Validation:

   • CountryIdEnum only supports GREECE and CYPRUS. Passing unsupported values throws InvalidArgumentException.
   • Fix: Use CountryIdEnum::from() or validate input:

     if (!CountryIdEnum::tryFrom($countryId)) {
         throw new \InvalidArgumentException("Unsupported country: {$countryId}");
     }
     

3. Rate Limiting:

   • ACS may throttle requests. Handle ServiceUnavailable exceptions gracefully:

     try {
         $shops = $parcelShopService->getList(CountryIdEnum::GREECE);
     } catch (ServiceUnavailable $e) {
         // Retry logic or notify admin
         $this->logger->error("ACS API unavailable: {$e->getMessage()}");
     }
     

4. Response Parsing:

   • Malformed responses (e.g., non-JSON) trigger MalformedResponse.
   • Debugging Tip: Log raw responses for troubleshooting:

     $response = $this->client->request('GET', '/shops');
     $this->logger->debug("Raw ACS response: {$response->getBody()}");
     

Tips

1. Testing:

   • Mock ParcelShopsService in PHPUnit:

     $mockService = $this->createMock(ParcelShopsService::class);
     $mockService->method('getList')
         ->willReturn([new ParcelShop(/* ... */)]);
     $this->app->instance(ParcelShopsService::class, $mockService);
     

2. Extending Functionality:

   • Add custom endpoints by extending the client:

     // src/Service/CustomAcsService.php
     class CustomAcsService extends ParcelShopsService
     {
         public function getShopDetails(int $shopId): array
         {
             $response = $this->client->request('GET', "/shops/{$shopId}");
             return $this->serializer->deserialize($response->getBody(), ParcelShop::class, 'json');
         }
     }
     

3. Logging:

   • Enable Guzzle logging for debugging:

     # config/packages/answear_acs.yaml
     answear_gls:
         debug: true # Adds logging middleware
     

4. PHP Version Compatibility:

   • The bundle requires PHP 8.4+ and Symfony 7+. Avoid mixing with older versions.

5. Error Handling:

   • Catch specific exceptions for granular control:

     try {
         $shops = $parcelShopService->getList(CountryIdEnum::GREECE);
     } catch (MalformedResponse $e) {
         // Handle parsing errors
     } catch (ServiceUnavailable $e) {
         // Handle API downtime
     }