Inpost Pickup Point Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony Bundle for Laravel: The package is designed for Symfony but can be adapted for Laravel via:
  • Facade pattern to abstract Symfony dependencies (e.g., HttpClient, Serializer).
  • Laravel’s Symfony Bridge (symfony/http-client-bridge) for minimal overhead.
  • Standalone components (e.g., guzzlehttp/guzzle, symfony/serializer) if needed.
• API-Centric Design: Aligns with Laravel’s HTTP client (Illuminate\Http\Client) for consistency.
• Event-Driven Potential: Can emit Laravel events (e.g., PickupPointFound) for reactive workflows (e.g., notifications, analytics).

Integration Feasibility

• High for Read-Only Use Cases: Ideal for searching pickup points (no write operations like shipment creation).
• Challenges:
  • Symfony Dependencies: Requires wrapping or replacing Symfony-specific components (e.g., HttpClient → Laravel’s HttpClient).
  • Authentication: Inpost API auth (e.g., OAuth, API keys) must be manually configured in Laravel’s config/services.php.
  • Testing Gap: No bundled tests; requires adding Laravel/Pest tests for reliability.

Technical Risk

Key Questions

1. Symfony vs. Laravel Compatibility:

   • Can we replace Answear\InpostBundle\Client with Laravel’s HttpClient without breaking functionality?
   • Are there Symfony-specific features (e.g., Serializer) that require workarounds?

2. Authentication:

   • How does Inpost’s API auth (e.g., OAuth2, API keys) map to Laravel’s HttpClient?
   • Should we abstract auth into a configurable service provider?

3. Performance:

   • How will pagination (setPage, setPerPage) scale for bulk operations (e.g., 1000+ points)?
   • Should we implement batch processing for large datasets?

4. Error Handling:

   • What are Inpost’s API error codes/responses? Do we need custom Laravel exceptions?
   • How should rate limits or timeouts be handled (e.g., exponential backoff)?

5. Testing:

   • How will we mock the Inpost API in Laravel tests (e.g., Pest, PHPUnit)?
   • Should we add contract tests for the bundle’s public methods?

6. Future-Proofing:

   • Can this bundle be extended for write operations (e.g., shipment creation) if needed?
   • How would we handle multi-country support beyond Poland/Italy?

Integration Approach

Stack Fit

• Laravel 10+: Compatible with PHP 8.4+ and Symfony components via bridges.
• Symfony Components:
  • Replace HttpClient with Laravel’s HttpClient (or use symfony/http-client-bridge).
  • Replace Serializer with Laravel’s Illuminate\Support\Serializer or symfony/serializer.
• Dependencies:
  • guzzlehttp/guzzle (already used by Laravel).
  • php-enum (replaced by PHP 8.1+ enums; no action needed).

Migration Path

1. Phase 1: Wrapper Layer

   • Create a Laravel package (e.g., laravel-inpost-pickup) with:
     • A facade (e.g., Inpost::findPoints()).
     • Service provider to configure auth and HTTP client.
     • Artisan commands for bulk operations.
   • Example:

     // app/Providers/InpostServiceProvider.php
     public function register()
     {
         $this->app->singleton(InpostClient::class, function ($app) {
             return new InpostClient(
                 config('services.inpost.api_key'),
                 new HttpClient(),
                 new Serializer()
             );
         });
     }
     

2. Phase 2: Core Integration

   • Replace Symfony’s HttpClient with Laravel’s:

     // Replace:
     $client = new Client(['base_uri' => $baseUri]);
     // With:
     $client = Http::baseUrl($baseUri);
     

   • Adapt request builders to use Laravel’s HttpClient syntax.

3. Phase 3: Testing & Optimization

   • Add Pest/Laravel tests for:
     • Happy paths (successful point searches).
     • Error scenarios (rate limits, invalid postcodes).
   • Implement Redis caching for frequent queries.

Compatibility

Sequencing

1. Pilot Scope:
   • Start with Poland-only integration (primary market).
   • Focus on checkout pickup point selection (MVP).
2. Expand Scope:
   • Add Italy support (bundle already includes it).
   • Integrate with order tracking (e.g., "Your package is ready at [Point]").
3. Optimize:
   • Add geocoding (e.g., auto-detect user’s location).
   • Implement batch processing for bulk point fetches.

Operational Impact

Maintenance

• Low Ongoing Effort:
  • MIT license; no vendor lock-in.
  • Bundle updates are infrequent (last release: 2026-07-03).
• Dependencies:
  • Monitor guzzlehttp/guzzle and symfony/serializer for breaking changes.
  • Laravel’s built-in HTTP client reduces maintenance overhead.
• Deprecation Risk:
  • Symfony 7+ support is future-proof for Laravel’s long-term roadmap.

Support

• Troubleshooting:
  • Inpost API issues (e.g., rate limits, auth failures) require monitoring (e.g., Sentry, Laravel Log).
  • Laravel’s HttpClient provides built-in error handling.
• Community:
  • Limited stars/contributors; rely on internal testing and Inpost’s docs.
  • Consider opening a GitHub issue for Laravel compatibility feedback.

Scaling

• Performance:
  • Pagination: Use setPage/setPerPage to avoid fetching all points at once.
  • Caching: Cache responses in Redis (e.g., Cache::remember).
  • Batch Processing: For bulk operations, implement queued jobs (e.g., Laravel Queues).
• Load Testing:
  • Simulate high traffic (e.g., 1000+ concurrent searches) to validate pagination and rate limits.

Failure Modes

Ramp-Up

• Onboarding Time:
  • 1–2 weeks for initial wrapper implementation.
  • 2–4 weeks for testing, caching, and edge-case handling.
• Team Skills:
  • PHP/Laravel: Required for adaptation.
  • Symfony: Helpful but not mandatory (bridges abstract complexity).
• Documentation:
  • Internal Docs: Add Laravel-specific usage examples (e.g., facades, events).
  • External Docs: Update README with Laravel installation steps.
• Training:
  • Backend: Focus on HTTP client usage and error handling.
  • Frontend: Demo pickup point selection flow in checkout.