README

Shared contracts for the Canvas shipments ecosystem. Contains the interfaces and value objects that connect shipping provider packages to your application.

Installation

composer require quellabs/canvas-shipments-contracts

What's in this package

All classes are in the Quellabs\Shipments\Contracts namespace.

Usage

use Quellabs\Shipments\Contracts\ShipmentInterface;
use Quellabs\Shipments\Contracts\ShipmentRequest;
use Quellabs\Shipments\Contracts\ShipmentAddress;
use Quellabs\Shipments\Contracts\ShipmentCreationException;

class FulfillmentService {
    public function __construct(private ShipmentInterface $shipments) {}

    public function ship(): void {
        try {
            $result = $this->shipments->create(new ShipmentRequest(
                shippingModule:  'sendcloud_postnl',
                reference:       'order-12345',
                deliveryAddress: new ShipmentAddress(
                    name:              'Jan de Vries',
                    street:            'Keizersgracht',
                    houseNumber:       '123',
                    houseNumberSuffix: null,
                    postalCode:        '1015 CJ',
                    city:              'Amsterdam',
                    country:           'NL',
                    email:             'jan@example.com',
                ),
                weightGrams: 1200,
                methodId:    8,
            ));

            // Persist $result->parcelId and $result->provider — needed for exchange() and cancel()
            // $result->trackingUrl is ready to embed in your confirmation email
        } catch (ShipmentCreationException $e) {
            // handle error
        }
    }
}

ShipmentState

ShipmentState is an immutable snapshot of a shipment's current status. Your application receives it by subscribing to the shipment_exchange signal, which is emitted by the controller layer after a webhook or manual refresh.

Persist $parcelId and $provider from ShipmentResult at creation time — they are required when calling ShipmentRouter::exchange() or ShipmentRouter::cancel() later.

Exceptions

All exceptions extend ShipmentException, which exposes getDriver(): string and getErrorId(): int|string. Catch the base class to handle any shipment failure, or catch a specific subclass to handle a particular operation.

use Quellabs\Shipments\Contracts\ShipmentException;
use Quellabs\Shipments\Contracts\ShipmentCreationException;
use Quellabs\Shipments\Contracts\ShipmentCancellationException;
use Quellabs\Shipments\Contracts\ShipmentExchangeException;

// Catch all shipment failures
} catch (ShipmentException $e) {
    $e->getDriver();   // e.g. 'sendcloud'
    $e->getErrorId();  // provider error ID
    $e->getMessage();  // human-readable message
}

// Or catch specific failures
} catch (ShipmentCreationException $e) { ... }     // create() failed
} catch (ShipmentCancellationException $e) { ... } // cancel() failed
} catch (ShipmentExchangeException $e) { ... }     // exchange() failed

ShipmentStatus values

License

MIT