diff --git a/core/lib/Drupal/Core/DependencyInjection/Compiler/StackedKernelPass.php b/core/lib/Drupal/Core/DependencyInjection/Compiler/StackedKernelPass.php index 267d2be..9869e66 100644 --- a/core/lib/Drupal/Core/DependencyInjection/Compiler/StackedKernelPass.php +++ b/core/lib/Drupal/Core/DependencyInjection/Compiler/StackedKernelPass.php @@ -14,6 +14,40 @@ /** * Provides a compiler pass for stacked HTTP kernels. * + * Builds the HTTP kernel by collecting all services tagged 'http_middleware' + * and assembling them into a StackedKernel. The middleware with the lowest + * priority ends up as the outermost while the highest priority middleware + * wraps the actual HTTP kernel defined by the http_kernel.basic service. + * + * The 'http_middleware' service tag additionally accepts a 'responder' + * parameter. It should be set to TRUE if many or most requests will be handled + * directly by the middleware. Any underlying middleware and the HTTP kernel are + * then flagged as 'lazy'. As a result those low priority services and their + * dependencies are only initialized if the 'responder' middleware fails to + * generate a response and the request is delegated to the underlying kernel. + * + * In general middlewares should not have heavy dependencies. This is especially + * important for high-priority services which need to run before the internal + * page cache. + * + * An example of a high priority middleware. + * @code + * http_middleware.reverse_proxy: + * class: Drupal\Core\StackMiddleware\ReverseProxyMiddleware + * arguments: ['@settings'] + * tags: + * - { name: http_middleware, priority: 300 } + * @endcode + * + * An example of a responder middleware: + * @code + * http_middleware.page_cache: + * class: Drupal\page_cache\StackMiddleware\PageCache + * arguments: ['@cache.render', '@page_cache_request_policy', '@page_cache_response_policy'] + * tags: + * - { name: http_middleware, priority: 200, responder: true } + * @endcode + * * @see \Stack\Builder */ class StackedKernelPass implements CompilerPassInterface {