mvdnbrk / myparcel-php-api
MyParcel API client for PHP
Fund package maintenance!
mvdnbrk
Installs: 5 092
Dependents: 1
Suggesters: 0
Security: 0
Stars: 2
Watchers: 2
Forks: 5
Open Issues: 8
Requires
- php: ^7.3 || ^8.0
- ext-json: *
- composer/ca-bundle: ^1.2
- guzzlehttp/guzzle: ^6.4 || ^7.1
- illuminate/collections: ^8.0
Requires (Dev)
- phpunit/phpunit: ^8.5 || ^9.4
- symfony/var-dumper: ^5.0
- vlucas/phpdotenv: ^5.0
README
MyParcel makes sending packages easy.
Requirements
To use the MyParcel API client, the following things are required:
- Get a free MyParcel account
- Generate your API Key
- Now you're ready to use the MyParcel API client
Installation
You can install the package via composer:
composer require mvdnbrk/myparcel-php-api
Getting started
Initialize the MyParcel client and set your API key:
$myparcel = new \Mvdnbrk\MyParcel\Client(); $myparcel->setApiKey('your-api-key');
Create a parcel
$parcel = new \Mvdnbrk\MyParcel\Resources\Parcel([ 'reference' => 'your own reference for the parcel', 'recipient' => [ 'first_name' => 'John', 'last_name' => 'Doe' 'street' => 'Poststraat', 'number' => '1', 'number_suffix' => 'A', 'postal_code' => '1234AA', 'city' => 'Amsterdam', 'cc' => 'NL', ] ]);
Create a shipment
$shipment = $myparcel->shipments->create($parcel); // Get the `id` of the shipment. You may save this value for later reference. $shipment->id;
You have created your first shipment!
Retrieve a label
A label can be retrieved by using $shipment->id
. This will return a label in A6 format as a string.
$myparcel->labels->get($shipment->id);
Or you may pass the Shipment
instance directly to this method:
$myparcel->labels->get($shipment);
The label format is A6 by default, you may change this by calling the setFormatA4
method:
$myparcel->labels->setFormatA4()->get($shipment);
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' => 'Description on the label', 'signature' => true, ... ], ]);
Or you may use a method like signature
, onlyRecipient
, returnToSender
, ageCheck
and labelDescription
.
You may call any of these methods after constructing the parcel:
$parcel->labelDescription('Your description.') ->ageCheck() ->onlyRecipient() ->returnToSender() ->signature();
Mailbox package
This package type is only available for shipments in the Netherlands that fit in a standard mailbox.
$parcel->mailboxpackage();
Send a parcel to a service point
You may send a parcel to a PostNL service point where a customer can pick up the parcel:
$parcel = new \Mvdnbrk\MyParcel\Resources\Parcel([ 'recipient' => [ ... ], 'pickup' => [ 'name' => 'Name of the location', 'street' => 'Poststraat', 'number' => '1', 'postal_code' => '1234AA', 'city' => 'Amsterdam', 'cc' => 'NL, ] ]);
Retrieve service points
$servicepoints = $myparcel->servicePoints->setPostalcode('1234AA')->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(); $item->opening_hours; });
Get a shipment
You can get a shipment by id
or your own reference.
$shipment = $myparcel->shipments->get($id); $shipment = $myparcel->shipments->getByReference('your own reference'); // Get the barcode for the shipment: $shipment->barcode; // Get the current status: $shipment->status;
Track a shipment
You can get detailed track and trace information for a shipment.
$tracktrace = $myparcel->tracktrace->get($id); // Links: $tracktrace->link; $tracktrace->link_portal; // Check if the shipment is delivered: $tracktrace->isDelivered; // Get current state of the shipment: $tracktrace->code; $tracktrace->description; $tracktrace->datetime; // Get all traces for the shipment, this will return a collection with // all traces in descending order, including the current state: $tracktrace->items; // Convert all items to an array: $tracktrace->items->all()
Usage with Laravel
You may incorporate this package in your Laravel application by using this package.
Changelog
Please see CHANGELOG for more information what has changed recently.
Testing
$ composer test
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.