Merge pull request #79 from froschdesign/hotfix/docs/mvc-application-…

…integration Updates description for laminas-mvc application integration to simplify the description and usage
laminas · Nov 4, 2022 · 2b7b62c · 2b7b62c
2 parents 2e9a2f2 + 5436a0c
commit 2b7b62c
Showing 1 changed file with 35 additions and 74 deletions.
diff --git a/docs/book/application-integration/usage-in-a-laminas-mvc-application.md b/docs/book/application-integration/usage-in-a-laminas-mvc-application.md
@@ -1,15 +1,15 @@
 # Usage in a laminas-mvc Application
 
-The following example shows _one_ potential use case of laminas-inputfilter within
-a laminas-mvc based application. The example uses a module, a controller and the
-laminas-inputfilter plugin manager.
+The following example shows _one_ potential use case of laminas-inputfilter within a laminas-mvc based application.
+The example uses a module, a controller and the input filter plugin manager.
+
+The example is based on the [tutorial application](https://docs.laminas.dev/tutorials/getting-started/overview/) which builds an album inventory system.
 
 Before starting, make sure laminas-inputfilter is [installed and configured](../installation.md).
 
 ## Create Input Filter
 
-Create an input filter as separate class, e.g.
-`module/Album/src/InputFilter/QueryInputFilter.php`:
+[Create an input filter as separate class](../intro.md) using the `init` method, e.g. `module/Album/src/InputFilter/QueryInputFilter.php`:
 
 ```php
 namespace Album\InputFilter;
@@ -18,9 +18,9 @@ use Laminas\Filter\ToInt;
 use Laminas\I18n\Validator\IsInt;
 use Laminas\InputFilter\InputFilter;
 
-class QueryInputFilter extends InputFilter
+final class QueryInputFilter extends InputFilter
 {
-    public function init()
+    public function init(): void
     {
         // Page
         $this->add(
@@ -46,108 +46,69 @@ class QueryInputFilter extends InputFilter
 }
 ```
 
-## Using Input Filter
-
-### Create Controller
+## Create Controller
 
-Using the input filter in a controller, e.g.
-`module/Album/Controller/AlbumController.php`:
+[Create a controller class](https://docs.laminas.dev/laminas-mvc/quick-start/#create-a-controller) and inject the input filter plugin manager via the constructor, e.g. `module/Album/Controller/AlbumController.php`:
 
 ```php
 namespace Album\Controller;
 
 use Album\InputFilter\QueryInputFilter;
-use Laminas\InputFilter\InputFilterInterface;
+use Laminas\InputFilter\InputFilterPluginManager;
 use Laminas\Mvc\Controller\AbstractActionController;
 
-class AlbumController extends AbstractActionController
+use function assert;
+
+final class AlbumController extends AbstractActionController
 {
-    /** @var InputFilterInterface */
-    private $inputFilter;
-
-    public function __construct(InputFilterInterface $inputFilter)
-    {
-        $this->inputFilter = $inputFilter;        
-    }
+    public function __construct(
+        public readonly InputFilterPluginManager $inputFilterPluginManager
+    ) {}
 
     public function indexAction()
     {
-        $this->inputFilter->setData($this->getRequest()->getQuery());
-        $this->inputFilter->isValid();
-        $filteredParams = $this->inputFilter->getValues();
+        $inputFilter = $this->inputFilterPluginManager->get(QueryInputFilter::class);
+        assert($inputFilter instanceof QueryInputFilter);
+
+        $inputFilter->setData($this->getRequest()->getQuery());
+        $inputFilter->isValid();
+        $filteredParams = $inputFilter->getValues();
 
         // …
     }
 }
 ```
 
-### Create Factory for Controller
-
-Fetch the `QueryInputFilter` from the input filter plugin manager in a factory,
-e.g. `src/Album/Handler/ListHandlerFactory.php`:
-
-```php
-namespace Album\Controller;
-
-use Album\InputFilter\QueryInputFilter;
-use Psr\Container\ContainerInterface;
-use Laminas\InputFilter\InputFilterPluginManager;
-use Laminas\ServiceManager\Factory\FactoryInterface;
-
-class AlbumControllerFactory implements FactoryInterface
-{
-    public function __invoke(
-        ContainerInterface $container,
-        $requestedName,
-        array $options = null
-    ) {
-        /** @var InputFilterPluginManager $pluginManager */
-        $pluginManager = $container->get(InputFilterPluginManager::class);
-        $inputFilter   = $pluginManager->get(QueryInputFilter::class);
-
-        return new AlbumController($inputFilter);
-    }
-}
-```
-
-> ### Instantiating the Input Filter
+> INFO: **Instantiating the Input Filter**
 >
-> The `InputFilterPluginManager` is used instead of directly instantiating the
-> input filter to ensure to get the filter and validator plugin managers
-> injected. This allows usage of any filters and validators registered with
-> their respective plugin managers.
+> The input filter plugin manager (`Laminas\InputFilter\InputFilterPluginManager`) is used instead of directly instantiating the input filter to ensure to get the filter and validator plugin managers injected.
+> This allows usage of any filters and validators registered with their respective plugin managers.
 >
-> Additionally the `InputFilterPluginManager` calls the `init` method _after_
-> instantiating the input filter, ensuring all dependencies are fully injected
-> first.
+> Additionally, the input filter plugin manager calls the `init` method _after_ instantiating the input filter, ensuring all dependencies are fully injected first.
 
 ## Register Input Filter and Controller
 
-Extend the configuration of the module to register the input filter and
-controller in the application.  
-Add the following lines to the module configuration file, e.g.
-`module/Album/config/module.config.php`:
+If no separate factory is required for the input filter, then the input filter plugin manager will be instantiating the input filter class without prior registration. Otherwise, the input filter must be registered.
+
+To [register the controller](https://docs.laminas.dev/laminas-mvc/quick-start/#create-a-route) for the application, extend the configuration of the module.
+Add the following lines to the module configuration file, e.g. `module/Album/config/module.config.php`:
 
 <!-- markdownlint-disable MD033 -->
-<pre class="language-php" data-line="8-9,12-17"><code>
+<pre class="language-php" data-line="8-9"><code>
 namespace Album;
 
-use Laminas\ServiceManager\Factory\InvokableFactory;
+use Laminas\ServiceManager\AbstractFactory\ReflectionBasedAbstractFactory;
 
 return [
     'controllers' => [
         'factories' => [
             // Add this line
-            Controller\AlbumController::class => Controller\AlbumControllerFactory::class,
-        ],
-    ],
-    // Add the following array
-    'input_filters' => [
-        'factories => [
-            InputFilter\QueryInputFilter::class => InvokableFactory::class,
+            Controller\AlbumController::class => ReflectionBasedAbstractFactory::class,
         ],
     ],
     // …
 ];
 </code></pre>
 <!-- markdownlint-enable MD033 -->
+
+The example uses the [reflection factory from laminas-servicemanager](https://docs.laminas.dev/laminas-servicemanager/reflection-abstract-factory/) to resolve the constructor dependencies for the controller class.