Getting Started

Minimal Steps

Installation:

composer require answear/acs-bundle

Manually add to config/bundles.php if Symfony Flex doesn’t auto-register:

Answear\AcsBundle\AnswearAcsBundle::class => ['all' => true],

Configuration: Add credentials to config/packages/answear_acs.yaml:

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

First Use Case: Fetch parcel shops in Greece (default language):

use Answear\AcsBundle\Service\ParcelShopsService;
use Answear\AcsBundle\Enum\CountryIdEnum;

$parcelShopService = $container->get(ParcelShopsService::class);
$shops = $parcelShopService->getList(CountryIdEnum::GREECE);

Where to Look First

Service: src/Service/ParcelShopsService.php (core logic).
DTOs: src/Response/DTO/ (response structure).
Exceptions: src/Exception/ (error handling).
Config: config/packages/answear_acs.yaml (credentials).

Implementation Patterns

Usage Patterns

Dependency Injection: Inject ParcelShopsService into controllers/services:

public function __construct(private ParcelShopsService $parcelShopService) {}

Filtering Shops: Fetch shops by type (e.g., ACS_KIND_PARCEL_SHOP):

$shops = $parcelShopService->getList(CountryIdEnum::GREECE, ACS_KIND_PARCEL_SHOP);

Error Handling: Catch ACS-specific exceptions:

try {
    $shops = $parcelShopService->getList(CountryIdEnum::CYPRUS);
} catch (ServiceUnavailable $e) {
    Log::error("ACS API unavailable: " . $e->getMessage());
    return response()->view('errors/503');
} catch (MalformedResponse $e) {
    Log::error("Invalid ACS response: " . $e->getMessage());
}

Configuration Overrides: Override defaults in environment (e.g., .env):
```
ANSWEAR_ACS_LANGUAGE=EN
ANSWEAR_ACS_TIMEOUT=30
```

Workflows

E-commerce Integration:

Use getList() to populate a dropdown of ACS pickup locations.

Example:

$countries = [CountryIdEnum::GREECE, CountryIdEnum::CYPRUS];
$shopsByCountry = collect($countries)->map(fn($country) =>
    $parcelShopService->getList($country)
);

Logistics Dashboard:

Cache shop lists (e.g., every 6 hours) to reduce API calls:

$shops = Cache::remember("acs_shops_{$country->value}", now()->addHours(6), function() use ($country) {
    return $parcelShopService->getList($country);
});

Multi-Carrier Comparison:

Combine ACS shop data with other carriers (e.g., DHL) for a unified UI:

$allShops = [
    'acs' => $parcelShopService->getList(CountryIdEnum::GREECE),
    'dhl' => $dhlService->getLocations(),
];

Integration Tips

Laravel Adaptation:

Replace Symfony’s HttpClient with Laravel’s Http:

// In ParcelShopsService, replace Guzzle with:
$response = Http::withHeaders([
    'Authorization' => 'Basic ' . base64_encode($apiKey . ':' . $companyPassword),
])->get($acsUrl);

DTO Serialization:

Use Spatie\ArrayToObject for DTOs:

use Spatie\ArrayToObject\ArrayToObject;

$shops = ArrayToObject::convert($rawResponse);

Testing:

Mock ParcelShopsService in Laravel tests:

$this->mock(ParcelShopsService::class)->shouldReceive('getList')
    ->once()->andReturn([new ParcelShopDTO()]);

Rate Limiting:

Throttle API calls using Laravel’s throttle middleware:

Route::middleware(['throttle:10,1'])->group(function() {
    Route::get('/acs/shops', [ShopController::class, 'index']);
});

Gotchas and Tips

Pitfalls

Country Limitations:

Only supports Greece (GR) and Cyprus (CY). Attempting other countries may return empty results or errors.

Fix: Validate input in ParcelShopsService:

if (!in_array($countryId->value, [CountryIdEnum::GREECE->value, CountryIdEnum::CYPRUS->value])) {
    throw new \InvalidArgumentException("Unsupported country for ACS");
}

Authentication Quirks:
- ACS requires company-level credentials (companyId, companyPassword) and user credentials (userId, userPassword).
- Fix: Double-check config values in answear_acs.yaml:
```
answear_gls:
    companyId: "12345" # Not userId!
    companyPassword: "secure_pass"
    userId: "user123"
    userPassword: "user_pass"
```

Response Parsing:

ACS may return partial data or non-standard JSON. The bundle’s MalformedResponse exception hides these issues.

Fix: Log raw responses for debugging:

try {
    $shops = $parcelShopService->getList(CountryIdEnum::GREECE);
} catch (MalformedResponse $e) {
    Log::debug("Raw ACS response: " . $e->getRawResponse());
}

Timeouts:
- Guzzle’s default timeout (added in v2.1.1) may be too short for slow ACS responses.
- Fix: Override in config:
```
answear_gls:
    timeout: 60 # seconds
```
  Or via Laravel’s HTTP client:
```
Http::timeout(60)->get($acsUrl);
```

Enum Mismatches:

CountryIdEnum uses GR/CY, but ACS might expect GR/CY or EL/CY.

Fix: Normalize in ParcelShopsService:

$countryCode = match($countryId->value) {
    CountryIdEnum::GREECE->value => 'GR',
    CountryIdEnum::CYPRUS->value => 'CY',
    default => throw new \InvalidArgumentException("Unsupported country"),
};

Debugging

Enable Guzzle Logging: Add to config/services.php:

'http' => [
    'timeout' => 30,
    'debug' => env('APP_DEBUG'), // Logs requests/responses
],

Check ACS API Status:

ACS may have maintenance windows. Monitor their status page (if available).

Fix: Implement a health check endpoint:

Route::get('/acs/health', function() {
    try {
        $parcelShopService->getList(CountryIdEnum::GREECE, limit: 1);
        return response()->json(['status' => 'healthy']);
    } catch (\Exception $e) {
        return response()->json(['status' => 'unhealthy', 'error' => $e->getMessage()], 503);
    }
});

Validate Credentials:

Test credentials with a direct API call (e.g., Postman) before integrating:

GET https://api.acs.gr/parcelshops?country=GR
Headers:
  Authorization: Basic {base64(apiKey:companyPassword)}
  X-User: userId
  X-Password: userPassword

Config Quirks

Language Default:
- Defaults to GR (Greek). Override in config:
```
answear_gls:
    language: "EN" # English responses
```
Missing Fields:
- ACS responses may omit optional fields (e.g., openingHours). The bundle’s DTOs are

Acs Bundle Laravel Package