Formats

The API can be very inconsistent when it comes to returning times and dates, for example. To standardize how some fields are handled, the library uses different formats.

Dates, Times and DateTimes

This library makes a distinction between Dates, Times and DateTimes. To normalize moments in time, this package returns DateTimeImmutable objects when referring to a single point in time and uses strings for times.

The following definitions and formats are used:

Dates

Dates refer to a specific moment in time; not specifying the time. Can be formatted as 2020-02-03. Is always a DateTimeImmutable object.

Times

Times refer to a certain moment on any given day. Can be formatted as 12:12:12. Is always a string and should always be formatted using the following PHP date format: H:i:s (Hours, minutes and seconds with leading zeros).

DateTimes

DateTimes are referring to a specific date and time. They can be formatted for example as 2021-02-03 12:12:12. Is always a DateTimeImmutable object.

Note

Every DateTimeImmutable object and time string returned by the library is adjusted to the timezone of the PostNL API (Europe/Amsterdam). Make sure your timezone is aligned correctly, or otherwise convert dates and times manually by adding/subtracting the time difference.

You can check your PHP’s configured timezone by printing the date.timezone setting:

die(ini_get('date.timezone'));

SOAP object structure

Sometimes you will notice that the REST API documentation might return property names in singular whereas the library returns the plural version of a property. This is caused by the fact that the SOAP API returns most properties in plural format. An example is the shipping status service when requesting the current status of a shipment. The SOAP API would return an addresses property whereas REST returns address. This is automatically converted to the Firstred\PostNL\Entity\Shipment::$Addresses property by this library. Therefore, when in doubt, you can safely assume that plural is used.