G'day Shippy!

Verbb Team Verbb Team May 2024 3 min read

Say hello to Shippy — our first non-Craft CMS-related release! It's a PHP, framework agnostic and open-source shipping library for fetching rates, creating shipments, tracking updates and more.

Shippy has been inspired by other exceptional projects that provide a singular abstraction layer when communicating with many third-party providers like league/omnipay and league/oauth2-client.

While there are several paid services out there that do the same thing as Shippy, we wanted to create an open-source one with the source code freely available and open to the community. To our knowledge, nothing out there exists that's well-supported, works with multiple carriers and is free.

Why use Shippy?#

Of course, you can connect to a carrier like UPS via their API or use one of the aforementioned paid (via a monthly fee) SaaS products if that's all you wish to use, but there are plenty of reasons to use Shippy.

  • It's free! Zero subscription services or ongoing fees
  • You can learn a single API for use in multiple projects, and handle multiple carriers
  • If you want to add support for multiple carriers, or switch to another carrier, you don't need to install another package and get to know their API
  • Shippy takes care of API changes so you don't have to

Shippy aims to be the go-to package when you want to have a consistent API for dealing with shipping carrier APIs.

Get Shippy#

Getting started with Shippy is pretty straightforward by installing the verbb/shippy package via Composer in any PHP project.

composer require verbb/shippy

Then, let's fetch some shipping rates for UPS and FedEx:

use verbb\shippy\carriers\FedEx;
use verbb\shippy\carriers\UPS;
use verbb\shippy\models\Address;
use verbb\shippy\models\Package;
use verbb\shippy\models\Shipment;

// Create a shipment to set the from/to address details
$shipment = new Shipment([
    // You can supply config arrays for quick setting.
    'from' => new Address([
        'street1' => 'One Infinite Loop',
        'city' => 'Cupertino',
        'stateProvince' => 'CA',
        'postalCode' => '95014',
        'countryCode' => 'US',
    ]),
]);

// You can use traditional setters if you prefer
$toAddress = new Address();
$toAddress->setStreet1('1600 Amphitheatre Parkway');
$toAddress->setCity('Mountain View');
$toAddress->setStateProvince('CA');
$toAddress->setPostalCode('94043');
$toAddress->setCountryCode('US');
$shipment->setTo($toAddress);

// Create a package (or more) to represent what we're sending
// You can use fluent syntax if you prefer
$package = new Package()
    ->setLength(300)
    ->setWidth(100)
    ->setHeight(80)
    ->setWeight(2000)
    ->setDimensionUnit('mm')
    ->setWeightUnit('g');

$shipment->addPackage($package);

// Finally, add the carrier(s) we wish to fetch rates for. With multiple carriers, rates will be
// returned across all, sorted by cheapest to most expensive
$shipment->addCarrier(new UPS([
    'isProduction' => false,
    'clientId' => '•••••••••••••••••••••••••••••••••••',
    'clientSecret' => '•••••••••••••••••••••••••••••••••••',
    'accountNumber' => '••••••',
]));

$shipment->addCarrier(new FedEx([
    'isProduction' => false,
    'clientId' => '•••••••••••••••••••••••••••••••••••',
    'clientSecret' => '•••••••••••••••••••••••••••••••••••',
    'accountNumber' => '••••••',
]));

// Fetch the rates and print the response
$rateResponse = $shipment->getRates();

echo '<pre>';
print_r($rateResponse);
echo '</pre>';

As you can see, we support a few different syntaxes for objects, depending on your favourite flavour.

Sustainable development#

As many of us are keenly aware, the challenge with open-source software is ensuring that it's maintained and supported. In fact, it's the main reason Shippy was created where many individual packages for shipping carriers were marked as abandoned, or the developers were otherwise unresponsive.

Shippy is used in a commercial Craft CMS plugin of ours called Postie. It's a paid plugin due to its tightly coupled nature with the Craft CMS ecosystem but uses Shippy for handling communications with carriers.

Through this paid usage of Shippy, we aim to provide the time and effort to keep Shippy working, supported and available for the community. After all, with Postie relying on Shippy, it's in our best interest to ensure that it's working!

Let us know what you think#

It's a little different to normal, but we're confident people will find it useful, especially as we don't believe a similar (free) library exists out there.

We'd love to get your feedback, and there's plenty of room for scope and future development. Don't be shy in offering suggestions!

Shippy is available today for free on GitHub (opens new window).