Merge pull request #108 from Howriq/issue-99

Issue #99: injectable input filters

Author: arhimede

docs/book/v6/extended-features/injectable-input-filters.md

@@ -0,0 +1,72 @@
+# Injectable input filters
+
+In the current version of 6.0, Dotkernel API has an Injectable Input Filter system into the constructors of our handlers.
+
+When building APIs or backend applications in PHP, especially within frameworks that support dependency injection, input validation is a critical concern.
+Many developers instinctively instantiate input filters or validators inside their handlers or controllers.
+However, injecting input filters is a cleaner, more testable, and flexible approach.
+
+The **previous** version that contained inline instantiation:
+
+```php
+public function handle(ServerRequestInterface $request): ResponseInterface
+{
+    $inputFilter = (new CreateAdminInputFilter())->setData((array) $request->getParsedBody());
+    if (! $inputFilter->isValid()) {
+        throw (new BadRequestException())->setMessages($inputFilter->getMessages());
+    }
+
+    $admin = $this->adminService->createAdmin($inputFilter->getValues());
+
+    return $this->createdResponse($request, $admin);
+}
+```
+
+While simple, this ties your handler directly to a concrete class. It’s harder to reuse logic across contexts and mock or replace the filter during testing.
+
+Our **current** approach uses constructor injection:
+
+```php
+class PostAdminResourceHandler extends AbstractHandler
+{
+    #[Inject(
+        AdminServiceInterface::class,
+        CreateAdminInputFilter::class,
+    )]
+    public function __construct(
+        protected AdminServiceInterface $adminService,
+        protected CreateAdminInputFilter $inputFilter,
+    ) {
+    }
+
+    /**
+     * @throws BadRequestException
+     * @throws ConflictException
+     * @throws NotFoundException
+     */
+    public function handle(ServerRequestInterface $request): ResponseInterface
+    {
+        $this->inputFilter->setData((array) $request->getParsedBody());
+        if (! $this->inputFilter->isValid()) {
+            throw (new BadRequestException())->setMessages($this->inputFilter->getMessages());
+        }
+
+        $admin = $this->adminService->createAdmin((array) $this->inputFilter->getValues());
+
+        return $this->createdResponse($request, $admin);
+    }
+}
+```
+
+This new approach makes it trivial to mock the filters during tests:
+
+```php
+$mockFilter = $this->createMock(CreateAdminInputFilter::class);
+$mockFilter->method('setData')->willReturnSelf();
+$mockFilter->method('isValid')->willReturn(true);
+
+$handler = new PostAdminResourceHandler($adminService, $mockFilter);
+$response = $handler->handle($request);
+```
+
+You're no longer tied to the real filter logic in your handler tests.

docs/book/v6/introduction/file-structure.md

@@ -31,7 +31,6 @@ This folder contains all application-related config files:
 * `development.config.php.dist` - Activates debug mode; gets symlinked as `development.config.php` when enabling development mode
 * `migrations.php` - Configuration for database migration, like migration file location and table to save the migration log
 * `pipeline.php` - Contains a list of middlewares, in the order of their execution
-* `twig-cs-fixer.php` - Configuration file for Twig code style checker/fixer
 
 ### `config/autoload` folder
 

docs/book/v6/introduction/packages.md

@@ -23,7 +23,6 @@
 * `mezzio/mezzio-fastroute` - FastRoute integration for Mezzio
 * `mezzio/mezzio-hal` - Hypertext Application Language implementation for PHP and PSR-15
 * `mezzio/mezzio-problem-details` - Problem Details for PSR-15 HTTP APIs addressing the RFC 7807 standard
-* `mezzio/mezzio-twigrenderer` - Twig integration for Mezzio
 * `ramsey/uuid-doctrine` - Use ramsey/uuid as a Doctrine field type
 * `roave/psr-container-doctrine` - Doctrine Factories for PSR-11 Containers
 * `symfony/filesystem` - Provides basic utilities for the filesystem

mkdocs.yml

@@ -42,6 +42,7 @@ nav:
           - "New Handler Structure": v6/extended-features/handler-structure.md
           - "Route Grouping": v6/extended-features/route-grouping.md
           - "Problem Details": v6/extended-features/problem-details.md
+          - "Injectable Input Filters": v6/extended-features/injectable-input-filters.md
       - Commands:
           - "Create admin account": v6/commands/create-admin-account.md
           - "Generate database migrations": v6/commands/generate-database-migrations.md