Adds description for usage in a laminas-mvc based application

Signed-off-by: Frank Brückner <dev@froschdesignstudio.de>
laminas · Dec 19, 2022 · b1e7a7d · b1e7a7d
1 parent 32b5c35
commit b1e7a7d
Show file tree

Hide file tree

Showing 3 changed files with 143 additions and 15 deletions.
diff --git a/doc/book/application-integration/usage-in-a-laminas-mvc-application.md b/doc/book/application-integration/usage-in-a-laminas-mvc-application.md
@@ -0,0 +1,106 @@
+# Usage in a laminas-mvc Application
+
+The following example shows _one_ potential use case of laminas-eventmanager within
+a laminas-mvc based application.
+The example creates a listener for logging errors of an application with [laminas-log](https://docs.laminas.dev/laminas-log/).
+
+Before starting, make sure laminas-log is [installed and configured](https://docs.laminas.dev/laminas-log/installation/).
+
+laminas-eventmanager is already present in laminas-mvc based applications as it is an event-driven MVC layer based on the event manager.
+
+## Create Listener
+
+Create a listener as class using [a listener aggregate](../aggregates.md) and add the logger via constructor injection to create a valid object with all required dependencies, e.g. `module/Application/src/Listener/ErrorListener.php`:
+
+```php
+namespace Application\Listener;
+
+use Exception;
+use Laminas\EventManager\AbstractListenerAggregate;
+use Laminas\EventManager\EventManagerInterface;
+use Laminas\Log\Logger;
+use Laminas\Mvc\MvcEvent;
+
+final class ErrorListener extends AbstractListenerAggregate
+{
+    public function __construct(
+        private readonly Logger $logger
+    ) {}
+
+    public function attach(EventManagerInterface $events, $priority = 1): void
+    {
+        $this->listeners[] = $events->attach(
+            MvcEvent::EVENT_DISPATCH_ERROR,
+            [$this, 'onDispatchError']
+        );
+    }
+
+    public function onDispatchError(MvcEvent $event): void
+    {
+        /** @var Exception|null $exception */
+        $exception = $event->getParam('exception');
+        if ($exception) {
+            $this->logger->crit('Error: ' . $exception->getMessage());
+        } else {
+            $this->logger->crit('Error: ' . $event->getError());
+        }
+    }
+}
+```
+
+The listener aggregate was chosen because [it can listen to even more events](../aggregates.md#recommendations) due to the possible extension.
+
+NOTE: **More Events**
+All events that can be triggered are listed and explained in the [documentation of laminas-mvc](https://docs.laminas.dev/laminas-mvc/mvc-event/).
+
+## Register Listener
+
+To register a listener in a laminas-mvc based application use the application or module configuration, such as `config/autload/global.php` or `module/Application/config/module.config.php`, and the configuration key `listeners`.
+
+The current example uses the module configuration, e.g. `module/Application/config/module.config.php`:
+
+<pre class="language-php" data-line="4-6"><code>
+namespace Application;
+
+return [
+    'listeners' => [
+        Listener\ErrorListener::class,
+    ],
+    // …
+];
+</code></pre>
+
+All listeners registered in this way are fetched from the application service container.
+This means the listeners must be registered for the application service container.
+
+To register the listener for the application service container, extend the configuration of the module.
+Add the following lines to the module configuration file, e.g. `module/Application/config/module.config.php`:
+
+<pre class="language-php" data-line="3,8"><code>
+namespace Application;
+
+use Laminas\ServiceManager\AbstractFactory\ReflectionBasedAbstractFactory;
+
+return [
+    'service_manager' => [
+        'factories' => [
+            Listener\ErrorListener::class => ReflectionBasedAbstractFactory::class,
+        ],
+    ],
+    // …
+];
+</code></pre>
+
+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 listener class.
+
+If the listener has no dependencies, use the [factory `Laminas\ServiceManager\Factory\InvokableFactory`](https://docs.laminas.dev/laminas-servicemanager/configuring-the-service-manager/#factories).
+
+## Logging Message
+
+To log a message, produce a [dispatch error](https://docs.laminas.dev/laminas-mvc/mvc-event/#mvceventevent_dispatch_error-dispatcherror) by navigate to `http://localhost:8080/1234`, and the 404 page should be displayed.
+The attached listener will log a message and write it to the registered storage backend(s).
+
+## Learn More
+
+- [Listener Aggregates](../aggregates.md)
+- [The MvcEvent](https://docs.laminas.dev/laminas-mvc/mvc-event/)
diff --git a/doc/book/index.md b/doc/book/index.md
diff --git a/doc/book/index.md b/doc/book/index.md
@@ -0,0 +1,21 @@
+## Installation
+
+### Using Composer
+
+```bash
+$ composer require laminas/laminas-eventmanager
+```
+
+## Learn
+
+<ul class="list-group list-group-flush">
+    <li class="list-group-item">
+        <a href="/laminas-eventmanager/quick-start">Quick start</a>
+    </li>
+    <li class="list-group-item">
+        <a href="/laminas-eventmanager/tutorial">Tutorial</a>
+    </li>
+    <li class="list-group-item">
+        <a href="/laminas-eventmanager/application-integration/usage-in-a-laminas-mvc-application">Usage in a laminas-mvc application</a>
+    </li>
+</ul>
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -6,22 +6,24 @@ nav:
     - "Quick Start": quick-start.md
     - Tutorial: tutorial.md
     - Examples: examples.md
-    - Reference:
-        - "Wildcard Listeners": wildcard-listeners.md
-        - "Listener Aggregates": aggregates.md
-        - "Lazy Listeners":
-            - Intro: lazy-listeners/intro.md
-            - LazyListener: lazy-listeners/lazy-listener.md
-            - LazyEventListener: lazy-listeners/lazy-event-listener.md
-            - LazyListenerAggregate: lazy-listeners/lazy-listener-aggregate.md
-        - "EventManager API": api.md
-        - "Intercepting Filters": intercepting-filters.md
-        - "Migration Guide":
-            - Intro: migration/intro.md
-            - "Removed Functionality": migration/removed.md
-            - "Changed Functionality": migration/changed.md
+    - "Wildcard Listeners": wildcard-listeners.md
+    - "Listener Aggregates": aggregates.md
+    - "Lazy Listeners":
+        - Introduction: lazy-listeners/intro.md
+        - LazyListener: lazy-listeners/lazy-listener.md
+        - LazyEventListener: lazy-listeners/lazy-event-listener.md
+        - LazyListenerAggregate: lazy-listeners/lazy-listener-aggregate.md
+    - "EventManager API": api.md
+    - "Intercepting Filters": intercepting-filters.md
+    - "Application Integration":
+        - "Usage in a laminas-mvc Application": application-integration/usage-in-a-laminas-mvc-application.md
+    - "Migration Guide":
+        - Introduction: migration/intro.md
+        - "Removed Functionality": migration/removed.md
+        - "Changed Functionality": migration/changed.md
 site_name: laminas-eventmanager
 site_description: 'Implement events, signal slots, aspects, and observers!'
 repo_url: 'https://github.com/laminas/laminas-eventmanager'
 extra:
     project: Components
+    show_special_homepage: true