04. Using HTTP exceptions for reporting errors.md

Using HTTP exceptions for reporting errors

In this example, you'll learn how to use exceptions within ZfrRest.

Built-in exceptions

ZfrRest comes with a lot of HTTP exceptions among the most popular ones used for REST APIs. Those exceptions are triggered by ZfrRest internally. For instance, if it does not found a given HTTP method (ie. it is not implemented in your controller), it will trigger a ZfrRest\Http\Exception\Client\MethodNotAllowedException.

All those exceptions are catched by the ZfrRest\Mvc\HttpExceptionListener, and a new HTTP response is created from the exception. The message of the exception is set as the Reason Phrase of the HTTP response, while the code is set as the HTTP status code.

Here is a list of all ZfrRest exceptions:

• ZfrRest\Http\Exception\Client\BadRequestException
• ZfrRest\Http\Exception\Client\ConflictException
• ZfrRest\Http\Exception\Client\ForbiddenException
• ZfrRest\Http\Exception\Client\GoneException
• ZfrRest\Http\Exception\Client\MethodNotAllowedException
• ZfrRest\Http\Exception\Client\NotFoundException
• ZfrRest\Http\Exception\Client\UnauthorizedException
• ZfrRest\Http\Exception\ClientErrorException
• ZfrRest\Http\Exception\Server\InternalServerErrorException
• ZfrRest\Http\Exception\Server\NotImplementedException
• ZfrRest\Http\Exception\Server\ServiceUnavailableException
• ZfrRest\Http\Exception\ServerErrorException

For instance:

use ZfrRest\Mvc\Controller\AbstractRestfulController;
use ZfrRest\Http\Exception\Server\ServiceUnavailableException;

class PaymentsController extends AbstractRestfulController
{
    // Create a new payment!
    public function post(array $routeParams)
    {
        // Get the payment from your service and route params
        // ...

        try {
            $this->paymentService->create($payment);
        } catch (PaypalUnavailableException $e) {
            throw new ServiceUnavailableException('PayPal is currently unavailable, please try again later');
        }

        return $payment;
    }
}

Mapping custom exceptions

When working with third-party modules, a lot of exceptions can be thrown, and manually catching all those exceptions to create ZfrRest exceptions can be tedious. Instead, you can use an exception map to map exceptions to ZfrRest exceptions.

For instance, let's say you work with ZfcRbac, and you want to map the ZfcRbac\Exception\UnauthorizedException to the ZfrRest exception. In your config, add the following:

use ZfcRbac\Exception\UnauthorizedException;
use ZfrRest\Http\Exception\Client\UnauthorizedException;

return [
    'zfr_rest' => [
        'exception_map' => [
            UnauthorizedException::class => UnauthorizedException::class
        ]
    ]
];

Navigation

• Continue to [Best practices](/docs/05. Best practices.md)
• Back to [the View Layer](/docs/03. View layer.md)
• Back to the Index