Econt Pickup Point Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require answear/econt-pickup-point-bundle
   

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

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

   answear_econt:
       user: 'your_econt_username'
       password: 'your_econt_password'
   

3. First use case: Fetch pickup offices Inject the GetOffices command via dependency injection (DI) and call it with a request:

   use Answear\EcontBundle\Command\GetOffices;
   use Answear\EcontBundle\Request\GetOfficesRequest;
   
   // In a service/controller
   $getOffices = $this->container->get(GetOffices::class);
   $response = $getOffices->getOffices(new GetOfficesRequest());
   

Implementation Patterns

Core Workflow: Data Fetching

1. Request Creation Use dedicated request classes (e.g., GetOfficesRequest, GetCitiesRequest) to structure API calls. Example:

   $request = new GetOfficesRequest();
   $request->setCityId('WAR'); // Warsaw city code
   

2. Command Execution Inject commands via DI and execute them:

   $cities = $this->get(GetCities::class)->getCities(new GetCitiesRequest());
   

3. Response Handling Responses are typically objects with methods like getData() or getOffices(). Validate responses:

   if ($response->isSuccess()) {
       $offices = $response->getData();
   }
   

Integration Tips

1. Caching Responses Cache API responses (e.g., cities/offices) to reduce calls:

   $cacheKey = 'econt_offices_' . $cityId;
   $offices = Cache::remember($cacheKey, now()->addHours(1), function () use ($cityId) {
       return $this->get(GetOffices::class)->getOffices(new GetOfficesRequest($cityId))->getData();
   });
   

2. Error Handling Wrap API calls in try-catch blocks to handle exceptions (e.g., EcontException):

   try {
       $response = $getOffices->getOffices($request);
   } catch (EcontException $e) {
       $this->logger->error('Econt API error: ' . $e->getMessage());
       throw new \RuntimeException('Failed to fetch offices', 0, $e);
   }
   

3. Dependency Injection Register commands as services in services.yaml for easier testing:

   services:
       Answear\EcontBundle\Command\GetOffices:
           arguments:
               $configProvider: '@answear_econt.config_provider'
   

4. Testing Mock the ConfigProvider or use a test double for the EcontClient to isolate tests:

   $this->mock(EcontClient::class)
       ->shouldReceive('getOffices')
       ->andReturn(new GetOfficesResponse([...]));
   

Gotchas and Tips

Pitfalls

1. Authentication Failures

   • Ensure user/password in answear_econt.yaml are correct. Test credentials via the Econt API docs.
   • Debug tip: Log the full request payload to verify credentials are passed:

     $configProvider = $this->app->get(ConfigProvider::class);
     $this->logger->debug('Econt Config:', ['user' => $configProvider->getUser()]);
     

2. Rate Limiting

   • The API may throttle requests. Add delays between calls if needed:

     sleep(1); // 1-second delay
     

3. Deprecated Methods

   • Avoid hardcoding cityId as strings (e.g., 'WAR'). Use constants or enums for maintainability:

     final class CityCodes {
         public const WARSAW = 'WAR';
     }
     

4. Response Validation

   • Not all responses are guaranteed to have getData(). Check for methods dynamically:

     if (method_exists($response, 'getData')) {
         $data = $response->getData();
     }
     

Debugging Tips

1. Enable Guzzle Debugging Configure Guzzle to log requests/responses in config/packages/answear_econt.yaml:

   answear_econt:
       debug: true
   

   This will output raw API calls to var/log/dev.log.

2. Timeout Issues

   • If requests hang, increase the Guzzle timeout (default: 10s):

     answear_econt:
           timeout: 30 # seconds
     

3. PHP 8.4+ Compatibility

   • Use strict types and named arguments where possible to avoid deprecation warnings:

     $request = new GetOfficesRequest(cityId: 'WAR');
     

Extension Points

1. Custom Requests Extend the base Request class to add custom parameters:

   class CustomOfficesRequest extends GetOfficesRequest {
       public function __construct(
           string $cityId,
           private ?string $customParam = null
       ) {
           parent::__construct($cityId);
       }
   }
   

2. Response Transformers Create a decorator for responses to normalize data:

   class OfficeResponseDecorator {
       public function __construct(private GetOfficesResponse $response) {}
   
       public function getFormattedOffices(): array {
           return array_map(function ($office) {
               return [
                   'id' => $office->getId(),
                   'name' => $office->getName(),
                   'address' => $office->getAddress(),
               ];
           }, $this->response->getData());
       }
   }
   

3. Event Listeners Trigger events on API responses (e.g., log successful calls):

   // In a service
   $dispatcher->dispatch(new EcontResponseEvent($response));
   

4. Symfony Messenger Integrate with Symfony’s Messenger component to process responses asynchronously:

   $message = new ProcessEcontOfficesMessage($response->getData());
   $this->messageBus->dispatch($message);