Download the PHP package setono/shipmondo-php-sdk without Composer

Shipmondo PHP SDK

Consume the Shipmondo API in PHP.

Installation

Upgrading from 1.x? See UPGRADE.md — 2.x is a rewrite with a number of breaking changes.

Usage

To target the sandbox API instead of production, pass sandbox: true to the constructor:

will output something:

Receiving webhooks

Shipmondo delivers webhooks as a POST whose body is {"data": "<JWT>"}, where the JWT is HS256-signed with the key you chose when you created the webhook. Verifying that signature is the only way to prove a request really came from Shipmondo, so the SDK ships a WebhookParser that does it for you and hands back a typed WebhookEvent:

Webhook keys must be at least 32 bytes. HS256 requires a key of at least 256 bits / 32 bytes (RFC 7518 §3.2). The SDK enforces this both when you create a webhook (WebhookRequest) and when you verify one (WebhookParser), so make sure the key you set on the webhook is long enough — a shorter key cannot be verified.

action and resourceType are typed enums — if Shipmondo ever sends an action or resource the SDK doesn't model, parse() throws MalformedWebhookException rather than passing an unknown value through. (WebhookResourceName::actions() lists the actions valid for a resource, and WebhooksEndpoint::create() rejects an invalid resource/action pair before sending.)

If you are not on PSR-7, pass the raw body and headers instead:

Both methods pin the HS256 algorithm, so a token presenting any other alg (including none) is rejected. The webhook key is passed per call, so a server that hosts several webhooks can read the SMD-Webhook-Id header to pick the right key before verifying.

WebhookParser implements WebhookParserInterface, so you can type-hint the interface in your controllers/services and inject the parser (or a mock) via your DI container.

Production usage

Internally this library uses the CuyZ/Valinor library which is particularly well suited for turning API responses into DTOs (and request DTOs into JSON). However, this library has some overhead and works best with a cache enabled.

The Client is immutable: configure a cached mapper/normalizer and inject them through the constructor. Use the static helpers so the SDK's required configuration (date formats, superfluous-key handling, and the request null-stripping / snake_case transformers) is applied to your cached builders:

You can read more about it here: Valinor: Performance and caching.

Notes

Accessing fields the SDK doesn't model yet

Every response object exposes a ->raw property containing the full decoded response with its original snake_case keys (the same names as the Shipmondo API docs). Use it to reach fields the SDK doesn't type yet:

Sales orders are eventually consistent

A sales order you just created via salesOrders()->create() may not appear in salesOrders()->getPage() / paginate() immediately — Shipmondo indexes the list asynchronously, so there can be a short delay before a new order is listed. The order is available straight away by id, so for read-after-write use the id returned by create():