Mwl Pickup Point Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require answear/mwl-pickup-point-bundle
   

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

2. Configuration Add credentials to config/packages/answear_mwl.yaml:

   answear_mwl:
       partnerKey: 'your-partner-key'
       secretKey: 'your-secret-key'
   

3. First Use Case Fetch pickup points for a specific carrier/country:

   use Answear\MwlBundle\Command\GetPickupPointsByCarriersAndCountryCodes;
   use Answear\MwlBundle\Request\GetPickupPointsByCarriersAndCountryCodesRequest;
   use Answear\MwlBundle\Request\Struct\CarrierAndCountryCode;
   use Answear\MwlBundle\Enum\{CarrierEnum, CountryCodeEnum};
   
   $request = new GetPickupPointsByCarriersAndCountryCodesRequest([
       new CarrierAndCountryCode(CarrierEnum::Meest, CountryCodeEnum::Ukraine)
   ]);
   
   $response = app()->get(GetPickupPointsByCarriersAndCountryCodes::class)
       ->getPickupPointsByCarriersAndCountryCodesRequest($request);
   

Key Classes to Explore

• Commands: GetPickupPoints, GetPickupPointsByCarriersAndCountryCodes, GetCities
• Requests: GetPickupPointsRequest, GetCitiesRequest
• Enums: CarrierEnum, CountryCodeEnum
• Response Handling: ResponseInterface (added in v2.2.0)

Implementation Patterns

Core Workflows

1. Carrier-Specific Pickup Points

   // Fetch pickup points for multiple carriers/countries
   $request = new GetPickupPointsByCarriersAndCountryCodesRequest([
       new CarrierAndCountryCode(CarrierEnum::Meest, CountryCodeEnum::Ukraine),
       new CarrierAndCountryCode(CarrierEnum::NovaPoshta, CountryCodeEnum::Poland),
   ]);
   

2. City Lookup for UI Autocomplete

   // Fetch cities for a country (e.g., for dropdowns)
   $cities = app()->get(GetCities::class)
       ->getCities(new GetCitiesRequest(CountryCodeEnum::Ukraine));
   

3. Response Transformation Use the ResponseInterface (v2.2.0+) to normalize responses:

   $response = $command->execute($request);
   $data = $response->getData(); // Array of pickup points/cities
   

Integration Tips

• Service Container Binding Bind commands to interfaces for testability:

  $container->bind(
      GetPickupPointsByCarriersAndCountryCodes::class,
      fn() => new GetPickupPointsByCarriersAndCountryCodes(
          new ConfigProvider($config),
          new HttpClient()
      )
  );
  

• Caching Responses Cache API responses (e.g., cities) with Symfony Cache component:

  $cache = $container->get('cache.app');
  $cachedCities = $cache->get('mwl_cities_ua', fn() => $command->getCities(...));
  

• Error Handling Wrap commands in try-catch for API errors:

  try {
      $response = $command->execute($request);
  } catch (ApiException $e) {
      report($e); // Log or notify
      return back()->withError('Pickup point service unavailable');
  }
  

• Laravel-Specific Adaptation Use Laravel’s app() helper or bind commands to the container:

  $this->app->singleton(GetPickupPoints::class, fn() => new GetPickupPoints(...));
  

Gotchas and Tips

Common Pitfalls

1. Authentication Failures

   • Symptom: 401 Unauthorized or empty responses.
   • Fix: Verify partnerKey/secretKey in answear_mwl.yaml and check MWL API docs for key validity.

2. Rate Limiting

   • MWL may throttle requests. Implement exponential backoff:

     use Symfony\Component\HttpClient\RetryableHttpClient;
     $client = new RetryableHttpClient($baseClient, [
         'max_retries' => 3,
         'delay' => 1000,
         'multiplier' => 2,
     ]);
     

3. Deprecated Methods

   • Avoid getPickupPoints() (v1.x) in favor of getPickupPointsByCarriersAndCountryCodes() (v2.1.0+).

4. Country/Carrier Coverage

   • Not all carriers/countries are supported. Validate enums against MWL’s supported list.

Debugging Tips

• Enable Guzzle Debugging Add to config/packages/answear_mwl.yaml:

  answear_mwl:
      debug: true # Logs requests/responses to Symfony profiler
  

• Response Inspection Use var_dump($response->getData()) or dd($response->getRawResponse()) to debug raw API responses.

Extension Points

1. Custom Request/Response Mappers Extend Request\AbstractRequest or implement ResponseInterface for custom transformations:

   class CustomResponse implements ResponseInterface {
       public function getData(): array {
           return array_map(fn($point) => [
               'id' => $point['id'],
               'formatted_address' => $point['address'] . ', ' . $point['city'],
           ], $this->rawData);
       }
   }
   

2. Adding New Carriers Extend CarrierEnum and update the GetPickupPointsByCarriersAndCountryCodes command to handle new carriers.

3. Webhook Integration Use the bundle’s HTTP client to listen for MWL webhooks (e.g., pickup point updates):

   $client->request('POST', 'https://api.mwl.com/webhooks', [
       'json' => ['event' => 'pickup_point_updated', 'data' => [...]],
   ]);
   

Configuration Quirks

• Environment Variables For security, use .env with config/packages/answear_mwl.yaml:

  answear_mwl:
      partnerKey: '%env(MWL_PARTNER_KEY)%'
      secretKey: '%env(MWL_SECRET_KEY)%'
  

• Default Country The GetCities command defaults to CountryCodeEnum::Ukraine. Override in the request:

  new GetCitiesRequest(CountryCodeEnum::Poland)
  

Performance Optimizations

• Batch Processing For large datasets, paginate responses:

  $request->setLimit(100); // If MWL supports pagination
  

• Lazy Loading Use generators for memory efficiency:

  function getPickupPointsGenerator(): Generator {
      $response = $this->command->execute($request);
      foreach ($response->getData() as $point) {
          yield $point;
      }
  }