Unofficial PostNL REST API PHP Bindings

About

This unofficial PHP library for the PostNL REST API aims to provide a simple way to connect your application with PostNL. By abstracting away needless complexity when processing shipment information and increased fault-tolerance, you can get up and running with PostNL in minutes.
At the lower level this library uses asynchronous communication and payload splitting for improved performance.

Status

* PostNL::getTimeframesAndNearestLocations can be used as an alternative with more functionality: https://postnl-php.readthedocs.io/en/v1.4.x/quickstart.html#requesting-timeframes-location-and-delivery-date-at-once

Instructions

• Clone this repo
• Run composer install (Don't have composer? Visit https://getcomposer.org/)
• Optionally run composer require guzzlehttp/guzzle to use Guzzle instead of cURL directly
• You're good to go! A small example can be found in this README. Check out the full documentation for a quick start guide.

Documentation

Example

Allow a user to download a label using the default REST API

<?php

use Firstred\PostNL\PostNL;
use Firstred\PostNL\Entity\Customer;
use Firstred\PostNL\Entity\Address;
use Firstred\PostNL\Entity\Shipment;
use Firstred\PostNL\Entity\Dimension;

require_once __DIR__.'/vendor/autoload.php';

$customer = Customer::create([
    'CollectionLocation' => '123456',
    'CustomerCode'       => 'DEVC',
    'CustomerNumber'     => '11223344',
    'ContactPerson'      => 'Peter',
    'Address'            => Address::create([
        'AddressType' => '02',
        'City'        => 'Hoofddorp',
        'CompanyName' => 'PostNL',
        'Countrycode' => 'NL',
        'HouseNr'     => '42',
        'Street'      => 'Siriusdreef',
        'Zipcode'     => '2132WT',
    ]),
    'Email'              => 'info@voorbeeld.nl',
    'Name'               => 'Michael',
]);

$apikey = 'YOUR_API_KEY_HERE';
$sandbox = false;

$postnl = new PostNL($customer, $apikey, $sandbox);

$barcode = $postnl->generateBarcodeByCountryCode('NL');

$shipment = Shipment::create([
    'Addresses'           => [
        Address::create([
            'AddressType' => '01',
            'City'        => 'Utrecht',
            'Countrycode' => 'NL',
            'FirstName'   => 'Peter',
            'HouseNr'     => '9',
            'HouseNrExt'  => 'a bis',
            'Name'        => 'de Ruijter',
            'Street'      => 'Bilderdijkstraat',
            'Zipcode'     => '3521VA',
        ]),
    ],
    'Barcode'             => $barcode,
    'Dimension'           => new Dimension(/* weight */ '2000'),
    'ProductCodeDelivery' => '3085',
]);

header('Content-Type: application/pdf');
header('Content-Disposition: attachment; filename="label.pdf"');
echo base64_decode($postnl->generateLabel(
    /* The actual shipment */ $shipment, 
    /* The output format */ 'GraphicFile|PDF',
    /* Immediately confirm the shipment */ true
)
    ->getResponseShipments()[0]
    ->getLabels()[0]
    ->getContent()
);
exit;

Full documentation

The full documentation can be found on this page: https://postnl-php.readthedocs.io/

Building the documentation

Generating the documentation consists of two steps:

1. Generating the reference RST files of all PHP classes available in this library.
2. Generating the HTML output which can be viewed with a browser.

Generating the PHP classes reference

Generating the references depends on a pretty old library. Removing other dependencies first from require-dev may be the best workaround to install abbadon1334/phpdoc-to-rst.

  "require-dev": {
  },

Then install the PHPdoc to RST tool.

composer require abbadon1334/phpdoc-to-rst -W

This repository includes a simple PHP file which utilizes the above-mentioned tool to generate the reference RST files programmatically. It also moves around a few files to integrate the reference with the rest of the documentation.
Simply run (tested w/ PHP 8.2):

php ./build-docs-reference.php

Generating the final HTML output

The documentation is automatically built and hosted on readthedocs.io. You can build a local HTML copy by installing Sphinx and running

pip install -r docs/requirements.txt

to install the requirements, followed by

sphinx-build -b html docs builddir

to build the HTML output in the directory builddir.

License

This library has been licensed with the MIT license.