Merge branch 'main' into issue-110

Signed-off-by: Howriq <[email protected]>

Author: Howriq

docs/book/v5/tutorials/create-book-module.md

@@ -560,6 +560,13 @@ class BookHandler extends AbstractHandler implements RequestHandlerInterface
         return $this->createResponse($request, $book);
     }
 
+    public function getCollection(ServerRequestInterface $request): ResponseInterface
+    {
+        $books = $this->bookService->getRepository()->getBooks($request->getQueryParams());
+
+        return $this->createResponse($request, $books);
+    }
+
     public function post(ServerRequestInterface $request): ResponseInterface
     {
         $inputFilter = (new BookInputFilter())->setData($request->getParsedBody());
@@ -654,7 +661,7 @@ class RoutesDelegator
 
         $app->get(
             '/book/' . $uuid,
-            BookHandler::class,
+            BookCollection::class,
             'book.show'
         );
 

docs/book/v6/core-features/rendering-and-sending-emails.md

@@ -0,0 +1,44 @@
+# Rendering and sending emails
+
+In the previous versions of Dotkernel API we have been composing email bodies using **Twig** from the `mezzio/mezzio-twigrenderer` package.
+In the current version of Dotkernel API, we introduced the core mail service `Core/src/App/src/Service/MailService` which is responsible for sending all emails.
+
+Being a core service, `MailService` is used across all projects implementing the Core architecture.
+To compose and send an email, a solid implementation of `TemplateRendererInterface` was required to be injected into `MailService`, because each method rendered and parsed their respective templates in place before sending an email.
+This is acceptable with other Dotkernel applications which in most cases return a rendered template, but being that Dotkernel API mostly returns JSON objects, rendered with a different renderer, **Twig** had to be replaced with a lighter solution.
+
+The solution is a custom [`Api\App\Template\Renderer`](https://github.com/dotkernel/api/blob/6.0/src/App/src/Template/Renderer.php) implementing [`Api\App\Template\RendererInterface`](https://github.com/dotkernel/api/blob/6.0/src/App/src/Template/RendererInterface.php).
+This is a lightweight renderer, aimed at rendering a combination of **PHP** and **HTML** files with `phtml` extension.
+
+With the new solution, `MailService` requires no implementation of any renderer because it no longer has to render templates internally.
+Instead, an implementation of `Api\App\Template\RendererInterface` is first injected in the handler:
+
+```php
+class ExampleHandler extends AbstractHandler
+{
+    #[Inject(
+        MailService::class,
+        RendererInterface::class,
+    )]
+    public function __construct(
+        protected MailService $mailService,
+        protected RendererInterface $renderer,
+    ) {
+}
+```
+
+Then, the handler calls the renderer and saves the rendered template in a variable:
+
+```php
+$body = $this->renderer->render('user::welcome', ['user' => $user]);
+```
+
+And finally, the handler calls the mail service with the composed $body being passed as a parameter to the method which sends the email:
+
+```php
+// $user object contains email, firstname and lastname
+
+$this->mailService->sendWelcomeMail($user, $body);
+```
+
+> Other Dotkernel applications implementing the Core architecture do the same in the handlers, but keep using Twig as the template renderer.

mkdocs.yml

@@ -37,6 +37,7 @@ nav:
           - "Exceptions": v6/core-features/exceptions.md
           - "Dependency Injection": v6/core-features/dependency-injection.md
           - "Error reporting": v6/core-features/error-reporting.md
+          - "Rendering and Sending emails": v6/core-features/rendering-and-sending-emails.md
       - Extended features:
           - "Core and App": v6/extended-features/core-and-app.md
           - "New Handler Structure": v6/extended-features/handler-structure.md