Inpost Pickup Point Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Modularity: The bundle’s command-pattern (FindPoints) and request-builder (FindPointsRequestBuilder) align well with Laravel’s service-oriented architecture. It can be encapsulated as a Laravel service without tight coupling to Symfony’s Bundle structure.
• API Abstraction: Ideal for logistics modules where pickup point searches are a discrete feature (e.g., checkout flow, admin dashboards). The bundle’s focus on read-only operations (searching, not creating shipments) reduces scope creep.
• Extensibility: Supports event-driven workflows (e.g., caching responses, triggering notifications) via Laravel’s events/listeners or queues. Could be extended to integrate with:
  • Laravel Scout (for geospatial searches of pickup points).
  • Laravel Echo (real-time updates for point availability).
• Internationalization: Built-in support for Poland and Italy (via PointFunctionsType enums) enables phased rollouts for EU markets.

Integration Feasibility

• Symfony-to-Laravel Adaptation:
  • Service Container: Replace Symfony’s services.yaml with Laravel’s bindings in AppServiceProvider:

    $this->app->bind(
        Answear\InpostBundle\Request\FindPointsInterface::class,
        Answear\InpostBundle\Request\FindPoints::class
    );
    

  • Commands: Convert Symfony’s Command to Laravel’s Artisan command:

    Artisan::command('inpost:find-points', function () {
        $request = (new FindPointsRequestBuilder())->setPostCode('00-001')->build();
        $response = app(FindPointsInterface::class)->findPoints($request);
        // Output or process response
    });
    

  • HTTP Client: Leverage Laravel’s Guzzle integration (Http::client()) to avoid Symfony’s HttpClient dependency.
• PHP Enums: Laravel 8.3+ natively supports PHP 8.1+ enums (used in PointType, PointFunctionsType), so no additional abstraction is needed.
• Configuration: Replace Symfony’s config/packages/answear_inpost.yaml with Laravel’s .env and config files:

  INPOST_API_KEY=your_key
  INPOST_BASE_URI=https://api.inpost.pl
  

Technical Risk

• Symfony Component Bloat: Introduces dependencies like symfony/serializer and symfony/property-info, which may not be used elsewhere. Mitigation: Use standalone Composer packages (e.g., symfony/serializer without the full Symfony bundle).
• Testing Complexity: No bundled tests or Laravel-specific test examples. Mitigation:
  • Use PestPHP or Laravel’s Http::fake() to mock API responses.
  • Add feature tests for critical paths (e.g., postcode search, pagination).
• Error Handling: Relies on Guzzle exceptions. Mitigation:
  • Wrap API calls in Laravel’s try-catch and log errors via Log::error().
  • Extend with custom exceptions (e.g., InpostApiException).
• Performance: API calls are synchronous. Mitigation:
  • For high-frequency use, implement queueing (e.g., FindPointsJob with shouldQueue()).
  • Cache responses with Laravel Cache (e.g., Cache::remember()).
• Deprecation Risk: Bundle is updated sporadically (last release: 2026-05-21). Mitigation:
  • Fork the repo to maintain Laravel compatibility.
  • Monitor Inpost API changes (e.g., breaking changes in SHIPX).

Key Questions

1. API Usage Patterns:
   • Will pickup point searches be user-triggered (e.g., checkout) or batch-processed (e.g., nightly syncs for all cities)?
   • Does the app need webhook support for real-time updates (e.g., point availability changes)?
2. Caching Strategy:
   • Should responses be cached per user session (e.g., "nearby points for this postcode") or globally (e.g., all Polish points)?
   • What’s the cache invalidation strategy (e.g., TTL, manual refresh)?
3. Localization:
   • Does the app need to translate point names/cities (e.g., Polish → English)?
   • Should the UI support multi-language queries (e.g., search by city name in PL/IT)?
4. Monitoring:
   • Should API metrics (e.g., latency, failure rates) be tracked in Laravel Horizon or Prometheus?
   • Are alerts needed for API failures (e.g., Slack notifications)?
5. Testing:
   • Should contract tests be written to verify the bundle’s API responses match Inpost’s schema?
   • How will edge cases (e.g., invalid postcodes, rate limits) be tested?
6. Future-Proofing:
   • Does the app plan to extend beyond pickup points (e.g., parcel tracking, label generation)? If so, a direct Inpost API integration (not this bundle) may be better.
   • Should the integration support multi-carrier comparisons (e.g., Inpost vs. DHL for cost/distance)?

Integration Approach

Stack Fit

• Laravel 10+: Fully compatible with PHP 8.4 and Guzzle 7.x. No major conflicts with Laravel’s ecosystem.
• Dependencies:
  • Guzzle: Native support in Laravel (Http::client() or GuzzleHttp\Client).
  • Symfony Components: Can be opt-in (e.g., only symfony/serializer if needed for response parsing) or replaced with Laravel equivalents (e.g., spatie/array-to-object for deserialization).
  • PHP Enums: Native support in Laravel 8.3+.
  • Artisan Commands: Direct replacement for Symfony’s Command class.
• Database: No ORM required, but responses can be cached in Redis or stored in a local table (e.g., pickup_points) for offline use.
• Queue System: Supports asynchronous processing (e.g., bulk searches) via Laravel Queues.

Migration Path

1. Phase 1: Package Wrapping (1–2 weeks)
   • Create a Laravel-compatible facade/service (e.g., InpostService) that:
     • Adapts the bundle’s FindPointsRequestBuilder to Laravel’s DI.
     • Replaces Symfony’s HttpClient with Laravel’s Http::client().
     • Exposes methods like findPointsByPostcode(string $postcode): array.
   • Example:

     namespace App\Services;
     
     use Answear\InpostBundle\Request\FindPointsRequestBuilder;
     use Illuminate\Support\Facades\Http;
     
     class InpostService {
         public function findPoints(string $postcode): array {
             $request = (new FindPointsRequestBuilder())->setPostCode($postcode)->build();
             $response = Http::withHeaders([
                 'Authorization' => config('inpost.api_key'),
             ])->post(config('inpost.api_endpoint'), $request->toArray());
     
             return $response->json();
         }
     }
     

2. Phase 2: Integration (1 week)
   • Configuration: Add to config/services.php:

     'inpost' => [
         'api_key' => env('INPOST_API_KEY'),
         'api_endpoint' => 'https://api.inpost.pl/shipx/v1/points',
         'cache_ttl' => env('INPOST_CACHE_TTL', 3600), // 1 hour
     ],
     

   • Caching: Decorate InpostService to cache responses:

     public function findPoints(string $postcode): array {
         return Cache::remember(
             "inpost_points_{$postcode}",
             config('inpost.cache_ttl'),
             fn() => $this->fetchFromApi($postcode)
         );
     }
     

   • Commands: Add Laravel Artisan commands for CLI access:

     Artisan::command('inpost:search {postcode}', function ($postcode) {
         $points = app(InpostService::class)->findPoints($postcode);
         dd($points);
     });
     

3. Phase 3: UI Integration (2 weeks)
   • Frontend: Use the service in Livewire/Inertia.js or API routes:

     Route::get('/api/pickup-points', function (Request $request) {
         return app(InpostService::class)->findPoints($request->postcode);
     });
     

   • Checkout Flow: Implement a modal/dropdown to display points:

     // Example: Fetch points on postcode input
     document.getElement