Exception handling

The following tree view describes how the exceptions used in this library depend on each other.

. Exception : Throwable
└── Firstred\PostNL\Exception\PostNLException
    ├── Firstred\PostNL\Exception\ApiException
    │   ├── Firstred\PostNL\Exception\ApiConnectionException
    │   ├── Firstred\PostNL\Exception\CifDownException
    │   ├── Firstred\PostNL\Exception\CifException
    │   ├── Firstred\PostNL\Exception\NotFoundException
    │   ├── Firstred\PostNL\Exception\ResponseException
    │   └── Firstred\PostNL\Exception\ShipmentNotFoundException
    ├── Firstred\PostNL\Exception\HttpClientException
    └── Firstred\PostNL\Exception\InvalidArgumentException
        ├── Firstred\PostNL\Exception\InvalidApiModeException
        ├── Firstred\PostNL\Exception\InvalidBarcodeException
        ├── Firstred\PostNL\Exception\InvalidConfigurationException
        ├── Firstred\PostNL\Exception\InvalidMessageTimeStampException
        ├── Firstred\PostNL\Exception\InvalidMethodException
        ├── Firstred\PostNL\Exception\NotImplementedException
        └── Firstred\PostNL\Exception\NotSupportedException

Exception types

This library throws several exceptions for errors that can occur. In order to provide harmonized error handling for different API modes, several implementation details are left out. For example, errors related to XML or JSON parsing are wrapped in a Firstred\PostNL\Exception\ResponseException exception.

If you want to catch all exceptions thrown by this library be sure to catch Firstred\PostNL\Exception\PostNLException s. Under normal conditions there is no need to catch all Throwable s. If any other Throwable such as Error, TypeError or PsrCacheInvalidArgumentException is uncaught, it means that there is a bug somewhere in the library. Please file a new issue with all the details you can find (preferably with the original request/response [be sure to scrub personal data]): https://github.com/firstred/postnl-api-php/issues/new.

use Firstred\PostNL\Exception\PostNLException;
use Psr\Cache\InvalidArgumentException as PsrCacheInvalidArgumentException;

try {
    $postnl->getTimeframes(...);
} catch (PostNLException $e) {
    // ...
}

Firstred\PostNL\Exception\ApiException

This groups of exceptions occurs when there is something wrong with the way the API returns an object (likely an unsupported feature or structure), when the API has trouble processing data, is either down or the requested object could not be found.

deprecated Firstred\PostNL\Exception\ApiConnectionException

This happens when the HTTP client has a problem connecting with the API. This exception has been replaced by the Firstred\PostNL\Exception\HttpClientException exception, which allows you to gather more detailed information.

Firstred\PostNL\Exception\CifDownException

This exception is thrown when the CIF API is down.

Firstred\PostNL\Exception\CifException

When the CIF API itself has a fatal error this exception is thrown.

Firstred\PostNL\Exception\NotFoundException

This exception is thrown when the requested object could not be found.

Firstred\PostNL\Exception\ResponseException

This exception is thrown when a response could not be understood by the library. If there was a problem parsing the response, the previous argument might point at the underlying error.

deprecated

Required: False

deprecated Firstred\PostNL\Exception\ShipmentNotFoundException

Occurs when the requested Firstred\PostNL\Entity\Shipment or Firstred\PostNL\Entity\Response\ResponseShipment object could not be found. This exception is deprecated and being replaced by a Firstred\PostNL\Exception\NotFoundException.

Firstred\PostNL\Exception\HttpClientException

All exceptions that occur in underlying HTTP Clients are handled by Firstred\PostNL\Exception\HttpClientException s.

Firstred\PostNL\Exception\InvalidArgumentException

Invalid inputs are handled by the group of Firstred\PostNL\Exception\InvalidArgumentException exceptions.

deprecated Firstred\PostNL\Exception\InvalidApiModeException

When an invalid API mode is selected, this exception is thrown. This exception is deprecated, because the ability to select an API mode will be removed in the future.

Firstred\PostNL\Exception\InvalidBarcodeException

This exception is thrown when there is a problem with generating a barcode. Usually caused by invalid input.

Firstred\PostNL\Exception\InvalidConfigurationException

When a problem occurs due to configuration errors, this exception is thrown. For example, an invalid API key.

deprecated Firstred\PostNL\Exception\InvalidMessageTimeStampException

This occurs when a Firstred\PostNL\Entity\SOAP\Message has an invalid timestamp. Deprecated, because SOAP support is being removed.

Firstred\PostNL\Exception\InvalidMethodException

This happens when an invalid method has been called.

Firstred\PostNL\Exception\NotImplementedException

When a feature has not been implemented, yet, you will see this exception thrown.

Firstred\PostNL\Exception\NotSupportedException

This occurs when a feature is not supported.