Inpost Pickup Point Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require answear/inpost-pickup-point-bundle
   

   Note: In Laravel, manually add to config/app.php under providers:

   Answear\InpostBundle\AnswearInpostBundle::class,
   

2. Configuration: Add Inpost API credentials to .env:

   INPOST_API_KEY=your_api_key
   INPOST_BASE_URI=https://api.inpost.pl/shipx/v1
   

3. First Use Case: Search for pickup points by postcode in a Laravel controller:

   use Answear\InpostBundle\Request\FindPointsRequestBuilder;
   use Answear\InpostBundle\Command\FindPoints;
   
   public function findPickupPoints(Request $request)
   {
       $requestBuilder = new FindPointsRequestBuilder();
       $requestBuilder->setPostCode($request->postcode);
   
       $findPointsCommand = app(FindPoints::class);
       $response = $findPointsCommand->findPoints($requestBuilder->build());
   
       return response()->json($response->getPoints());
   }
   

4. Where to Look First:

   • Request Builder: FindPointsRequestBuilder for filtering (e.g., setPostCode, setType).
   • Response Handling: FindPointsResponse for parsing results (e.g., getPoints(), getTotalItemsCount()).
   • API Docs: Inpost SHIPX API for edge cases.

Implementation Patterns

Usage Patterns

1. Real-Time Checkout Integration

• Workflow:
  1. User enters postcode in checkout.
  2. Trigger FindPointsRequestBuilder with setPostCode().
  3. Cache results (e.g., Redis) for 1 hour to reduce API calls.
  4. Render pickup points in a modal (e.g., using Laravel Blade or Livewire).
• Example:

  // In a Livewire component
  public function searchPickupPoints($postcode)
  {
      $request = (new FindPointsRequestBuilder())
          ->setPostCode($postcode)
          ->setPerPage(10)
          ->build();
  
      $response = app(FindPoints::class)->findPoints($request);
      cache()->put("inpost_points_{$postcode}", $response, now()->addHour());
      return $response->getPoints();
  }
  

2. Bulk Operations for Logistics

• Workflow:
  • Fetch pickup points for multiple postcodes in a loop (e.g., for warehouse shipments).
  • Use setPostCodes(array) and setPage() for pagination.
• Example:

  public function fetchBulkPickupPoints(array $postcodes)
  {
      $points = [];
      foreach ($postcodes as $postcode) {
          $request = (new FindPointsRequestBuilder())
              ->setPostCodes([$postcode])
              ->setPerPage(50)
              ->build();
  
          $response = app(FindPoints::class)->findPoints($request);
          $points[$postcode] = $response->getPoints();
      }
      return $points;
  }
  

3. Command-Line Tooling

• Workflow:
  • Create an Artisan command to pre-fetch and cache pickup points for high-traffic areas.
• Example:

  // app/Console/Commands/FetchInpostPoints.php
  use Illuminate\Console\Command;
  use Answear\InpostBundle\Request\FindPointsRequestBuilder;
  use Answear\InpostBundle\Command\FindPoints;
  
  class FetchInpostPoints extends Command
  {
      protected $signature = 'inpost:fetch {--postcode=*}';
      protected $description = 'Fetch and cache Inpost pickup points';
  
      public function handle()
      {
          $postcodes = $this->option('postcode') ?: ['00-001', '00-999'];
          foreach ($postcodes as $postcode) {
              $request = (new FindPointsRequestBuilder())
                  ->setPostCode($postcode)
                  ->build();
  
              $response = app(FindPoints::class)->findPoints($request);
              cache()->forever("inpost_{$postcode}", $response);
              $this->info("Cached {$postcode}: " . count($response->getPoints()) . " points");
          }
      }
  }
  

  Run with:

  php artisan inpost:fetch --postcode=02-123 --postcode=01-234
  

4. Event-Driven Caching

• Workflow:
  • Listen for Illuminate\Cache\Events\KeyGenerated to invalidate cached pickup points when postcode data changes (e.g., via a webhook).
• Example:

  // In EventServiceProvider
  protected $listen = [
      'Illuminate\Cache\Events\KeyGenerated' => [
          'App\Listeners\InvalidateInpostCache',
      ],
  ];
  

Integration Tips

1. Laravel Service Container: Bind the Symfony command to Laravel’s container in AppServiceProvider:

   public function register()
   {
       $this->app->bind(
           Answear\InpostBundle\Command\FindPoints::class,
           function ($app) {
               return new Answear\InpostBundle\Command\FindPoints(
                   $app->make(Answear\InpostBundle\Client\InpostClient::class)
               );
           }
       );
   }
   

2. API Client Customization: Extend the Guzzle client for Laravel-specific needs (e.g., middleware for logging):

   // config/inpost.php
   'client' => [
       'timeout' => 30,
       'headers' => [
           'Accept' => 'application/json',
           'User-Agent' => 'Laravel-Inpost-Integration/1.0',
       ],
       'middleware' => [
           \App\Http\Middleware\LogInpostRequests::class,
       ],
   ],
   

3. Response Wrapping: Create a Laravel-friendly response DTO:

   namespace App\DTO;
   
   class InpostPickupPoint
   {
       public function __construct(
           public string $id,
           public string $name,
           public string $address,
           public string $postCode,
           public string $city,
           public float $distance,
       ) {}
   }
   

   Transform the bundle’s response:

   $points = collect($response->getPoints())->map(function ($point) {
       return new InpostPickupPoint(
           $point['id'],
           $point['name'],
           $point['address']['street'],
           $point['address']['postCode'],
           $point['address']['city'],
           $point['distance'] ?? 0,
       );
   });
   

4. Testing: Mock the FindPoints command in Laravel tests:

   use Answear\InpostBundle\Command\FindPoints;
   use Answear\InpostBundle\Request\FindPointsRequest;
   use Answear\InpostBundle\Response\FindPointsResponse;
   
   $mockResponse = new FindPointsResponse([], 10);
   $mockCommand = Mockery::mock(FindPoints::class);
   $mockCommand->shouldReceive('findPoints')
       ->withArgs(function (FindPointsRequest $request) {
           return $request->getPostCode() === '00-001';
       })
       ->andReturn($mockResponse);
   
   $this->app->instance(FindPoints::class, $mockCommand);
   

Gotchas and Tips

Pitfalls

1. Symfony Dependency Conflicts:

   • The bundle uses Symfony’s PropertyInfo and Serializer. If your Laravel app uses these components elsewhere (e.g., API Platform), conflicts may arise.
   • Fix: Vendor the required Symfony packages (e.g., symfony/property-info, symfony/serializer) or use Laravel’s native alternatives (e.g., spatie/laravel-array-to-object).

2. PHP 8.4+ Requirement:

   • Laravel 10+ supports PHP 8.4, but older Laravel versions (e.g., 9.x) may not.
   • Fix: Use a Laravel version manager (e.g., laravel-shift) or pin PHP 8.2 in composer.json:

     "config": {
         "platform": {
             "php": "8.2.0"
         }
     }
     

3. GET Request Body Issue:

   • Release 4.1.0 fixed a bug where request bodies were incorrectly sent with GET requests. Ensure you’re using >=4.1.0.
   • Fix: Update the package:

     composer update answear/inpost-pickup-point-bundle
     

4. Rate Limiting:

   • Inpost’s API may throttle requests. The bundle lacks built-in retry logic.
   • Fix: Add Guzzle