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 your MWL 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 (e.g., Meest in Ukraine):

   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);
   

4. Key Classes:

   • Commands: GetPickupPoints, GetPickupPointsByCarriersAndCountryCodes, GetCities
   • Enums: CarrierEnum, CountryCodeEnum (for filtering)
   • Requests: Structured DTOs for API calls (e.g., GetPickupPointsRequest).

Implementation Patterns

Core Workflows

1. Fetching Pickup Points:

   • Broad Search: Use GetPickupPoints for all points (no filters).

     $response = app()->get(GetPickupPoints::class)
         ->getPickupPoints(new GetPickupPointsRequest());
     

   • Filtered Search: Use GetPickupPointsByCarriersAndCountryCodes for targeted results (e.g., Meest in Poland).

     $response = app()->get(GetPickupPointsByCarriersAndCountryCodes::class)
         ->getPickupPointsByCarriersAndCountryCodesRequest($filteredRequest);
     

2. City Lookup: Fetch cities by country (e.g., for dropdowns in UIs):

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

3. Response Handling:

   • Responses are typed objects (not raw arrays). Access data via methods:

     $pickupPoints = $response->getPickupPoints();
     foreach ($pickupPoints as $point) {
         echo $point->getName(); // e.g., "Nova Poshta #12345"
     }
     

   • Use getResponse() (added in v2.2.0) for raw API responses if needed.

Integration Tips

1. Dependency Injection: Bind commands to services for reusability:

   // services.yaml
   services:
       Answear\MwlBundle\Command\GetPickupPointsByCarriersAndCountryCodes:
           tags: ['container.service_subscriber']
   

   Then inject via constructor:

   public function __construct(
       private GetPickupPointsByCarriersAndCountryCodes $command
   ) {}
   

2. Caching: Cache responses (e.g., cities/pickup points) to reduce API calls:

   $cacheKey = 'mwl_pickup_points_meest_ua';
   $pickupPoints = Cache::remember($cacheKey, 3600, fn() => $command->execute($request));
   

3. Error Handling: Wrap calls in try-catch for API errors:

   try {
       $response = $command->execute($request);
   } catch (\Answear\MwlBundle\Exception\MwlException $e) {
       // Log or retry (e.g., $e->getCode() for HTTP status)
       throw new \RuntimeException('MWL API failed', 0, $e);
   }
   

4. Testing: Mock the ConfigProvider to isolate tests:

   $this->mock(ConfigProvider::class)
       ->shouldReceive('getPartnerKey')
       ->andReturn('test-key');
   

Gotchas and Tips

Pitfalls

1. Authentication:

   • Missing Keys: If partnerKey/secretKey are invalid, the API returns 401 Unauthorized. Validate config early:

     if (empty(config('answear_mwl.partnerKey'))) {
         throw new \RuntimeException('MWL keys not configured');
     }
     

   • Rate Limits: MWL may throttle requests. Implement exponential backoff for retries.

2. Data Structure:

   • Response Parsing: The bundle returns objects, not arrays. Avoid:

     // ❌ Wrong (throws UndefinedIndexException)
     $response['pickupPoints'][0]['name'];
     

     Use:

     // ✅ Correct
     $response->getPickupPoints()[0]->getName();
     

3. Enum Usage:

   • Case Sensitivity: CarrierEnum::MEEST (uppercase) vs. CarrierEnum::Meest (PascalCase). Stick to the latter.

4. Deprecations:

   • v2.0+: Older methods (e.g., getCitiesByCountry) may be deprecated. Prefer new structured requests.

Debugging

1. Raw API Responses: Use getResponse() (v2.2.0+) to inspect raw data:

   $rawResponse = $response->getResponse();
   dd($rawResponse->getBody()->getContents());
   

2. Logging: Enable Guzzle logging to debug HTTP calls:

   $client = new \GuzzleHttp\Client([
       'handler' => \GuzzleHttp\HandlerStack::create([
           new \GuzzleHttp\Middleware::tap(function ($request, $options) {
               \Monolog\Logger::getInstance()->info('MWL Request:', [
                   'url' => (string) $request->getUri(),
                   'method' => $request->getMethod(),
               ]);
           }),
       ]),
   ]);
   

   Bind the custom client to the bundle’s HttpClient service.

3. Common Errors:

   • 400 Bad Request: Invalid CarrierAndCountryCode combinations (e.g., Meest + Germany).
   • 500 Server Error: Contact MWL support; cache responses temporarily.

Extension Points

1. Custom Requests: Extend the Request classes to add fields (e.g., radius search):

   class CustomPickupPointsRequest extends GetPickupPointsRequest {
       public function __construct(
           public ?int $radius = null,
           public ?string $city = null
       ) {}
   }
   

   Update the command to handle the new request.

2. Response Transformers: Decorate responses for your domain:

   $transformed = $response->getPickupPoints()->map(fn($point) => new PickupPointDto(
       $point->getId(),
       $point->getName(),
       // ...
   ));
   

3. Event Listeners: Trigger events on successful/failed API calls:

   // src/EventListener/MwlListener.php
   public function onMwlResponse(MwlResponseEvent $event) {
       if ($event->isSuccess()) {
           Cache::put('mwl_last_sync', now());
       }
   }
   

   Register the listener in services.yaml.

4. Testing Helpers: Create a test double for ConfigProvider:

   // tests/Unit/Mock/MwlConfigProvider.php
   class MockConfigProvider extends ConfigProvider {
       public function getPartnerKey() { return 'test-key'; }
       public function getSecretKey() { return 'test-secret'; }
   }
   

   Override the service in tests:

   $this->app->bind(ConfigProvider::class, MockConfigProvider::class);