mvdnbrk / dhlparcel-php-api
DHL Parcel API client for PHP
Fund package maintenance!
mvdnbrk
Installs: 51 276
Dependents: 5
Suggesters: 0
Security: 0
Stars: 37
Watchers: 5
Forks: 28
Open Issues: 11
Requires
- php: ^7.2 || ^8.0
- ext-json: *
- composer/ca-bundle: ^1.2
- guzzlehttp/guzzle: ^6.4 || ^7.1
- lcobucci/jwt: ^3.4 || ^4.0
- ramsey/uuid: ^4.0
- tightenco/collect: ^5.8 || ^6.0 || ^7.0 || ^8.0
Requires (Dev)
- phpunit/phpunit: ^8.0 || ^9.4
- symfony/var-dumper: ^5.0
- vlucas/phpdotenv: ^5.0
README
Installation
You can install the package via composer:
composer require mvdnbrk/dhlparcel-php-api
Usage
Initialize the DHL Parcel client and set your credentials.
$dhlparcel = new \Mvdnbrk\DhlParcel\Client(); $dhlparcel->setUserId('your-user-id'); $dhlparcel->setApiKey('your-api-key');
If you have multipe accounts, you may optionally set an account id:
$dhlparcel->setAccountId('123456');
Create a parcel
$parcel = new \Mvdnbrk\DhlParcel\Resources\Parcel([ 'reference' => 'your own reference for the parcel (optional)', 'recipient' => [ 'first_name' => 'John', 'last_name' => 'Doe', 'street' => 'Poststraat', 'number' => '1', 'number_suffix' => 'A', 'postal_code' => '1234AA', 'city' => 'Amsterdam', 'cc' => 'NL', ], 'sender' => [ 'company_name' => 'Your Company Name', 'street' => 'Pakketstraat', 'additional_address_line' => 'Industrie 9999', 'number' => '99', 'postal_code' => '9999AA', 'city' => 'Amsterdam', 'cc' => 'NL', ], // Optional. This will be set as the default. 'pieces' => [ [ 'parcel_type' => \Mvdnbrk\DhlParcel\Resources\Piece::PARCEL_TYPE_SMALL, 'quantity' => 1, ], ], ]);
Create the shipment
$shipment = $dhlparcel->shipments->create($parcel); $shipment->id; // For shipments with multiple pieces: $shipment->pieces->each(function ($item) { $item->label_id; $item->barcode; }) // For a shipment with one single piece: $shipment->label_id; $shipment->barcode;
Retrieving a label
A label can be retrieved by using the label_id
.
This will return a PDF label as a string.
$dhlparcel->labels->get($shipment->label_id);
Or you may pass the Shipment
instance directly to this method:
$dhlparcel->labels->get($shipment);
Passing a
Shipment
instance will only retrieve the label for a shipment with a single piece, or the first piece if you have created a shipment with multple pieces. If you have created a shipment with multiple pieces you should retrieve the labels one by one for each piece your shipment contains.
Setting delivery options for a parcel
You can set delivery options for a parcel by passing in the options directly when you create a parcel:
$parcel = new \Mvdnbrk\MyParcel\Resources\Parcel([ ... 'recipient' => [ ... ], 'options' => [ 'description' => 'Order #123', 'signature' => true, 'only_recipient' => true, 'cash_on_delivery' => 9.95, 'evening_delivery' => true, 'extra_assurance' => true, ... ], ]);
Or you may use a method like signature()
and others after constructing the parcel:
$parcel->onlyRecipient() ->signature() ->labelDescription('Order #123') ->cashOnDelivery(9.95) ->eveningDelivery() ->extraAssurance();
Mailbox package
If you would like to send a parcel that fits in a standard mailbox you may use the mailboxpackage()
method:
$parcel->mailboxpackage();
Deliver a parcel to a DHL service point
You may send a parcel to a DHL service point where a customer can pick up the parcel.
The ID of the service point can be set directly when creating a parcel
or with the servicePoint
method:
$parcel = new \Mvdnbrk\MyParcel\Resources\Parcel([ ... 'options' => [ 'service_point_id' => '8004-NL-272403', ... ], ]); $parcel->servicePoint('8004-NL-272403');
Tracking a shipment
$tracktrace = $dhlparcel->tracktrace->get('JVGL...'); // Check if the shipment is delivered: $tracktrace->isDelivered;
Retrieving service points
$servicepoints = $dhlparcel->servicePoints->setPostalcode('1012AA')->setHousenumber('1')->get();
This will return a collection of ServicePoint
objects:
$servicepoints->each(function ($item) {
$item->id;
$item->name;
$item->latitude;
$item->longitude;
$item->distance;
$item->distanceForHumans();
});
Usage with Laravel
You may incorporate this package in your Laravel application by using this package.
Testing
composer test
Changelog
Please see CHANGELOG for more information what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
Credits
License
The MIT License (MIT). Please see License File for more information.