diff --git a/docs/book/v6/extended-features/handler-structure.md b/docs/book/v6/extended-features/handler-structure.md index 859a30b..80cec08 100644 --- a/docs/book/v6/extended-features/handler-structure.md +++ b/docs/book/v6/extended-features/handler-structure.md @@ -38,6 +38,5 @@ In this way, the developer can easily figure out the functionality of each handl ## Mapping of the handlers -In the picture below you can see the mapping of our current handlers with their respective paths and actions: - -![Dotkernel API Mapping!](https://docs.dotkernel.org/img/api/naming-convention.png) +The full mapping of the handlers and their current paths and actions can be found [here](https://docs.dotkernel.org/img/api/naming-convention.png). +![naming-convention-thumbnail](https://docs.dotkernel.org/img/api/naming-convention-thumbnail.png) diff --git a/docs/book/v6/extended-features/problem-details.md b/docs/book/v6/extended-features/problem-details.md new file mode 100644 index 0000000..6d19d96 --- /dev/null +++ b/docs/book/v6/extended-features/problem-details.md @@ -0,0 +1,78 @@ +# Problem details + +With the usage of `mezzio/mezzio-problem-details` we have implemented a way to help the developers understand better the errors that they are getting from their APIs based on the [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457.html) standards. + +Example of a response with details: + +```json +{ + "title": "Unauthorized", + "type": "https://docs.dotkernel.org/api-documentation/v5/core-features/error-reporting/", + "status": 401, + "detail": "You are not allowed to report errors." +} +``` + +Usually the response includes: + +- A title related to the error +- The type of error +- The status of the request (e.g `404`) +- Different error messages + +More fields can be added based on the preference of the developer. + +## Our changes + +In order for us to implement this new feature, a new middleware component was required. +We have created `ProblemDetailsMiddleware` along with `ProblemDetailsNotFoundHandler` which is being called in the `config/pipeline.php` file. +Our exceptions have also been modified in order to be slimmed around the requirement for the `problem-details` package. + +Example from `src/App/src/Exception/BadRequestException.php`: + +```php +public static function create(string $detail, string $type = '', string $title = '', array $additional = []): self + { + $exception = new self(); + + $exception->type = $type; + $exception->detail = $detail; + $exception->status = StatusCodeInterface::STATUS_BAD_REQUEST; + $exception->title = $title; + $exception->additional = $additional; + + return $exception; + } +``` + +An example configuration file for setting custom links has also been created in `config/autoload/problem-details.global.php`. +Here the statuses of the API calls are being attributed to a link. + +```php +return [ + 'problem-details' => [ + 'default_types_map' => [ + StatusCodeInterface::STATUS_BAD_REQUEST + => 'https://datatracker.ietf.org/doc/html/rfc9110#name-400-bad-request', + StatusCodeInterface::STATUS_UNAUTHORIZED + => 'https://datatracker.ietf.org/doc/html/rfc9110#name-401-unauthorized', + StatusCodeInterface::STATUS_FORBIDDEN + => 'https://datatracker.ietf.org/doc/html/rfc9110#name-403-forbidden', + StatusCodeInterface::STATUS_NOT_FOUND + => 'https://datatracker.ietf.org/doc/html/rfc9110#name-404-not-found', + StatusCodeInterface::STATUS_METHOD_NOT_ALLOWED + => 'https://datatracker.ietf.org/doc/html/rfc9110#name-405-method-not-allowed', + StatusCodeInterface::STATUS_NOT_ACCEPTABLE + => 'https://datatracker.ietf.org/doc/html/rfc9110#name-406-not-acceptable', + StatusCodeInterface::STATUS_CONFLICT + => 'https://datatracker.ietf.org/doc/html/rfc9110#name-409-conflict', + StatusCodeInterface::STATUS_GONE + => 'https://datatracker.ietf.org/doc/html/rfc9110#name-410-gone', + StatusCodeInterface::STATUS_UNSUPPORTED_MEDIA_TYPE + => 'https://datatracker.ietf.org/doc/html/rfc9110#name-415-unsupported-media-type', + StatusCodeInterface::STATUS_INTERNAL_SERVER_ERROR + => 'https://datatracker.ietf.org/doc/html/rfc9110#name-500-internal-server-error', + ], + ], +]; +``` diff --git a/docs/book/v6/extended-features/route-grouping.md b/docs/book/v6/extended-features/route-grouping.md new file mode 100644 index 0000000..1b860ef --- /dev/null +++ b/docs/book/v6/extended-features/route-grouping.md @@ -0,0 +1,29 @@ +# Route grouping + +In Dotkernel 6.0 with the help of the new [dot-router](https://docs.dotkernel.org/dot-router/v1/overview/) package, we have managed to implement a nicer way of creating routes. +A lot of the times developers need to create sets of routes that have a similar format. As an example: + +```php +$app->post('/product/create', CreateProductHandler::class, 'product:create'); +$app->delete('/product/delete/{id}', DeleteProductHandler::class, 'product:delete'); +$app->patch('/product/update/{id}', UpdateProductHandler::class, 'product:update'); +$app->get('/product/view/{id}', GetProductHandler::class, 'product:view'); +``` + +Along with the features from `mezzio/mezzio-fastroute`, the new `dot-router` package provides the ability to create route groups which are collections of routes that have the same base string for the path. + +Here we have an example from `src/User/src/RoutesDelegator.php` with the new grouping method: + +```php +$routeCollector->group('/user/' . $uuid) + ->delete('', DeleteUserResourceHandler::class, 'user::delete-user') + ->get('', GetUserResourceHandler::class, 'user::view-user') + ->patch('', PatchUserResourceHandler::class, 'user::update-user'); +``` + +The advantages of this new implementation: + +- DRY - no need for repeating common route parts +- encapsulation - similar routes are grouped in a single block of code (vs each route a separate statement) +- easy path refactoring - modify all routes at once by changing only the prefix +- easy copying/moving - copying/moving an entire group makes sure that you don't accidentally omit a route diff --git a/mkdocs.yml b/mkdocs.yml index 4d04065..598e724 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -40,6 +40,7 @@ nav: - Extended features: - "Core and App": v6/extended-features/core-and-app.md - "New Handler Structure": v6/extended-features/handler-structure.md + - "Route Grouping": v6/extended-features/route-grouping.md - Commands: - "Create admin account": v6/commands/create-admin-account.md - "Generate database migrations": v6/commands/generate-database-migrations.md