nilportugues / api-problems
PSR7 Response implementation for the Problem Details for HTTP APIs
Installs: 48 047
Dependents: 4
Suggesters: 0
Security: 0
Stars: 17
Watchers: 2
Forks: 4
Open Issues: 1
Requires
- guzzlehttp/psr7: ^1.3
- nilportugues/assert: ^1.0
- psr/http-message: ^1.0
Requires (Dev)
- fabpot/php-cs-fixer: ~1.9
- phpunit/phpunit: 4.*
README
PSR7 Response implementation for the Problem Details for HTTP APIs (RFC7807) specification.
Usage
To report a single error, all you need to do is pass in the mandatory parameters and you'll be fine.
Straightforward usage (recommended)
This is probably the fastest way and it's really convenient as it hides the presenter and creating the instances from you.
use NilPortugues\Api\Problem\ApiProblemResponse; $additionalDetails = []; //you may pass additional details too. /**@var $response is a PSR7 response */ $response = ApiProblemResponse::json(404,'User with id 5 not found.', 'Not Found', 'user.not_found', $additionalDetails); $response = ApiProblemResponse::xml(404,'User with id 5 not found.', 'Not Found', 'user.not_found', $additionalDetails); $response = ApiProblemResponse::fromExceptionToJson($exception); $response = ApiProblemResponse::fromExceptionToXml($exception);
Using the constructor and handling the response yourself.
use NilPortugues\Api\Problem\ApiProblem; use NilPortugues\Api\Problem\ApiProblemResponse; use NilPortugues\Api\Problem\Presenter\JsonPresenter; $apiProblem = new ApiProblem( 404, 'User with id 5 not found.', 'Not Found', 'user.not_found' ); $presenter = new JsonPresenter($apiProblem); //or XmlPresenter return new ApiProblemResponse($presenter);
Using an Exception and handling the response yourself.
use NilPortugues\Api\Problem\ApiProblem; use NilPortugues\Api\Problem\ApiProblemResponse; use NilPortugues\Api\Problem\Presenter\JsonPresenter; try { //...your code throwing an exception throw new \Exception('User with id 5 not found.', 404); } catch(\Exception $exception) { $problem = ApiProblem::fromException($exception); $presenter = new JsonPresenter($apiProblem); //or XmlPresenter return new ApiProblemResponse($presenter); }
Multiple Problems, one object
In order to report more than problem, you must use the additional details parameter.
use NilPortugues\Api\Problem\ApiProblem; use NilPortugues\Api\Problem\ApiProblemResponse; use NilPortugues\Api\Problem\Presenter\JsonPresenter; try { // some code of yours throws an exception... for instance: throw new \Exception('User data is not valid.', 500); } catch(\Exception $exception) { $additionalDetails = [ 'errors' => [ ['name' => 'username', 'error' => 'Username must be at least 5 characters long.'], ['name' => 'email', 'error' => 'Provided address is not a valid email.'], ], ] $apiProblem = ApiProblem::fromException( $exception, 'Input values do not match the requirements', 'user.invalid_data', $additionalDetails; ); $presenter = new JsonPresenter($apiProblem); //or XmlPresenter return new ApiProblemResponse($presenter); }
JSON Output
Headers
HTTP/1.1 500 Bad Request
Content-Type: application/problem+json
Body
{ "title": "Input values do not match the requirements", "status": 500, "detail": "User data is not valid.", "type": "user.invalid_data", "errors": [ { "name": "username", "error": "Username must be at least 5 characters long." }, { "name": "email", "error": "Provided address is not a valid email." } ] }
XML Output
Headers
HTTP/1.1 500 Bad Request
Content-Type: application/problem+xml
Body
<?xml version="1.0" encoding="UTF-8"?> <problem xmlns="urn:ietf:rfc:7807"> <title>Input values do not match the requirements</title> <status>500</status> <detail>User data is not valid.</detail> <type>user.invalid_data</type> <errors> <item> <name>username</name> <error>Username must be at least 5 characters long.</error> </item> <item> <name>email</name> <error>Provided address is not a valid email.</error> </item> </errors> </problem>
Contribute
Contributions to the package are always welcome!
- Report any bugs or issues you find on the issue tracker.
- You can grab the source code at the package's Git repository.
Support
Get in touch with me using one of the following means:
- Emailing me at contact@nilportugues.com
- Opening an Issue
Authors
License
The code base is licensed under the MIT license.