Taming the Shipping Beast: A Modern PHP/Laravel SDK for the Shippo API

Shipping can be a major headache for any e-commerce business. From comparing carrier rates to printing labels and tracking packages, the logistics can quickly become overwhelming. This is where services like Shippo come in, offering a unified platform to streamline the entire shipping process. But to truly unlock the power of Shippo, you need a way to integrate it into your applications.

Today, we're going to explore a brand new, modern PHP/Laravel client for the Shippo API that makes this integration a breeze: tigusigalpa/shippo-php.

What is Shippo and Why Should You Care?

For those unfamiliar, Shippo is a multi-carrier shipping API and platform that acts as a bridge between your business and a global network of shipping carriers like USPS, FedEx, UPS, and DHL. Instead of building and maintaining separate integrations for each carrier, Shippo provides a single, unified API to:

Shippo provides a single, unified API to compare shipping rates, purchase labels, validate addresses, track packages, and handle international customs.

By using Shippo, developers can save countless hours of development time and businesses can save significant money on shipping costs, with discounts of up to 90% on some carriers. It’s a powerful tool for any application that deals with physical goods.

Introducing shippo-php: A Modern PHP SDK for Shippo

While Shippo has an official client, tigusigalpa/shippo-php by Igor Sazonov provides a more modern and robust experience, especially for Laravel developers. It's built with PHP 8.1+ and adheres to the latest PSR standards.

Here are some of the standout features:

Key features include modern PHP 8.1+ support, PSR compliance, type-safe DTOs for all API responses, automatic retry logic for rate limits, seamless Laravel integration with a dedicated Facade, and comprehensive exception handling.

Getting Started

Installation is straightforward with Composer:

composer require tigusigalpa/shippo-php

For Laravel Users

The package auto-registers its service provider. All you need to do is publish the config file and add your API token to your .env file.

php artisan vendor:publish --tag=shippo-config

SHIPPO_API_TOKEN=your_shippo_api_token_here
SHIPPO_IS_TEST=true

Now you can use the Shippo facade anywhere in your Laravel application.

Standalone PHP

You can also use the library in any PHP project. Just instantiate the Shippo class with a PSR-18 HTTP client and a configuration object.

use GuzzleHttp\Client as GuzzleClient;
use GuzzleHttp\Psr7\HttpFactory;
use Tigusigalpa\Shippo\Shippo;
use Tigusigalpa\Shippo\Config;

$httpFactory = new HttpFactory();
$config = Config::make('your_api_token');

$shippo = new Shippo(
    httpClient: new GuzzleClient(),
    requestFactory: $httpFactory,
    streamFactory: $httpFactory,
    config: $config
);

A Quick Example: Creating a Shipping Label

Creating a shipping label is simple. It involves creating a shipment with address and parcel details, selecting a rate, and purchasing the label.

use Tigusigalpa\Shippo\Laravel\Facades\Shippo;

// 1. Create a shipment
$shipment = Shippo::shipments()->create([
    'address_from' => [ /* ... */ ],
    'address_to' => [ /* ... */ ],
    'parcels' => [ /* ... */ ],
]);

// 2. Select the cheapest rate
$rateId = $shipment->rates[0]['object_id'];

// 3. Purchase the label
$transaction = Shippo::transactions()->create([
    'rate' => $rateId,
    'label_file_type' => 'PDF',
]);

// 4. Get your label and tracking number!
echo "Label URL: {$transaction->labelUrl}\n";
echo "Tracking Number: {$transaction->trackingNumber}\n";

The library supports all major Shippo API endpoints. For more examples, including address validation, tracking, and customs, check out the GitHub repository.

Conclusion

For any PHP or Laravel project integrating with Shippo, tigusigalpa/shippo-php is an excellent choice. Its modern design and robust features will help you write cleaner, more reliable shipping code. Give it a try and tame the shipping beast in your next project!

References