Merge pull request #239 from mtymek/modular_expressive_cookbook

Add cookbook about modular applications

doc/book/cookbook/bookdown.json

@@ -6,6 +6,7 @@
         {"Setting custom 404 page handling": "custom-404-page-handling.md"},
         {"Registering custom view helpers when using zend-view": "using-custom-view-helpers.md"},
         {"Using zend-form view helpers": "using-zend-form-view-helpers.md"},
-        {"Using Expressive from a subdirectory": "using-a-base-path.md"}
+        {"Using Expressive from a subdirectory": "using-a-base-path.md"},
+        {"Building modular applications": "modular-layout.md"}
     ]
 }

doc/book/cookbook/modular-layout.md

@@ -0,0 +1,101 @@
+How can I make my application modular?
+======================================
+
+ZF2 applications are built with modules - independent units that can provide
+configuration, services and hooks to MVC lifecycle.
+
+While ZF ModuleManager can be used with Expressive, we suggest different approach: 
+modules that are based only on configuration. This is pretty powerful, and (contrary
+to ZF modules) doesn't affect performance. It still offers flexibility: each module
+can provide its own services (with factories), default configuration and routes. 
+
+This cookbook will show how to organize modules with 
+[`mtymek/expressive-config-manager`](https://github.com/mtymek/expressive-config-manager)
+- lightweight library that aggregates and merges configuration, optionally caching it.
+
+## Install configuration manager
+
+Configuration manager is available in Packagist:
+
+```bash
+$ composer require mtymek/expressive-config-manager
+```
+
+## Generate your config
+
+Default Expressive Skeleton comes with `config/config.php` file - main place that
+aggregates all configuration. Replace it with following code: 
+
+```php
+<?php
+
+use Zend\Expressive\ConfigManager\ConfigManager;
+use Zend\Expressive\ConfigManager\PhpFileProvider;
+
+$configManager = new ConfigManager(
+    [
+        new PhpFileProvider('config/autoload/{{,*.}global,{,*.}local}.php'),
+    ]
+);
+
+return new ArrayObject($configManager->getMergedConfig());
+```
+
+If you open application in a browser, it should still work in exactly the same way
+as it was before. Now you can start adding your modules.
+
+## First module
+
+`ConfigManager` does not force you to use any particular structure for your module.
+Only requirement is to expose default configuration using "config provider" - an
+invokable class that returns configuration array. For instance, this is how your
+module can provide its own routes:
+
+```php
+namespace App;
+
+class AppConfig
+{
+    public function __invoke()
+    {
+        return [
+            'routes' => [
+                [
+                    'name' => 'api.list-transactions',
+                    'path' => '/api/transactions',
+                    'middleware' => App\Action\ListTransactionsAction::class,
+                    'allowed_methods' => ['GET'],
+                ],
+                [
+                    'name' => 'api.refund-transaction',
+                    'path' => '/api/refund',
+                    'middleware' => App\Action\RefundAction::class,
+                    'allowed_methods' => ['POST'],
+                ],
+            ],
+        ];
+    }
+}
+```
+
+## Enabling module
+
+Finally, you can enable your module by adding config class `ConfigManager` constructor in
+`config/config.php` file:
+
+```php
+$configManager = new ConfigManager(
+    [
+        App\AppConfig::class,
+        new PhpFileProvider('config/autoload/{{,*.}global,{,*.}local}.php'),
+    ]
+);
+```
+
+This looks simple, but it is flexible:
+- You pass list of config providers to `ConfigManager` constructor.
+- Configuration is merged in the same order as it is passed.
+- You can override default configuration using `*.global.php` and `*.local.php` files.
+- If cached config is found, `ConfigManager` does not iterate over provider list.
+
+For more details, please refer to [Config Manager Documentation](https://github.com/mtymek/expressive-config-manager#expressive-configuration-manager).

mkdocs.yml

@@ -13,7 +13,7 @@ pages:
     - { Helpers: [{ Introduction: helpers/intro.md }, { UrlHelper: helpers/url-helper.md }, { ServerUrlHelper: helpers/server-url-helper.md }] }
     - { Emitters: emitters.md }
     - { Examples: usage-examples.md }
-    - { Cookbook: [{ 'Prepending a common path to all routes': cookbook/common-prefix-for-routes.md }, { 'Route-specific middleware pipelines': cookbook/route-specific-pipeline.md }, { 'Setting custom 404 page handling': cookbook/custom-404-page-handling.md }, { 'Registering custom view helpers when using zend-view': cookbook/using-custom-view-helpers.md }, { 'Using zend-form view helpers': cookbook/using-zend-form-view-helpers.md }, { 'Using Expressive from a subdirectory': cookbook/using-a-base-path.md }] }
+    - { Cookbook: [{ 'Prepending a common path to all routes': cookbook/common-prefix-for-routes.md }, { 'Route-specific middleware pipelines': cookbook/route-specific-pipeline.md }, { 'Setting custom 404 page handling': cookbook/custom-404-page-handling.md }, { 'Registering custom view helpers when using zend-view': cookbook/using-custom-view-helpers.md }, { 'Using zend-form view helpers': cookbook/using-zend-form-view-helpers.md }, { 'Using Expressive from a subdirectory': cookbook/using-a-base-path.md }, { 'Building modular applications': cookbook/modular-layout.md }] }
     - { 'Expressive Projects': expressive-projects.md }
 site_name: zend-expressive
 site_description: 'zend-expressive: PSR-7 Middleware Microframework'