mediagone / symfony-easy-api
Quickly build JSON API using plain Symfony controllers.
Installs: 3 128
Dependents: 0
Suggesters: 0
Security: 0
Stars: 2
Watchers: 1
Forks: 1
Open Issues: 0
Requires
- php: ^7.4|^8.0
- ext-json: *
- symfony/http-foundation: ^4.0|^5.0|^6.0|^7.0
Requires (Dev)
- phpunit/phpunit: ^9.0
README
This package provides helper classes to build a Json API very easily from plain Symfony controllers.
Supported features :
- Single and Collection results
- Pagination for Collection results
- Out of the box support for most useful status codes (200, 201, 202, 204, 400, 401, 403, 404, 405, 409, 410, 415, 422, 429, 500 and 501).
Installation
This package requires PHP 7.4+.
Add it as Composer dependency:
$ composer require mediagone/symfony-easy-api
Introduction
This package provides several classes to handle API requests and return structured JSON responses:
ApiPayload200Success
ApiPayload201Created
ApiPayload202Accepted
ApiPayload204NoContent
ApiPayloadError400BadRequest
ApiPayloadError401Unauthorized
ApiPayloadError403Forbidden
ApiPayloadError404NotFound
ApiPayloadError405MethodNotAllowed
ApiPayloadError409Conflict
ApiPayloadError410Gone
ApiPayloadError415UnsupportedMediaType
ApiPayloadError422UnprocessableEntity
ApiPayloadError429TooManyRequests
ApiPayloadError500ServerError
ApiPayloadError501NotImplemented
Examples
The easiest way to build an API controller is to use the EasyApi
class and wrap the controller code in an anonymous function, to benefit from automatic error handling.
1. Entity instance API endpoint
The EasyApi->response
method accepts any callable argument that returns an ApiPayload
instance.
use App\Thing\ThingRepository; use Mediagone\Symfony\EasyApi\EasyApi; use Mediagone\Symfony\EasyApi\Payloads\ApiPayload200Success; use Mediagone\Symfony\EasyApi\Payloads\ApiPayloadError404NotFound; use Symfony\Component\HttpFoundation\Response; /** * @Route("/api/things/{thingId}", name="api_things", methods={"GET"}) */ final class ApiEndpointController { public function __invoke(int $thingId, EasyApi $easyApi, ThingRepository $thingRepository) : Response { return $easyApi->response( function() use ($thingId, $thingRepository) { // Any uncatched exception would be automatically converted into an ApiPayloadError500ServerError response's payload. if ($thingId < 1) { throw new LogicException("Invalid `\$thingId` value ($thingId)"); } $thing = $thingRepository->find($thingId); if ($thing === null) { // Explicit "not found" error response's payload return ApiPayloadError404NotFound::create('Thing not found (id: '.$thingId.')'); } return ApiPayload200Success::createWithSingleResult($thing); } ); } }
In case of success, the previous controller will return the following JSON object:
{ "success": true, "status": "ok", "statusCode": 200, "payload": { "result": { "id": 1, "name": "First thing" } } }
Or a "not found" response:
{ "success": false, "status": "not_found", "statusCode": 404, "error": "not_found", "errorDescription": "Thing not found (id: 1)", "errorCode": 0 }
Or a "server error" response:
{ "success": false, "status": "server_error", "statusCode": 500, "error": "server_error", "errorDescription": "Unexpected server error: Invalid `$thingId` value (-1)", "errorCode": 0 }
Note: errorCode
is the internal error's code of the PHP exception (0 by default). You can generally define it by passing an additional integer argument to the constructor, eg. throw new LogicException("Invalid
$thingId value ($thingId)", 1234);
.
2. Entity collection API endpoint
You can also return multiple results by using the ApiPayload200Success::createWithArrayResult
factory method:
/** * @Route("/api/things", name="api_things", methods={"GET"}) */ final class ApiEndpointController { public function __invoke(EasyApi $easyApi, ThingRepository $thingRepository) : Response { return $easyApi->response( function() use ($thingRepository) { $things = $thingRepository->findAll(); return ApiPayload200Success::createWithArrayResult($things); } ); } }
It will result in a slightly different JSON object:
{ "success": true, "status": "ok", "statusCode": 200, "payload": { "results": [ { "id": 1, "name": "First thing" }, { "id": 2, "name": "Second thing" }, { "id": 3, "name": "Third thing" } ], "resultsCount": 3, "resultsCountTotal": 3, "page": 1, "pageCount": 1 } }
3. Collection pagination
When dealing with a lot of database entries, you may want to paginate results to retrieve them chunk by chunk.
The package provides the ApiPagination
class to help with that feature.
It requires two database queries: one to count the total number of results, and another to fetch the requested results:
use Mediagone\Symfony\EasyApi\EasyApi; use Mediagone\Symfony\EasyApi\Payloads\ApiPayload; use Mediagone\Symfony\EasyApi\Payloads\ApiPayload200Success; use Mediagone\Symfony\EasyApi\Request\ApiPagination; use Symfony\Component\HttpFoundation\Response; use Symfony\Component\Routing\Annotation\Route; #[Route('/api/things/{requestedPage}', name:'api_things_list')] public function __invoke(int $requestedPage = 1, ThingRepository $thingRepository): Response { return $easyApi->response(static function () use ($requestedPage, $thingRepository) : ApiPayload { // Count the total number of Things in the db $thingsCount = $thingRepository->countAll(); // Create a pagination object $pagination = ApiPagination::create($requestedPage, 5, $thingsCount); // Query the page's results $things = $thingRepository->findAllPaginated($pagination); return ApiPayload200Success::createWithArrayResult($things, $pagination); } }
Assuming that you have 93 rows in your database and you are requesting the 2nd page of 5 results, you'll receive the following JSON response:
{ "success": true, "status": "ok", "statusCode": 200, "payload": { "results": [ { "id": 6, "name": "6th thing" }, { "id": 7, "name": "7th thing" }, { "id": 8, "name": "8th thing" }, { "id": 9, "name": "9th thing" }, { "id": 10, "name": "10th thing" } ], "resultsCount": 5, "resultsCountTotal": 93, "page": 2, "pageCount": 19 } }
License
Symfony EasyAPI is licensed under MIT license. See LICENSE file.