Chris@0: # Stack/Builder
Chris@0: 
Chris@0: Builder for stack middlewares based on HttpKernelInterface.
Chris@0: 
Chris@0: Stack/Builder is a small library that helps you construct a nested
Chris@0: HttpKernelInterface decorator tree. It models it as a stack of middlewares.
Chris@0: 
Chris@0: ## Example
Chris@0: 
Chris@0: If you want to decorate a [silex](https://github.com/fabpot/Silex) app with
Chris@0: session and cache middlewares, you'll have to do something like this:
Chris@0: 
Chris@0: ```php
Chris@0: use Symfony\Component\HttpKernel\HttpCache\Store;
Chris@0: 
Chris@0: $app = new Silex\Application();
Chris@0: 
Chris@0: $app->get('/', function () {
Chris@0:     return 'Hello World!';
Chris@0: });
Chris@0: 
Chris@0: $app = new Stack\Session(
Chris@0:     new Symfony\Component\HttpKernel\HttpCache\HttpCache(
Chris@0:         $app,
Chris@0:         new Store(__DIR__.'/cache')
Chris@0:     )
Chris@0: );
Chris@0: ```
Chris@0: 
Chris@0: This can get quite annoying indeed. Stack/Builder simplifies that:
Chris@0: 
Chris@0: ```php
Chris@0: $stack = (new Stack\Builder())
Chris@0:     ->push('Stack\Session')
Chris@0:     ->push('Symfony\Component\HttpKernel\HttpCache\HttpCache', new Store(__DIR__.'/cache'));
Chris@0: 
Chris@0: $app = $stack->resolve($app);
Chris@0: ```
Chris@0: As you can see, by arranging the layers as a stack, they become a lot easier
Chris@0: to work with.
Chris@0: 
Chris@0: In the front controller, you need to serve the request:
Chris@0: 
Chris@0: ```php
Chris@0: use Symfony\Component\HttpFoundation\Request;
Chris@0: 
Chris@0: $request = Request::createFromGlobals();
Chris@0: $response = $app->handle($request)->send();
Chris@0: $app->terminate($request, $response);
Chris@0: ```
Chris@0: Stack/Builder also supports pushing a `callable` on to the stack, for situations
Chris@0: where instantiating middlewares might be more complicated. The `callable` should
Chris@0: accept a `HttpKernelInterface` as the first argument and should also return a
Chris@0: `HttpKernelInterface`. The example above could be rewritten as:
Chris@0: 
Chris@0: ```php
Chris@0: $stack = (new Stack\Builder())
Chris@0:     ->push('Stack\Session')
Chris@0:     ->push(function ($app) {
Chris@0:         $cache = new HttpCache($app, new Store(__DIR__.'/cache'));
Chris@0:         return $cache;
Chris@0:     })
Chris@0: ;
Chris@0: ```
Chris@0: 
Chris@0: ## Inspiration
Chris@0: 
Chris@0: * [Rack::Builder](http://rack.rubyforge.org/doc/Rack/Builder.html)
Chris@0: * [HttpKernel middlewares](https://igor.io/2013/02/02/http-kernel-middlewares.html)