In the chapter on error reporting <phlyrestfully.error-reporting>
, I noted that PhlyRestfully has standardized on the API-Problem format for reporting errors.
Currently, an API-Problem response will be created automatically for any of the following conditions:
- raising a
PhlyRestfully\Exception\CreationException
inside acreate
listener. - raising a
PhlyRestfully\Exception\PatchException
inside apatch
listener. - raising a
PhlyRestfully\Exception\UpdateException
inside anupdate
listener. - raising an exception in any other
PhlyRestfully\Resource
event listener.
If the exception you raise implements PhlyRestfully\Exception\ProblemExceptionInterface
-- which PhlyRestfully\Exception\DomainException
does, as does its descendents, the CreationException
, PatchException
, and UpdateException
-- you can set additional details in the exception instance before throwing it, allowing you to hit to PhlyRestfully\ApiProblem
how to render itself.
There's another way to create and return an API-Problem payload, however: create and return an instance of PhlyRestfully\ApiProblem
from any of the Resource
event listeners. This gives you fine-grained control over creation of the problem object, and avoids the overhead of exceptions.
However, there's another way to receive an API-Problem result: raising an exception. For this the listener becomes important.
PhlyRestfully\Module
registers a listener with the identifier PhlyRestfully\ResourceController
on its dispatch
event. This event then registers the PhlyRestfully\ApiProblemListener
on the application render
event. Essentially, this ensures that the listener is only registered if a controller intended as a RESTful resource endpoint is triggered.
The listener checks to see if the MvcEvent
instance is marked as containing an error. If so, it checks to see if the Accept
header is looking for a JSON response, and, finally, if so, it marshals an ApiProblem
instance from the exception, setting it as the result.
This latter bit, the Accept
header matching, is configurable. If you want to allow an API-Problem response for other than the default set of mediatypes (application/hal+json
, application/api-problem+json
, and application/json
), you can do so via your configuration. Set the value in the accept_filter
subkey of the phlyrestfully
configuration; the value should be a comma-separated set of mimetypes.
return array(
'phlyrestfully' => array(
// ...
'accept_filter' => 'application/json,text/json',
),
);
api-problem, error reporting, exception, accept