Merge pull request #106 from Howriq/issue-97

 Issue #97: route grouping

Author: arhimede

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)

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',
+        ],
+    ],
+];
+```

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

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