Decorating Applications with Stack (MKEPUG 2014)

Stack is a convention for composing HttpKernelInterface middlewares. By following Stack's conventions you can add behavior and functionality to any application based on Symfony's HttpKernelInterface. This means Stack middlewares can be applied to Silex, Laravel 4, and Drupal 8 applications in addition to any other HttpKernelInterface based application. Learn the conventions, see community middlewares, and find out how to get started with Stack.

Transcript

1. Decorating Applications with Stack Milwaukee PHP User Group September 9th, 2014 @beausimensen dflydev.com @stackphp stackphp.com
2. Hello, Stack!
3. #silex-php
5. February 1st, 2013 <simensen> igorw: what is the closest analogy to middlewares is there in silex/symfony? anything? <igorw> simensen: what kind of middlewares? <simensen> like ruby rack middlewares or python middlewares. <igorw> httpkernel decorators ... <igorw> I guess you can think of it like a stack of httpkernels?
6. May 23rd, 2013
7. So what is Stack?
8. Stack is a convention for composing HttpKernelInterface middlewares
9. Stack is a convention for composing HttpKernelInterface middlewares
10. Middlewares
12. – https://docs.djangoproject.com/en/dev/topics/http/middleware/ “Middleware is a framework of hooks into Django’s request/response processing. It’s a light, low-level “plugin” system for globally altering Django’s input or output.”
13. – https://docs.djangoproject.com/en/dev/topics/http/middleware/ "Each middleware component is responsible for doing some specific function. For example, Django includes a middleware component [...] that associates users with requests using sessions."
15. – http://rubylearning.com/blog/a-quick-introduction-to-rack/#C12 “The fundamental idea behind Rack middleware is – come between the calling client and the server, process the HTTP request before sending it to the server, and processing the HTTP response before returning it to the client.”
16. – http://zaiste.net/2012/08/concisely_about_rack_applications/ "Rack middleware provides a way to implement a chained process execution for web applications. It's an implementation of the pipeline design pattern. It acts "in the middle" between the client and the server processing requests before they reach the server and responses before they are returned to the client."
17. Stack is a convention for composing HttpKernelInterface middlewares
18. HttpKernelInterface
20. –Fabien Potencier, HttpKernelInterface.php “HttpKernelInterface handles a Request to convert it to a Response.”
22. "Stack is framework agnostic."
24. "Framework agnostic," my foot!
25. ... and more!
26. Stack is a convention for composing HttpKernelInterface middlewares
27. Composition
28. HAS-A vs IS-A
29. HAS-A <3
30. Interfaces?
31. Decorate them!
32. WRAPS-A? :)
33. MUST implement every method Good old RFC 2119...
34. :(
35. just one method
36. handle()
37. :)
38. MAY delegate to decorated object Good old RFC 2119...
39. class Passthru implements HttpKernelInterface { private $app; public function __construct(HttpKernelInterface $app) { $this->app = $app; } public function handle( Request $request, $type = self::MASTER_REQUEST, $catch = true ) { return $this->app->handle($request, $type, $catch) } }
40. for the sake of brevity
41. "use HttpKernelInterface as HKI"
42. public function handle($request)
43. class Passthru implements HKI { private $app; public function __construct(HKI $app) { $this->app = $app; } public function handle($request) { return $this->app->handle($request) } }
44. class Passthru implements HKI { private $app; public function __construct(HKI $app) { $this->app = $app; } public function handle($request) { return $this->app->handle($request) } }
45. Actually...
46. class Passthru implements HKI { public function handle($request) { return $this->app->handle($request) } }
47. class Passthru implements HKI { public function handle($request) { return $this->app->handle($request) } }
48. Stack is a convention for composing HttpKernelInterface middlewares
49. Conventions
50. Stack is NOT a library
51. Stack is NOT a framework
52. • A Stack middleware MUST implement the HttpKernelInterface. • A Stack middleware MAY delegate to a decorated HttpKernelInterface instance. • A Stack middleware MUST take an HttpKernelInterface as its first constructor argument. Good old RFC 2119...
53. That’s it. That’s a Stack middleware.
54. STACK-1 Core
55. STACK-2 Authentication
56. STACK-3 Authorization
57. Stack is a convention for composing HttpKernelInterface middlewares
58. Anatomy of a Middleware
59. class Passthru implements HKI { public function handle($request) { return $this->app->handle($request) } }
60. class Passthru implements HKI { public function handle($request) { ! // // Request / before // ! // Delegate $response = $this->app->handle($request) ! // // Response / after // ! return $response; } }
65. Stack Builder
66. Builder is NOT required to "implement Stack"
67. Builder IS a tool to help "implement Stack"
68. $stack = (new Stack\Builder()) ! ->push('Stack\Session') ! ->push('Dflydev\Stack\BasicAuthentication') ! ->push('Silpion\Stack\Logger'); ! $app = new YourAppKernel(); ! $app = $stack->resolve($app);
69. push() accepts the classname of a Stack middleware !
70. push() accepts the classname of a Stack middleware ! ... or ...
71. a callable whose first argument is an HttpKernelInterface instance !
72. class Application implements HttpKernelInterface { public function run(SymfonyRequest $request = null) { $request = $request ?: $this['request']; ! $response = with($stack = $this->getStackedClient())->handle($request); ! $response->send(); ! $stack->terminate($request, $response); } ! protected function getStackedClient() { $sessionReject = $this->bound('session.reject') ? $this['session.reject'] : null; ! $client = (new \Stack\Builder) ->push('Illuminate\Cookie\Guard', $this['encrypter']) ->push('Illuminate\Cookie\Queue', $this['cookie']) ->push('Illuminate\Session\Middleware', $this['session'], $sessionReject); ! $this->mergeCustomMiddlewares($client); ! return $client->resolve($this); } }
73. class StackedKernelPass implements CompilerPassInterface { public function process(ContainerBuilder $container) { if (!$container->hasDefinition('http_kernel_factory')) { return; } ! $http_kernel_factory = $container->getDefinition('http_kernel_factory'); $middleware_priorities = array(); $middleware_arguments = array(); foreach ($container->findTaggedServiceIds('http_middleware') as $id => $attributes) { $priority = isset($attributes[0]['priority']) ? $attributes[0]['priority'] : 0; $middleware_priorities[$id] = $priority; $definition = $container->getDefinition($id); $middleware_arguments[$id] = $definition->getArguments(); array_unshift($middleware_arguments[$id], $definition->getClass()); } array_multisort($middleware_priorities, SORT_DESC, $middleware_arguments, SORT_DESC); ! foreach ($middleware_arguments as $id => $push_arguments) { $http_kernel_factory->addMethodCall('push', $push_arguments); } } }
74. Middlewares
75. Passthru Middleware
76. class Passthru implements HKI { public function handle($request) { return $this->app->handle($request) } }
77. Inline Middleware (Inline functions / callables)
78. class Inline implements HKI { public function __construct(HKI $app, $callable) { $this->app = $app; $this->callable = $callable; } public function handle($request) { return call_user_func($this->callable, $this->app); } }
79. $app = new Silex\Application(); ! $app->get('/', function (Request $request) { if ('success' === $request->attributes->get('callable_middleware')) { return new Response('SUCCESS'); } ! return new Response('FAILED', 500); }); ! $inlineMiddleware = function(HKI $app) { $request->attributes->set('callable_middleware', 'success'); $response = $app->handle($request, $type, $catch); $response->setContent('['.$response->getContent().']'); return $response; }; ! $stack = (new Stack\Builder()) ->push('Stack\Inline', $inlineMiddleware); ! $app = $stack->resolve($app);
80. 200, "[SUCCESS]"
81. Great for testing
82. Session Middleware
83. class Session implements HKI { public function __construct(HKI $app, $session) { $this->app = $app; $this->session = $session; } public function handle($request) { $request->setSession($this->session); $this->session->setId($request->cookies->get($this->session->getName())); ! $response = $this->app->handle($request); ! if ($this->session && $this->session->isStarted()) { $response->headers->setCookie(new Cookie( $session->getName(), $session->getId(), /* ... */ )); } ! return $response; } }
84. class Session implements HKI { public function __construct(HKI $app, $session) { $this->app = $app; $this->session = $session; } public function handle($request) { $request->setSession($this->session); $this->session->setId($request->cookies->get($this->session->getName())); ! $response = $this->app->handle($request); ! if ($this->session && $this->session->isStarted()) { $response->headers->setCookie(new Cookie( $session->getName(), $session->getId(), /* ... */ )); } ! return $response; } }
85. class Session implements HKI { public function __construct(HKI $app, $session) { $this->app = $app; $this->session = $session; } public function handle($request) { $request->setSession($this->session); $this->session->setId($request->cookies->get($this->session->getName())); ! $response = $this->app->handle($request); ! if ($this->session && $this->session->isStarted()) { $response->headers->setCookie(new Cookie( $session->getName(), $session->getId(), /* ... */ )); } ! return $response; } }
86. class Session implements HKI { public function __construct(HKI $app, $session) { $this->app = $app; $this->session = $session; } public function handle($request) { $request->setSession($this->session); $this->session->setId($request->cookies->get($this->session->getName())); ! $response = $this->app->handle($request); ! if ($this->session && $this->session->isStarted()) { $response->headers->setCookie(new Cookie( $session->getName(), $session->getId(), /* ... */ )); } ! return $response; } }
87. class Session implements HKI { public function __construct(HKI $app, $session) { $this->app = $app; $this->session = $session; } public function handle($request) { $request->setSession($this->session); $this->session->setId($request->cookies->get($this->session->getName())); ! $response = $this->app->handle($request); ! if ($this->session && $this->session->isStarted()) { $response->headers->setCookie(new Cookie( $session->getName(), $session->getId(), /* ... */ )); } ! return $response; } }
88. (It is actually a little more complicated than that)
89. $app = new Silex\Application(); ! $app->get('/login', function (Request $request) { $session = $request->getSession(); $username = $request->server->get('PHP_AUTH_USER'); $password = $request->server->get('PHP_AUTH_PW'); if ('igor' === $username && 'password' === $password) { $session->set('user', array('username' => $username)); return new RedirectResponse('/account'); } return new Response('Please sign in.', 401, [ 'WWW-Authenticate' => sprintf('Basic realm="%s"', 'site_login'), ]); }); ! $app->get('/account', function (Request $request) { $session = $request->getSession(); if (null === $user = $session->get('user')) { return new RedirectResponse('/login'); } return sprintf('Welcome %s!', $user['username']); }); ! $stack = (new Stack\Builder()) ->push('Stack\Session'); ! $app = $stack->resolve($app);
90. URL Map
91. class UrlMap implements HKI { public function __construct(HKI $app, $map) { $this->app = $app; $this->map = $map; } public function handle($request) { $pathInfo = rawurldecode($request->getPathInfo()); foreach ($this->map as $path => $app) { if (0 === strpos($pathInfo, $path)) { $server = $request->server->all(); $server['SCRIPT_FILENAME'] = $server['SCRIPT_NAME'] = $server['PHP_SELF'] = $request->getBaseUrl().$path; $attributes = $request->attributes->all(); $attributes['stack.url_map.prefix'] = $request->getBaseUrl().$path; $newRequest = $request->duplicate(null, null, $attributes, null, null, $server); return $app->handle($newRequest, $type, $catch); } } return $this->app->handle($request); } }
92. class UrlMap implements HKI { public function __construct(HKI $app, $map) { $this->app = $app; $this->map = $map; } public function handle($request) { $pathInfo = rawurldecode($request->getPathInfo()); foreach ($this->map as $path => $app) { if (0 === strpos($pathInfo, $path)) { $server = $request->server->all(); $server['SCRIPT_FILENAME'] = $server['SCRIPT_NAME'] = $server['PHP_SELF'] = $request->getBaseUrl().$path; $attributes = $request->attributes->all(); $attributes['stack.url_map.prefix'] = $request->getBaseUrl().$path; $newRequest = $request->duplicate(null, null, $attributes, null, null, $server); return $app->handle($newRequest, $type, $catch); } } return $this->app->handle($request); } }
93. class UrlMap implements HKI { public function __construct(HKI $app, $map) { $this->app = $app; $this->map = $map; } public function handle($request) { $pathInfo = rawurldecode($request->getPathInfo()); foreach ($this->map as $path => $app) { if (0 === strpos($pathInfo, $path)) { $server = $request->server->all(); $server['SCRIPT_FILENAME'] = $server['SCRIPT_NAME'] = $server['PHP_SELF'] = $request->getBaseUrl().$path; $attributes = $request->attributes->all(); $attributes['stack.url_map.prefix'] = $request->getBaseUrl().$path; $newRequest = $request->duplicate(null, null, $attributes, null, null, $server); return $app->handle($newRequest, $type, $catch); } } return $this->app->handle($request); } }
94. class UrlMap implements HKI { public function __construct(HKI $app, $map) { $this->app = $app; $this->map = $map; } public function handle($request) { $pathInfo = rawurldecode($request->getPathInfo()); foreach ($this->map as $path => $app) { if (0 === strpos($pathInfo, $path)) { $server = $request->server->all(); $server['SCRIPT_FILENAME'] = $server['SCRIPT_NAME'] = $server['PHP_SELF'] = $request->getBaseUrl().$path; $attributes = $request->attributes->all(); $attributes['stack.url_map.prefix'] = $request->getBaseUrl().$path; $newRequest = $request->duplicate(null, null, $attributes, null, null, $server); return $app->handle($newRequest, $type, $catch); } } return $this->app->handle($request); } }
95. class UrlMap implements HKI { public function __construct(HKI $app, $map) { $this->app = $app; $this->map = $map; } public function handle($request) { $pathInfo = rawurldecode($request->getPathInfo()); foreach ($this->map as $path => $app) { if (0 === strpos($pathInfo, $path)) { $server = $request->server->all(); $server['SCRIPT_FILENAME'] = $server['SCRIPT_NAME'] = $server['PHP_SELF'] = $request->getBaseUrl().$path; $attributes = $request->attributes->all(); $attributes['stack.url_map.prefix'] = $request->getBaseUrl().$path; $newRequest = $request->duplicate(null, null, $attributes, null, null, $server); return $app->handle($newRequest, $type, $catch); } } return $this->app->handle($request); } }
96. class UrlMap implements HKI { public function __construct(HKI $app, $map) { $this->app = $app; $this->map = $map; } public function handle($request) { $pathInfo = rawurldecode($request->getPathInfo()); foreach ($this->map as $path => $app) { if (0 === strpos($pathInfo, $path)) { $server = $request->server->all(); $server['SCRIPT_FILENAME'] = $server['SCRIPT_NAME'] = $server['PHP_SELF'] = $request->getBaseUrl().$path; $attributes = $request->attributes->all(); $attributes['stack.url_map.prefix'] = $request->getBaseUrl().$path; $newRequest = $request->duplicate(null, null, $attributes, null, null, $server); return $app->handle($newRequest, $type, $catch); } } return $this->app->handle($request); } }
97. class UrlMap implements HKI { public function __construct(HKI $app, $map) { $this->app = $app; $this->map = $map; } public function handle($request) { $pathInfo = rawurldecode($request->getPathInfo()); foreach ($this->map as $path => $app) { if (0 === strpos($pathInfo, $path)) { $server = $request->server->all(); $server['SCRIPT_FILENAME'] = $server['SCRIPT_NAME'] = $server['PHP_SELF'] = $request->getBaseUrl().$path; $attributes = $request->attributes->all(); $attributes['stack.url_map.prefix'] = $request->getBaseUrl().$path; $newRequest = $request->duplicate(null, null, $attributes, null, null, $server); return $app->handle($newRequest, $type, $catch); } } return $this->app->handle($request); } }
98. class UrlMap implements HKI { public function __construct(HKI $app, $map) { $this->app = $app; $this->map = $map; } public function handle($request) { $pathInfo = rawurldecode($request->getPathInfo()); foreach ($this->map as $path => $app) { if (0 === strpos($pathInfo, $path)) { $server = $request->server->all(); $server['SCRIPT_FILENAME'] = $server['SCRIPT_NAME'] = $server['PHP_SELF'] = $request->getBaseUrl().$path; $attributes = $request->attributes->all(); $attributes['stack.url_map.prefix'] = $request->getBaseUrl().$path; $newRequest = $request->duplicate(null, null, $attributes, null, null, $server); return $app->handle($newRequest, $type, $catch); } } return $this->app->handle($request); } }
99. class UrlMap implements HKI { public function __construct(HKI $app, $map) { $this->app = $app; $this->map = $map; } public function handle($request) { $pathInfo = rawurldecode($request->getPathInfo()); foreach ($this->map as $path => $app) { if (0 === strpos($pathInfo, $path)) { $server = $request->server->all(); $server['SCRIPT_FILENAME'] = $server['SCRIPT_NAME'] = $server['PHP_SELF'] = $request->getBaseUrl().$path; $attributes = $request->attributes->all(); $attributes['stack.url_map.prefix'] = $request->getBaseUrl().$path; $newRequest = $request->duplicate(null, null, $attributes, null, null, $server); return $app->handle($newRequest, $type, $catch); } } return $this->app->handle($request); } }
100. $app = new Application(); $app->get('/', function () { return "Main Application!"; }); ! $blog = new Application(); $blog->get('/', function () { return "This is the blog!"; }); ! $forum = new Application(); $forum->get('/', function () { return "This is the forum!"; }); ! $map = [ "/blog" => $blog, "/forum" => $forum, ]; ! $stack = (new Stack\Builder()) ->push('Stack\UrlMap', $map); ! $app = $stack->resolve($app);
101. HTTP Cache
102. The original Stack middleware
103. class HttpCache implements HKI { public function __construct(HKI $app, StoreInterface $store) { $this->app = $app; $this->store = $store; } public function handle($request) { if ($this->store->isStillCached($request)) { $response = $this->store->getFromCache($request); } else { $response = $this->app->handle($request); } ! $response = $this->app->handle($request); ! if ($this->store->shouldCache($request, $response)) { $this->store->cache($request, $response); } ! return $response; } }
104. (That was not even close to what actually happens...)
105. Geo IP
106. class GeoIp implements HKI { public function __construct(HKI $app, $geocoder, $header = 'X-Country') { $this->app = $app; $this->geocoder = $geocoder; $this->header = $header; } public function handle($request) { $results = $this->geocoder->geocode($request->getClientIp()); if ($country = $results->getCountryCode()) { $request->headers->set($this->header, $country, true); } return $this->app->handle($request); } }
107. $app = new Silex\Application(); ! $app->get('/', function(Request $request) { $ip = $request->getClientIp(); $country = $request->headers->get('X-Country', 'UNKNOWN'); ! return new Response($ip . ' => '. $country, 200); }); ! $stack = (new Stack\Builder()) ->push('Geocoder\Stack\GeoIp'); ! $app = $stack->resolve($app);
108. $app = new Silex\Application(); ! $app->get('/', function(Request $request) { $ip = $request->getClientIp(); $country = $request->headers->get('X-Country', 'UNKNOWN'); ! return new Response($ip . ' => '. $country, 200); }); ! $blockAllButUs = function (HKI $app, $request) { if ($request->headers->get('X-Country') != 'US') { return new RedirectResponse('http://google.com); } return $app->handle($request); }; ! $stack = (new Stack\Builder()) ->push('Geocoder\Stack\GeoIp') ->push('Stack\Inline', $blockAllButUs); ! $app = $stack->resolve($app);
109. Backstage (maintenance pages)
110. class Backstage implements HKI { public function __construct(HKI $app, $path) { $this->app = $app; $this->path = $path; } ! public function handle($request) { $path = realpath($this->path); ! if (false !== $path) { return new Response(file_get_contents($path), 503); } ! return $this->app->handle($request); } }
111. $app = new Silex\Application(); ! $app->get('/', function () { return 'my app is working'; }); ! $stack = (new Stack\Builder()) ->push('Atst\StackBackstage', __DIR__.'/maintenance.html'); ! $app = $stack->resolve($app);
112. $ echo "<h1>Down for Maintenance</h1>" > /path/to/your/app/maintenance.html ! # do your thang ! $ rm /path/to/your/app/maintenance.html
113. So many more middlewares...
114. • HTTP Cache • CookieGuard • GeoIp • IpRestrict • Backstage • OAuth • Basic Authentication • Hawk • CORS • Robots • Negotiation • Honeypot • Logger • ... and more
115. Stack Conventions
116. STACK-0 Proposals Draft
117. STACK-0 Proposals Draft rfc.zeromq.org
118. Stack-0 Proposals • MUST look like STACK-{NUMBER}. • MUST have a descriptive name. Good old RFC 2119...
119. STACK-1 Core Draft
120. Stack-1 Core • Middlewares MUST implement the HttpKernelInterface. • Middlewares MAY delegate to the decorated HttpKernelInterface. • Middlewares MUST take an HttpKernelInterface as its first constructor argument. Good old RFC 2119...
121. WIP Stack-1 Core • Middlewares MUST implement the HttpKernelInterface. • Middlewares MAY delegate to the decorated HttpKernelInterface. • Middlewares MUST take an HttpKernelInterface as its first constructor argument. Good old RFC 2119...
122. STACK-2 Authentication Draft
123. stack.authn.token (string or serializable)
124. 401 Unauthorized WWW-Authenticate: Stack
125. dflydev/stack-authentication A collection of Stack middlewares designed to help authentication middleware implementors adhere to the STACK-2 Authentication conventions.
126. STACK-3 Authorization Draft
127. stack.authn.token
128. 401 Unauthorized WWW-Authenticate: Stack
129. 403 Forbidden
130. The Future!
131. [this page intentionally left blank]
132. Stack is NOT a library
133. Stack is NOT a framework
134. Stack is a convention for composing HttpKernelInterface middlewares
135. ... and more!
136. Questions? @beausimensen +BeauSimensen https://beau.io/talks/ dflydev.com
137. [this page intentionally left blank]
138. @igorwhiletrue @beausimensen @hochchristoph (plus many others!)