Advanced usage

This section describes more advanced ways to use this library. The main class Firstred\PostNL\PostNL and separate service classes (such as Firstred\PostNL\Service\BarcodeService) provide more ways to interact with the API.

Object instantiation

There are four ways in which entities can be instantiated. Either by

1. passing all arguments to the constructor in the right order

2. or using named parameters,

3. invoking the create method on an entity (deprecated since v1.4.0, avoid if you can)

4. or by instantiating an empty entity and calling the setters one by one.

Which method to use is entirely up to you. They are all supported by the library.

However, if you use an IDE with code completion then the safest ways to use are (2) using named parameters (PHP 8) or by calling the setters (4), one by one.

Even without using an editor with code completion you might benefit from using methods (2) and (4) since you will be able to detect errors earlier in the process.

1 - Constructor2 - Constructor named args3 - Create (deprecated since v1.4.0)4 - Setters

<?php

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

// Your PostNL credentials
$customer = new Customer(
    '11223344',
    'DEVC',
    '123456',
    'Sander',
    'test@voorbeeld.nl',
    'Michael',
    new Address(
        '02',
        'PostNL',
        'Siriusdreef',
        '42',
        '2132WT',
        'Hoofddorp',
        'NL',
    ),
);

Building requests manually

For most cases using the API through the (Firstred\PostNL\PostNL) object would be sufficient. There might be times, however, when the main class does not align with your use case. This section aims to describe the process that is involved in creating requests, sending them and processing the responses.

Interacting with the API through this library

In the above-mentioned merged label example we are passing two Firstred\PostNL\Entity\Shipment objects, filled with the needed information to generate the labels. To merge those labels manually, we have to set the merge option to false and can omit both the format and positions parameters. This will in turn make the library return Firstred\PostNL\Entity\Response\GenerateLabelResponse objects.

These are in line with the Firstred\PostNL\Entity\Response\GenerateLabelResponse nodes generated by the SOAP API, even when using the REST API. The main reason for this standardization is that the initial version of this library was built for the SOAP API. If you need a quick reference of the Firstred\PostNL\Entity\Response\GenerateLabelResponse object, you can either look up the code of the GenerateLabelResponse class or navigate to the API documentation directly.

Sending concurrent requests manually

There is no direct need to manually handle concurrent requests. This library handles most cases automatically and even provides a special function to quickly grab timeframe and location data for frontend delivery options widgets.

In case you manually want to send a custom mix of requests, you can look up the corresponding functions in the Service class of your choice and call the `buildXXXXXXRequest()` functions manually. Thanks to the PSR-7 standard used by this library you can use the PsrHttpMessageRequestInterface object that is returned to access the full request that would otherwise be sent directly. To pick up where you left off you can then grab the response and pass it to one of the processXXXXXXXResponse()` functions of the Service class. The easiest method is to grab the raw HTTP message and parse it with the included PSR-7 library. An example can be found in the cURL client.

Processing Response objects

Note

This section refers to Response objects returned by the library, not the standardized PSR-7 messages.

As soon as you’ve done your first request with this library, you will find that it returns a Response object. As mentioned in the Building Requests section, these Response objects are based on the SOAP API, regardless of the mode set. The properties of a Response object can be looked up in the code, but it can be a bit confusing at times, since the Response object will likely not contain all properties at once. It often depends on the context of the request. For this reason, you’re better off by having a look at the SOAP API documentation directly or by checking out some of the examples in this documentation.