Shipping Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require shopper/shipping
   

   Publish the config file (if available):

   php artisan vendor:publish --provider="Shopper\Shipping\ShippingServiceProvider"
   

2. Basic Configuration Edit config/shipping.php (if published) to define your shipping providers (e.g., FedEx, UPS, USPS). Example:

   'providers' => [
       'fedex' => [
           'key' => env('FEDEX_API_KEY'),
           'account' => env('FEDEX_ACCOUNT'),
           'test_mode' => env('APP_ENV') === 'local',
       ],
   ],
   

3. First Use Case: Fetch Rates

   use Shopper\Shipping\Facades\Shipping;
   
   $rates = Shipping::getRates([
       'origin' => ['zip' => '90210'],
       'destination' => ['zip' => '10001'],
       'package' => ['weight' => 2.5, 'dimensions' => [10, 10, 5]],
   ]);
   

Implementation Patterns

Core Workflows

1. Provider Agnostic Rate Requests Use the facade to abstract provider logic:

   $rates = Shipping::getRates($requestData);
   

   Internally, the package routes requests to configured providers (e.g., FedEx, UPS).

2. Dynamic Provider Selection Override the default provider per request:

   $rates = Shipping::getRates($requestData, 'ups');
   

3. Shipping Label Generation

   $label = Shipping::createLabel($shipmentData, 'fedex');
   

4. Tracking Integration

   $tracking = Shipping::track('FED123456789', 'fedex');
   

Integration Tips

• Laravel Services Bind the Shipping facade to your service container for dependency injection:

  public function __construct(private Shipping $shipping) {}
  

• Request Validation Validate shipping data before passing to the package:

  $validated = $request->validate([
      'origin.zip' => 'required|string',
      'destination.zip' => 'required|string',
      'package.weight' => 'required|numeric',
  ]);
  

• Caching Rates Cache provider responses to reduce API calls:

  $rates = Cache::remember("shipping_rates_{$cacheKey}", now()->addHours(1), function() use ($requestData) {
      return Shipping::getRates($requestData);
  });
  

• Event Listeners Dispatch events for shipping actions (e.g., ShippingRateFetched):

  Shipping::getRates($data)->each(function($rate) {
      event(new ShippingRateFetched($rate));
  });
  

Gotchas and Tips

Pitfalls

1. Missing Config

   • Issue: Forgetting to publish/config the shipping.php file.
   • Fix: Run php artisan vendor:publish and verify provider keys are set in .env.

2. Provider-Specific Quirks

   • Issue: Some providers (e.g., UPS) require additional fields (e.g., shipperNumber).
   • Fix: Check the provider’s documentation and extend the package or config as needed.

3. Rate Limiting

   • Issue: Hitting API rate limits during development/testing.
   • Fix: Enable test_mode in config and mock responses:

     'providers' => [
         'fedex' => [
             'test_mode' => true,
             'mock_response' => file_get_contents(base_path('tests/mocks/fedex_rates.json')),
         ],
     ],
     

4. Error Handling

   • Issue: Unhandled provider API errors (e.g., invalid credentials).
   • Fix: Wrap calls in try-catch and log errors:

     try {
         $rates = Shipping::getRates($data);
     } catch (\Shopper\Shipping\Exceptions\ProviderException $e) {
         Log::error("Shipping error: " . $e->getMessage());
         abort(500, "Shipping service unavailable");
     }
     

Debugging Tips

• Enable Logging Add to config/shipping.php:

  'debug' => env('APP_ENV') === 'local',
  

  Check storage/logs/laravel.log for provider API responses.

• Mock Providers Use Laravel’s HTTP testing to mock provider APIs:

  $this->get('api/fedex/rates')
       ->json(['rates' => [...]]);
  

Extension Points

1. Custom Providers Extend the base Provider class:

   namespace App\Providers;
   
   use Shopper\Shipping\Contracts\Provider;
   
   class CustomProvider implements Provider {
       public function getRates(array $data) { ... }
       public function createLabel(array $data) { ... }
   }
   

   Register in config/shipping.php:

   'providers' => [
       'custom' => \App\Providers\CustomProvider::class,
   ],
   

2. Request/Response Transformers Override the Shipping facade to modify data before/after API calls:

   Shipping::extend(function($app) {
       $app->resolving('shipping', function($shipping) {
           $shipping->beforeGetRates(function($data) {
               $data['custom_field'] = 'value';
               return $data;
           });
       });
   });
   

3. Webhook Handling Listen for provider webhooks (e.g., shipping updates) via Laravel events:

   event(new ShippingWebhookReceived($payload));