This package provides a RFC7807 Problem details implementation. It can be integrated everywhere in your code and should result in a general error response format for HTTP APis.
This package only provides a generic interface, an exception class and some built-in api problem messages. Since handling the exceptions is up to the framework, here is a list of known framework integrations:
- Symfony
^4.1: ApiProblemBundle
composer require phpro/api-problemThis package provides a general interface for creating ApiProblem value objects.
use Phpro\ApiProblem\Exception;
throw new ApiProblemException(
new HttpApiProblem(418, ['detail' => 'Did you know 4,000 people are injured by teapots every year?!'])
);-
General problems
-
Symfony integration problems
-
Http problems
Debuggable: The exception part will only be added in debug context!
use Phpro\ApiProblem\Http\ExceptionApiProblem;
new ExceptionApiProblem(new \Exception('message', 500));{
"status": 500,
"type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
"title": "Internal Server Error",
"detail": "message",
"exception": {
"message": "message",
"type": "RuntimeException",
"code": 500,
"line": 23,
"file": "exception.php",
"trace": [
"#0 [internal function]: ...",
"#1 [internal function]: ...",
"#3 [internal function]: ...",
"..."
],
"previous": [
{
"message": "previous",
"type": "InvalidArgumentException",
"code": 0,
"line": 20,
"file": "exception.php",
"trace": [
"#0 [internal function]: ...",
"#1 [internal function]: ...",
"#3 [internal function]: ...",
"..."
]
}
]
}
}use Phpro\ApiProblem\Http\HttpApiProblem;
new HttpApiProblem(404, ['detail' => 'The book could not be found.']);{
"status": 404,
"type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
"title": "Not found",
"detail": "The book could not be found."
}composer require symfony/validator:^4.1use Phpro\ApiProblem\Http\ValidationApiProblem;
use Symfony\Component\Validator\ConstraintViolation;
use Symfony\Component\Validator\ConstraintViolationList;
new ValidationApiProblem(new ConstraintViolationList([
new ConstraintViolation('Invalid email', '', [], '', 'email', '', null, '8615ecd9-afcb-479a-9c78-8bcfe260cf2a'),
]));{
"status": 400,
"type": "https:\/\/symfony.com\/errors\/validation",
"title": "Validation Failed",
"detail": "email: Invalid Email",
"violations": [
{
"propertyPath": "email",
"title": "Invalid email",
"type": "urn:uuid:8615ecd9-afcb-479a-9c78-8bcfe260cf2a"
}
]
}use Phpro\ApiProblem\Http\BadRequestProblem;
new BadRequestProblem('Bad request. Bad!.');{
"status": 400,
"type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
"title": "Bad Request",
"detail": "Bad request. Bad!"
}use Phpro\ApiProblem\Http\UnauthorizedProblem;
new UnauthorizedProblem('You are not authorized to access X.');{
"status": 401,
"type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
"title": "Unauthorized",
"detail": "You are not authenticated. Please login."
}use Phpro\ApiProblem\Http\ForbiddenProblem;
new ForbiddenProblem('Not authorized to access gold.');{
"status": 403,
"type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
"title": "Forbidden",
"detail": "Not authorized to access gold."
}use Phpro\ApiProblem\Http\NotFoundProblem;
new NotFoundProblem('The book with ID 20 could not be found.');{
"status": 404,
"type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
"title": "Not found",
"detail": "The book with ID 20 could not be found."
}use Phpro\ApiProblem\Http\MethodNotAllowedProblem;
new MethodNotAllowedProblem('Only POST and GET allowed.');{
"status": 405,
"type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
"title": "Method Not Allowed",
"detail": "Only POST and GET allowed."
}use Phpro\ApiProblem\Http\ConflictProblem;
new ConflictProblem('Duplicated key for book with ID 20.');{
"status": 409,
"type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
"title": "Conflict",
"detail": "Duplicated key for book with ID 20."
}use Phpro\ApiProblem\Http\PreconditionFailedProblem;
new PreconditionFailedProblem('Incorrect entity tag provided.');{
"status": 412,
"type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
"title": "Precondition Failed",
"detail": "Incorrect entity tag provided."
}use Phpro\ApiProblem\Http\UnsupportedMediaTypeProblem;
new UnsupportedMediaTypeProblem('Please provide valid JSON.');{
"status": 415,
"type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
"title": "Unsupported Media Type",
"detail": "Please provide valid JSON."
}use Phpro\ApiProblem\Http\IAmATeapotProblem;
new IAmATeapotProblem('More tea please.');{
"status": 418,
"type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
"title": "I'm a teapot",
"detail": "More tea please."
}use Phpro\ApiProblem\Http\UnprocessableEntityProblem;
new UnprocessableEntityProblem('Unable to process the contained instructions.');{
"status": 422,
"type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
"title": "Unprocessable Entity",
"detail": "Unable to process the contained instructions."
}use Phpro\ApiProblem\Http\LockedProblem;
new LockedProblem('This door is locked.');{
"status": 423,
"type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
"title": "Locked",
"detail": "This door is locked."
}use Phpro\ApiProblem\Http\PreconditionRequiredProblem;
new PreconditionRequiredProblem('If-match header is required.');{
"status": 428,
"type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
"title": "Precondition Required",
"detail": "If-match header is required."
}Creating problem sounds scary right!? Since the RFC is very loose, we made the interface as easy as possible:
use Phpro\ApiProblem\ApiProblemInterface;
class MyProblem implements ApiProblemInterface
{
public function toArray(): array
{
return [
'type' => 'about:blank',
'status' => '99',
'title' => 'Got 99 problems but a glitch aint one!',
];
}
}A lot of problems will be detected in an HTTP context. Therefore, we also provided a base HttpApiProblem class.
This one will automatically fill in the type and title section based on the HTTP code.
The only thing you'll need to do, is add some additional data to it:
use Phpro\ApiProblem\Http\HttpApiProblem;
class MyProblem extends HttpApiProblem
{
public function __construct(string $details)
{
parent::__construct(500, ['details' => $details]);
}
}If you want to log additional information in a debug context, it is possible to implement an additional DebuggableApiProblemInterface:
use Phpro\ApiProblem\DebuggableApiProblemInterface;
class MyProblem implements DebuggableApiProblemInterface
{
public function toArray(): array
{
return [
'type' => 'about:blank',
'status' => '99',
'title' => 'Got 99 problems but a glitch ain\'t one!',
];
}
public function toDebuggableArray(): array
{
return array_merge(
$this->toArray(),
[
'situation' => 'If you are having code problems, I feel bad for you son',
]
);
}
}Bugs and feature request are tracked on GitHub. Please take a look at our rules before contributing your code.
api-problem is licensed under the MIT License.