Mwl Pickup Point Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony/Laravel Compatibility: The bundle is designed for Symfony (via symfony/http-kernel, symfony/serializer, etc.), but Laravel’s Symfony Bridge (illuminate/support) allows partial integration. Key dependencies like Guzzle (HTTP client) and Webmozart Assert are Laravel-compatible.
• Domain Alignment: Fits well in e-commerce, logistics, or delivery workflows where pickup points (e.g., Nova Poshta, Meest) are needed for order fulfillment.
• Modularity: Command-based architecture (GetPickupPoints, GetCities) aligns with Laravel’s console/artisan or service-layer patterns. Can be wrapped in a facade or service class for cleaner usage.

Integration Feasibility

• Low-Coupling: Bundle injects minimal logic; core functionality is API calls wrapped in commands. Laravel’s Service Container can manage dependencies (e.g., ConfigProvider).
• Configuration: YAML-based config (answear_mwl.yaml) maps cleanly to Laravel’s config/mwl.php with environment variables for partnerKey/secretKey.
• API Abstraction: Underlying MWL API (Postman docs provided) can be mocked for testing via Laravel’s HTTP clients or Pest/Mockery.

Technical Risk

• Symfony-Specific Assumptions:
  • Uses symfony/property-access (Laravel alternative: Illuminate\Support\Facades\Arr or Str::of()).
  • Enum usage (Laravel 10+ supports PHP 8.1 enums natively; backport needed for older versions).
• Error Handling: Bundle lacks Laravel-specific exceptions (e.g., HttpClientException). Custom exceptions may be needed.
• Testing: No Laravel test examples; requires adaptation of Symfony’s phpunit setup to Laravel’s PHPUnit or Pest.
• Rate Limiting/Retries: Guzzle’s default config may need Laravel-specific retry logic (e.g., Laravel\Http\Retries).

Key Questions

1. API Stability: Is the MWL API (Postman docs) version-locked, or will breaking changes require bundle updates?
2. Performance: Will pickup-point queries (e.g., by city/carrier) need caching (Laravel’s Cache facade) to avoid rate limits?
3. Authentication: Are partnerKey/secretKey stored securely (Laravel’s Vault or .env)?
4. Webhook Support: Does MWL offer real-time updates (e.g., pickup point status changes)? If so, Laravel’s Queues or Horizon could integrate.
5. Localization: Are pickup points/cities localized? If so, Laravel’s Locale middleware or trans() may need extension.

Integration Approach

Stack Fit

• Laravel 10.x/11.x: Compatible due to PHP 8.2+ and Symfony 6/7 bridge.
• Alternatives:
  • Lumen: Possible but may require manual DI for Symfony components.
  • Livewire/Inertia: Bundle’s data can feed frontend via API routes (e.g., PickupPointController).
• Dependencies:
  • Guzzle 7.x: Laravel’s default HTTP client; no conflicts.
  • Enums: Native in Laravel 10+; use Spatie/Laravel-enum for older versions.

Migration Path

1. Composer Install:

   composer require answear/mwl-pickup-point-bundle guzzlehttp/guzzle
   

2. Publish Config:

   php artisan vendor:publish --tag="answear-mwl-config"
   

   (Adapt config/answear_mwl.yaml to Laravel’s config/mwl.php.)
3. Service Wrapper: Create a Laravel service to abstract commands:

   // app/Services/MwlService.php
   class MwlService {
       public function __construct(
           private GetPickupPoints $getPickupPoints,
           private GetCities $getCities
       ) {}
   
       public function fetchPickupPoints(array $carriers, string $countryCode) {
           return $this->getPickupPoints->execute(
               new GetPickupPointsByCarriersAndCountryCodesRequest(
                   array_map(fn($carrier) => new CarrierAndCountryCode(
                       CarrierEnum::from($carrier),
                       CountryCodeEnum::Ukraine
                   ), $carriers)
               )
           );
       }
   }
   

4. Facade (Optional):

   // app/Facades/Mwl.php
   Facade::register('Mwl', MwlService::class);
   

   Usage: Mwl::fetchPickupPoints(['Meest'], 'UA').

Compatibility

• Symfony vs. Laravel:
  • Replace symfony/property-access with Laravel’s Arr/Str.
  • Mock symfony/http-kernel interfaces if using HTTP tests.
• Testing:
  • Use Laravel’s Http facade to mock Guzzle calls:

    Http::fake([
        'api.mwl.com/*' => Http::response([...]),
    ]);
    

Sequencing

1. Phase 1: Core API integration (pickup points/cities).
2. Phase 2: Add caching (e.g., Cache::remember() for 1-hour TTL).
3. Phase 3: Extend with webhooks/queues if MWL supports real-time updates.
4. Phase 4: Build admin UI (Livewire/Inertia) or API endpoints for frontend.

Operational Impact

Maintenance

• Bundle Updates: Monitor answear/mwl-pickup-point-bundle for MWL API changes. Laravel’s composer.json can pin versions.
• Dependency Conflicts: Guzzle/Symfony versions may need alignment with Laravel’s constraints.
• Logging: Add Laravel’s Log facade to commands for debugging:

  Log::debug('MWL API response', ['data' => $response->getData()]);
  

Support

• Error Tracking: Use Laravel’s Sentry or Laravel Error Tracking to log MWL API failures.
• Fallbacks: Implement retry logic for transient failures (e.g., Laravel\Http\Retries).
• Documentation: Add Laravel-specific usage examples to the bundle’s README (contribute upstream).

Scaling

• Rate Limits: MWL API may throttle requests. Use:
  • Laravel’s Cache for local storage of pickup points.
  • Queue delayed jobs (dispatchSync()) for bulk fetches.
• Database: Store frequently accessed pickup points in pickup_points table with:

  Schema::create('pickup_points', function (Blueprint $table) {
      $table->id();
      $table->string('carrier');
      $table->string('country_code');
      $table->json('coordinates');
      $table->timestamps();
  });
  

• Microservice: For high traffic, extract MWL logic into a separate service with Laravel Queues.

Failure Modes

Ramp-Up

• Onboarding:
  1. Setup: 30 mins to install/config (Composer + .env keys).
  2. Testing: 1 hour to write API tests (Pest/Laravel HTTP tests).
  3. Integration: 2 hours to wrap commands in services/facades.
• Training:
  • Document key methods (fetchPickupPoints, getCities) in Laravel’s app/docs folder.
  • Example: Add a PickupPointFinder trait for reusable logic.
• Rollout:
  • Start with non-critical features (e.g., city lookup).
  • Monitor answear_mwl.* logs in Laravel’s storage/logs.