Meest Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require answear/meest-bundle
   

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

2. First Use Case: Fetch Nova Poshta pickup points (or any DivisionTypeEnum):

   use Answear\MeestBundle\Service\MeestClient;
   use Answear\MeestBundle\Request\SearchDivisions;
   use Answear\MeestBundle\Enum\DivisionTypeEnum;
   
   $client = app(MeestClient::class);
   $response = $client->request(new SearchDivisions(DivisionTypeEnum::NovaPoshtaPoint));
   
   foreach ($response->return as $division) {
       if ($division->active) {
           // Process active pickup points
       }
   }
   

3. Configuration:

   • No manual config required for basic usage. For custom API endpoints or credentials, extend the MeestClient or override its dependencies.

Implementation Patterns

Core Workflows

1. Request-Response Pattern:

   • All API calls use MeestClient::request(RequestInterface).
   • Example requests:
     • SearchDivisions (for pickup points, regions, etc.)
     • GetDivision (fetch details for a specific division)
     • CreateOrder (submit orders to Meest B2B).

2. DTO Handling:

   • Responses return typed DTO objects (e.g., DivisionDTO, OrderDTO).
   • Use @var hints or IDE autocompletion for properties like division->active, division->address.

3. Dependency Injection:

   • Inject MeestClient into services/controllers:

     public function __construct(private MeestClient $meestClient) {}
     

4. Error Handling:

   • Wrap requests in try-catch:

     try {
         $response = $this->meestClient->request($request);
     } catch (\Answear\MeestBundle\Exception\MeestException $e) {
         // Log or handle API errors (e.g., invalid credentials, rate limits)
     }
     

Integration Tips

• Symfony Forms: Bind pickup points to a ChoiceType field:

  $form->add('pickup_point', ChoiceType::class, [
      'choices' => $this->getPickupPoints(),
      'choice_label' => 'address',
  ]);
  

• Commands: Use MeestClient in console commands for bulk operations:

  $this->meestClient->request(new CreateOrder($orderData));
  

• Caching: Cache responses (e.g., pickup points) with Symfony\Component\Cache\Adapter\AdapterInterface:

  $cache = $this->container->get('cache.app');
  $cachedResponse = $cache->get('meest_pickup_points', fn() => $this->meestClient->request($request));
  

Gotchas and Tips

Pitfalls

1. SOAP Dependencies:

   • Ensure ext-soap is enabled (php -m | grep soap). The bundle requires it for API communication.

2. PHP/Symfony Version Mismatch:

   • Bundle drops support for:
     • PHP < 8.2 (since v3.0.0).
     • Symfony < 6 (since v2.0.0).
   • Check composer.json for your project’s compatibility.

3. Response Initialization:

   • Older versions (pre-3.0.2) had issues with uninitialized responses. Update to the latest version if you encounter this.

4. Deprecated Fields:

   • Some API fields (e.g., zipcode) may be deprecated. Refer to the Meest B2B API docs for updates.

Debugging

• Enable SOAP Debugging: Configure the MeestClient to log raw SOAP requests/responses:

  $client = new MeestClient(
      new \Answear\MeestBundle\Client\SoapClient(['trace' => 1])
  );
  

• Common Errors:

  • MeestException: Validate API credentials and request payloads.
  • SoapFault: Check for network issues or SOAP server errors (e.g., timeout).

Extension Points

1. Custom Requests: Extend Answear\MeestBundle\Request\AbstractRequest to create new API calls:

   class CustomRequest extends AbstractRequest {
       public function __construct(public string $customParam) {}
       public function toSoapArray(): array { /* ... */ }
   }
   

2. Override MeestClient: Replace the default client in your services.yaml:

   services:
       Answear\MeestBundle\Service\MeestClient:
           arguments:
               $client: '@custom.soap.client'
   

3. Add New DTOs: Extend Answear\MeestBundle\Response\AbstractDTO for custom response fields:

   class CustomDTO extends AbstractDTO {
       public string $newField;
   }
   

Configuration Quirks

• No Config File: The bundle uses default API endpoints. For custom URLs, override the MeestClient constructor or use environment variables:

  $client = new MeestClient(
      new \Answear\MeestBundle\Client\SoapClient([
          'location' => $_ENV['MEEST_API_URL'],
      ])
  );
  

• Rate Limiting: Meest B2B may throttle requests. Implement exponential backoff in your service layer:

  use Symfony\Component\Stopwatch\Stopwatch;
  
  $stopwatch = new Stopwatch();
  $event = $stopwatch->start('meest_request');
  $response = $this->meestClient->request($request);
  $event->stop();
  
  if ($event->getDuration() > 1000) { // >1s delay
      sleep(1); // Backoff
  }