PHPackages quellabs/canvas-shipments-contracts - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [PSR & Standards](/categories/psr-standards) 4. / 5. quellabs/canvas-shipments-contracts ActiveLibrary[PSR & Standards](/categories/psr-standards) quellabs/canvas-shipments-contracts =================================== Shipment gateway contracts and interfaces for the Canvas PHP framework 1.0.0(yesterday)006MITPHPPHP ^8.2 Since Apr 2Pushed todayCompare [ Source](https://github.com/quellabs/canvas-shipments-contracts)[ Packagist](https://packagist.org/packages/quellabs/canvas-shipments-contracts)[ RSS](/packages/quellabs-canvas-shipments-contracts/feed)WikiDiscussions main Synced today READMEChangelogDependencies (1)Versions (2)Used By (6) Canvas Shipments Contracts ========================== [](#canvas-shipments-contracts) Shared contracts for the Canvas shipments ecosystem. Contains the interfaces and value objects that connect shipping provider packages to your application. Installation ------------ [](#installation) ``` composer require quellabs/canvas-shipments-contracts ``` What's in this package ---------------------- [](#whats-in-this-package) Class / InterfaceDescription`ShipmentInterface`Interface for application code — exposes `create`, `cancel`, `getShippingOptions``ShipmentProviderInterface`Interface all driver packages must implement — extends `ShipmentInterface`, adds `exchange` and discovery methods`ShipmentRequest`Input for creating a shipment`ShipmentAddress`Recipient address attached to a shipment request`ShipmentResult`Result of a successful parcel creation`ShipmentState`Shipment snapshot delivered via the `shipment_exchange` signal`ShipmentStatus`Enum of possible shipment states`CancelRequest`Input for cancelling a shipment`CancelResult`Result of a cancellation attempt`ShipmentException`Base exception for all shipment failures`ShipmentCreationException`Thrown when `create()` fails`ShipmentCancellationException`Thrown when `cancel()` fails`ShipmentExchangeException`Thrown when `exchange()` failsAll classes are in the `Quellabs\Shipments\Contracts` namespace. Usage ----- [](#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) `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. PropertyTypeDescription`$provider``string`Provider identifier, e.g. `'sendcloud'``$parcelId``string`Provider-assigned parcel ID`$reference``string`Your own order reference, echoed back from `ShipmentRequest``$state``ShipmentStatus`Normalised shipment status`$trackingCode``?string`Carrier-assigned tracking code`$trackingUrl``?string`Public tracking URL, ready to embed in customer emails`$statusMessage``?string`Human-readable status message from the provider`$internalState``string`Raw status from the provider, before normalisation`$metadata``array`Provider-specific data, e.g. `carrierId`, `labelUrl`Persist `$parcelId` and `$provider` from `ShipmentResult` at creation time — they are required when calling `ShipmentRouter::exchange()` or `ShipmentRouter::cancel()` later. Exceptions ---------- [](#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 --------------------- [](#shipmentstatus-values) CaseDescription`ShipmentStatus::Created`Parcel record created; label not yet printed`ShipmentStatus::LabelPrinted`Label generated; ready for carrier pickup or drop-off`ShipmentStatus::InTransit`Carrier has accepted and is transporting the parcel`ShipmentStatus::OutForDelivery`Parcel is out for final delivery`ShipmentStatus::Delivered`Parcel successfully delivered to the recipient`ShipmentStatus::DeliveryFailed`Delivery attempt failed; carrier will retry`ShipmentStatus::AwaitingPickup`Parcel held at a service point for recipient pickup`ShipmentStatus::ReturnedToSender`Parcel returned after failed delivery attempts or explicit return`ShipmentStatus::Cancelled`Parcel cancelled before handover to the carrier`ShipmentStatus::Unknown`Unrecognised status from provider; see `ShipmentState::$internalState`License ------- [](#license) MIT ### Health Score 40 — FairBetter than 87% of packages Maintenance100 Actively maintained with recent releases Popularity0 Limited adoption so far Community9 Small or concentrated contributor base Maturity45 Maturing project, gaining track record How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 1d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/57e4ab872b3e37536367f2d26b192df3d3bb6a6a1cebec9a104d14a6d2ffe157?d=identicon)[noescom](/maintainers/noescom) --- Tags interfacescontractsabstractionscanvasshippingshipmentscanvas-shipments ### Embed Badge ![Health badge](/badges/quellabs-canvas-shipments-contracts/health.svg) ``` [![Health](https://phpackages.com/badges/quellabs-canvas-shipments-contracts/health.svg)](https://phpackages.com/packages/quellabs-canvas-shipments-contracts) ``` ### Alternatives [symfony/translation-contracts Generic abstractions related to translation 2.6k698.7M422](/packages/symfony-translation-contracts)[symfony/contracts A set of abstractions extracted out of the Symfony components 3.9k64.6M101](/packages/symfony-contracts) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)