Merge branch 'hotfix/408'

Close #408

Author: weierophinney

doc/book/features/router/fast-route.md

@@ -271,3 +271,82 @@ $container['FastRoute\RouteCollector'] = new FastRouteCollectorFactory();
 $container['FastRoute\RouteDispatcher'] = new FastRouteDispatcherFactory();
 $container['Zend\Expressive\Router\RouterInterface'] = new RouterFactory();
 ```
+
+### FastRoute caching support
+
+- Since zend-expressive-fastroute 1.3.0.
+
+Starting from version 1.3.0, zend-expressive-fastroute comes with support 
+for FastRoute native dispatch data caching.
+
+Enabling this feature requires changes to your configuration. Typically, router
+configuration occurs in `config/autoload/routes.global.php`; as such, we will
+reference that file when indicating configuration changes.
+
+The changes required are:
+
+- You will need to delegate creation of the router instance to a new factory.
+
+- You will need to add a new configuration entry, `$config['router']['fastroute']`. 
+  The options in this entry will be used by the factory to build the router
+  instance in order to toggle caching support and to specify a custom cache
+  file.
+
+As an example:
+
+``` php
+// File config/autoload/routes.global.php
+
+return [
+    'dependencies' => [
+        //..
+        'invokables' => [
+            /* ... */
+            // Comment out or remove the following line:
+            // Zend\Expressive\Router\RouterInterface::class => Zend\Expressive\Router\FastRouteRouter::class,
+            /* ... */
+        ],
+        'factories' => [
+            /* ... */
+            // Add this line; the specified factory now creates the router instance:
+            Zend\Expressive\Router\RouterInterface::class => Zend\Expressive\Router\FastRouteRouterFactory::class,
+            /* ... */
+        ],
+    ],
+    
+    // Add the following to enable caching support:
+    'router' => [
+        'fastroute' => [
+             // Enable caching support:
+            'cache_enabled' => true,
+             // Optional (but recommended) cache file path:
+            'cache_file'    => 'data/cache/fastroute.php.cache',
+        ],
+    ],
+
+    'routes' => [ /* ... */ ],
+]
+```
+
+The FastRoute-specific caching options are as follows:
+
+- `cache_enabled` (bool) is used to toggle caching support. It's advisable to enable 
+  caching in a production environment and leave it disabled for the development
+  environment. Commenting or omitting this option is equivalent to having it set
+  to `false`. We recommend enabling it in `config/autoload/routes.global.php`,
+  and, in development, disabling it within `config/autoload/routes.local.php` or
+  `config/autoload/local.php`.
+
+- `cache_file` (string) is an optional parameter that represents the path of 
+  the dispatch data cache file. It can be provided as an absolute file path or
+  as a path relative to the zend-expressive working directory. 
+
+  It defaults to `data/cache/fastroute.php.cache`, where `data/cache/` is the
+  cache directory defined within the zend-expressive skeleton application.  An
+  explicit absolute file path is recommended since the php `include` construct
+  will skip searching the `include_path` and the current directory.
+
+  If you choose a custom path, make sure that the directory exists and is
+  writable by the owner of the PHP process. As with any other zend-expressive
+  cached configuration, you will need to purge this file in order to enable any
+  newly added route when FastRoute caching is enabled.