README

DPD Connect PHP SDK

Connect your PHP application to DPD shipping services.
Create shipments, generate labels, find Parcelshop pickup points, and track parcels — all via a clean, dependency-free PHP library.

Features · Requirements · Installation · Quick Start · Documentation · Development

📦 Features

🚚 Shipment Creation

Feature	Description
Synchronous	Create shipments and receive labels in a single request
Asynchronous	Submit large batches and poll for completion via the Job resource
Batch creation	Send multiple shipment orders in one call
Array or objects	Build requests as plain arrays or typed domain objects
Request mapping	Built-in mapper converts Magento/custom requests to API objects

🏷️ Label Generation

Feature	Description
PDF labels	Standard A4 and A6 paper formats
ZPL labels	Thermal printer language support
Print offsets	Configurable vertical and horizontal offsets
Parcel label number	Optionally pre-assign label numbers

🏪 Parcelshop Lookup

Feature	Description
Geolocation search	Find parcelshops by longitude, latitude and country
Lookup by ID	Retrieve a specific parcelshop by its DPD ID
Result limiting	Control the number of results returned

📬 Parcel Tracking

Feature	Description
Status tracking	Retrieve current parcel status by parcel ID
Label retrieval	Fetch a label for an existing parcel by ID
Async job polling	Check the state of asynchronous shipment creation jobs

🔐 Authentication

Feature	Description
Password auth	Authenticate with username + password — JWT is fetched automatically
JWT auth	Provide your own JWT token directly
Token caching	Token cached until near expiry (5-minute safety margin)
Token callback	Register a callback to persist refreshed tokens externally

💾 Caching

Feature	Description
Built-in filesystem cache	Countries and products cached for 1 hour with no setup required
Stale fallback	Product list falls back to a year-old cached result on API failure
Custom backends	Implement `CacheInterface` to use Redis, Memcached, or any store

🌍 International Shipping

Feature	Description
Customs declarations	Consignee, consignor, customs lines with HS codes and values
Cash on delivery	COD amount, currency and purpose
Notifications	Email or SMS delivery notifications for the receiver
Pickup configuration	Optional pickup scheduling

✅ Requirements

Requirement	Version
PHP	`>=8.1`
ext-json	`*`
ext-curl	`*`

No framework dependency. Works standalone in any PHP project.

📥 Installation

composer require dpdconnect/php-sdk

⚡ Quick Start

1. Build a client

use DpdConnect\Sdk\ClientBuilder;

$clientBuilder = new ClientBuilder();

// Authenticate by username + password (JWT is fetched automatically)
$client = $clientBuilder->buildAuthenticatedByPassword('your-username', 'your-password');

// Or authenticate with an existing JWT token
$client = $clientBuilder->buildAuthenticatedByJwtToken('your-jwt-token');

2. Create a shipment

use DpdConnect\Sdk\Objects\ObjectFactory;
use DpdConnect\Sdk\Objects\ShipmentOrder;
use DpdConnect\Sdk\Objects\ShipmentOrder\Contact\Sender;
use DpdConnect\Sdk\Objects\ShipmentOrder\Contact\Receiver;
use DpdConnect\Sdk\Objects\ShipmentOrder\PrintOptions;
use DpdConnect\Sdk\Objects\ShipmentOrder\Shipment;
use DpdConnect\Sdk\Objects\ShipmentOrder\Shipment\Parcel;

$printOptions = ObjectFactory::create(PrintOptions::class, [
    'printerLanguage' => 'PDF',
    'paperFormat'     => 'A4',
]);

$sender = ObjectFactory::create(Sender::class, [
    'companyname'       => 'My Company B.V.',
    'name1'             => 'John Do',
    'street'            => 'John Do Street',
    'housenumber'       => '9',
    'postalcode'        => '1101BM',
    'city'              => 'Amsterdam',
    'country'           => 'NL',
    'email'             => 'info@mycompany.com',
    'phoneNumber'       => '0612345678',
    'commercialAddress' => true,
]);

$receiver = ObjectFactory::create(Receiver::class, [
    'name1'             => 'Jane Do',
    'street'            => 'Jane Do Street',
    'housenumber'       => '10',
    'postalcode'        => '1101BM',
    'city'              => 'Amsterdam',
    'country'           => 'NL',
    'phoneNumber'       => '0698765432',
    'commercialAddress' => false,
]);

$parcel = ObjectFactory::create(Parcel::class, [
    'customerReferences' => ['order-12345'],
    'weight'             => 500,
]);

$shipment = ObjectFactory::create(Shipment::class, [
    'orderId'      => 'order-12345',
    'sendingDepot' => '0522',
    'sender'       => $sender,
    'receiver'     => $receiver,
    'product'      => ['productCode' => 'CL'],
    'parcels'      => [$parcel],
]);

$shipmentOrder = ObjectFactory::create(ShipmentOrder::class, [
    'printOptions' => $printOptions,
    'createLabel'  => true,
    'shipments'    => [$shipment],
]);

$response = $client->getShipment()->createShipmentOrder($shipmentOrder);

3. Find Parcelshops

// List parcelshops near a location
$parcelshops = $client->getParcelshop()->getList([
    'longitude'  => 4.9041,
    'latitude'   => 52.3676,
    'countryIso' => 'NL',
    'limit'      => 10,
]);

// Get a specific parcelshop by ID
$parcelshop = $client->getParcelshop()->get('NL10566');

4. Track a parcel

$status = $client->getParcel()->getStatus('parcel-id');
$label  = $client->getParcel()->getLabel('parcel-id');

5. Use a custom API endpoint

// For staging or self-hosted environments
$clientBuilder = new ClientBuilder('https://api.staging.dpdconnect.nl');
$client = $clientBuilder->buildAuthenticatedByPassword('username', 'password');

📚 Documentation

Document	Description
Architecture	SDK architecture, HTTP stack, design patterns
Authentication	Auth methods, token caching, token callback
Resources	All API resources with full method reference
Objects	Domain objects and data model reference
Exceptions	Exception hierarchy and error handling patterns
Caching	Caching system and custom backend guide

🛠️ Development

Run tests

composer install
vendor/bin/phpunit -c phpunit.xml.dist

Code quality

php bin/phpcs          # PHP_CodeSniffer
php bin/phplint        # PHP lint check
phpmd . text phpmd.xml --exclude vendor

CI Pipeline

The project uses GitLab CI with four stages:

Stage	Jobs	Description
`validate`	`composer-validate`, `composer-audit`	Validates `composer.json` and checks advisories
`analyse`	`phpcs`, `phplint`	Static analysis; `phplint` runs on PHP 8.1 and 8.5
`test`	`phpunit`	Full unit test suite on PHP 8.1 and 8.5
`sync`	`sync-to-github`	On a release tag only: mirrors to GitHub and publishes the release

phplint and phpunit run on both ends of the declared range: PHP 8.1 is the floor that actually gates, and 8.5 catches runtime deprecations no static check sees. sync-to-github runs on release tags only; the job's own comments explain what it does and why.

dpdconnect / php-sdk

Package info

Security

Statistics