Hello, PSR-7. (phpwarks 2016)

PSR-7 HTTP Message Interface has been kicking around in one form or another since March of 2012. Get a brief history of how PSR-7 evolved from its humble beginnings as a simple HTTP client interface to the game-changing PHP-FIG proposal we have today. Learn how to work with the HTTP Message Interfaces and how they will be used by frameworks in the not to distant future. Find out what it will mean to have a healthy ecosystem of PHP software all speak HTTP the same way. Say hello to your new best friend in PHP, PSR-7.

Transcript

1. Hello, PSR-7. joind.in/talk/aef0a Beau Simensen beau.io • @beausimensen
2. PSR-7 HTTP Message Interface
3. The Problem Server-Side Edition
4. My background (It is relevant, I promise!)
5. PHP ~2005
6. Spring Framework ~2008
7. class halo_HttpRequest { public function __construct( $method, array $queryParams = null, array $postParams = null, array $fileData = null, array $env = null, $body = null ) { // ... } }
8. class halo_DispatcherUtil { public static function MAKE_HTTP_REQUEST() { return new halo_HttpRequest( $_SERVER['REQUEST_METHOD'], $_GET, $_POST, $_FILES, $_SERVER ); } }
9. namespace Symfony\Component\HttpFoundation; class Request { public function __construct( array $query = array(), array $request = array(), array $attributes = array(), array $cookies = array(), array $files = array(), array $server = array(), $content = null ) { // ... } }
10. namespace Symfony\Component\HttpFoundation; class Request { public static function createFromGlobals() { return self::createRequestFromFactory( $_GET, $_POST, array(), $_COOKIE, $_FILES, $server ); } }
11. namespace Zend\Http\PhpEnvironment; class Request extends \Zend\Http\Request { public function __construct() { $this->setEnv(new Parameters($_ENV)); if ($_GET) { $this->setQuery(new Parameters($_GET)); } if ($_POST) { $this->setPost(new Parameters($_POST)); } if ($_COOKIE) { $this->setCookies(new Parameters($_COOKIE)); } if ($_FILES) { $files = $this->mapPhpFiles(); $this->setFiles(new Parameters($files)); } $this->setServer(new Parameters($_SERVER)); } }
12. namespace Aura\Web; class WebFactory { public function newRequest() { return new Request( $this->newRequestClient(), $this->newRequestContent(), $this->newRequestGlobals(), $this->newRequestHeaders(), $this->newRequestMethod(), $this->newRequestParams(), $this->newRequestUrl() ); } public function newRequestGlobals() { return new Request\Globals( $this->newRequestCookies(), $this->newRequestEnv(), $this->newRequestFiles(), $this->newRequestPost(), $this->newRequestQuery(), $this->newRequestServer() ); } }
13. All define similar Responses
14. Abstractions over SAPI
15. Impact on Ecosystem
16. Symfony 2 HttpFoundation + HttpKernel
18. What if we could share code between these applications and frameworks at the HTTP level? — Igor, Beau, and Christoph
19. Stack PHP Conventions for writing framework agnostic* middleware stackphp.com
20. Framework agnostic my foot. — Imagined People
23. The Problem Client-Side Edition
24. Guzzle, Buzz, Requests
26. The Problem for both server-side and client-side: HTTP Messages abstraction should be a commodity <message line> Header: value Another-Header: value Message body
28. History of PSR-7
29. PHP-FIG PHP Framework Interoperability Group
31. March 24th, 2012 HTTP Client interface Benjamin Eberlei
32. $client = create_http_client(); // implementation specific $response = $client->request('GET', 'http://www.php.net'); if ($response->getStatusCode() == 200) { $content = $response->getContent(); } $response = $client->request('GET', 'http://api/returning.json'); if ($response->getContentType() == 'application/json') { $json = json_decode($response->getContent()); }
33. December 31st, 2012 HTTP Message Chris Wilkinson
34. There was a proposal to create a HTTP client interface earlier this year. As was noted at the time, the core HTTP message representation part (ie the request/response objects) is probably of more importance: it's used by both HTTP clients and frameworks. — Chris Wilkinson
35. interface MessageInterface { public function __toString(); public function getStartLine(); public function getProtocolVersion(); public function setProtocolVersion($protocolVersion); public function getHeader($header); public function getHeaders(); public function hasHeader($header); public function setHeader($header, $value); public function setHeaders(array $headers); public function addHeaders(array $headers); public function getBody(); public function setBody($body); }
36. interface RequestInterface extends MessageInterface { public function __construct( $method, $url, $protocolVersion = '1.1' ); public function getResponse(); public function setResponse(ResponseInterface $response); public function getMethod(); public function setMethod($method); public function getUrl(); public function setUrl($url); }
37. interface ResponseInterface extends MessageInterface { public function __construct( $statusCode, $reasonPhrase = null, $protocolVersion = '1.1' ); public function getRequest(); public function setRequest(RequestInterface $request); public function getStatusCode(); public function setStatusCode($statusCode); public function getReasonPhrase(); public function setReasonPhrase($reasonPhrase); }
38. January 28th, 2014 PSR-7 HTTP Message - DRAFT Michael Dowling
39. August 29th, 2014 PSR-7 HTTP Message - Retracted Michael Dowling
40. Matthew Weier O'Phinney
41. phly/http http://github.com/phly/http (similar to node's http.Server)
42. phly/conduit http://github.com/phly/conduit (a port of Sencha Connect)
43. September 26th, 2014 PSR-7 HTTP Message Interfaces Matthew Weier O'Phinney
44. accepted May 18th, 2015
46. Interfaces & Concepts
48. Bloated?
50. Immutability Messages and URIs are modeled as value objects
51. class Request implements RequestInterface { public function withMethod($method) { $new = clone $this; $new->method = $method; return $new; } }
52. use Zend\Diactoros\Request; use Zend\Diactoros\Uri; $request = (new Request()) ->withUri(new Uri('http://example.com')) ->withMethod('GET');
53. use Zend\Diactoros\Request; use Zend\Diactoros\Uri; $request = (new Request()) ->withUri(new Uri('http://example.com')) ->withMethod('GET'); // this does nothing to $request. $request->withAddedHeader( 'Content-Type', 'application/json' );
54. use Zend\Diactoros\Request; use Zend\Diactoros\Uri; $request = (new Request()) ->withUri(new Uri('http://example.com')) ->withMethod('GET'); // this is probably what you want. $request = $request->withAddedHeader( 'Content-Type', 'application/json' );
55. It will take some getting used to, but just try it. — Me
56. As somebody who implemented the interfaces, I was able to literally rip out huge swathes of defensive code, as state checks became unnecessary. — Matthew Weier O'Phinney
57. Streams cannot be immutable. :(
58. Streams Message Bodies & Uploaded Files
59. Allows implementations to work with large message bodies
60. Strings? php://memory or php://temp $message = $message->withBody(new Stream('php://temp')); $message->getBody()->write('This is my content!');
61. REMEMBER Immutability cannot be enforced! Use read-only streams for server-side requests and client-side responses
62. Messages
63. <message line> Header: value Another-Header: value Message body
64. Headers
65. $message = $message ->withHeader('foo', 'bar') ->withAddedHeader('foo', 'baz'); if ($message->hasHeader('Accept')) { /* ... */ } // 'bar, baz' $header = $message->getHeaderLine('foo'); // ['bar', 'baz'] $header = $message->getHeader('foo'); // [ 'foo' => ['bar', 'baz'] ] foreach ($message->getHeaders() as $header => $values) { }
66. Host header Calling $request->withUri() updates Host header Unless you pass true to $preserveHost
67. Requests
68. URI // https://api.example.com $uri = $uri->withScheme('https')->withHost('api.example.com'); $usersUri = $uri->withPath('/v2/users'); $booksUri = $uri->withPath('/v2/books'); // https://api.example.com/v2/users?limit=10 $getUsersRequest = (new Request()) ->withMethod('GET') ->withUri($usersUri->withQuery('?limit=10')); // https://api.example.com/v2/users $postUsersRequest = (new Request()) ->withMethod('POST') ->withUri($usersUri); // https://api.example.com/v2/books $getBooksRequest = (new Request()) ->withMethod('GET') ->withUri($booksUri);
69. Server Requests
70. CGI + SAPI $_COOKIE • $_GET • $_POST • $_FILES • $_SERVER
71. Attributes
72. $country = $this->resolveCountryForRequest($request); if ($country) { $request = $request->withAttribute( 'geocode.country', $country ); } // ... $country = $request->getAttribute('geocode.country'); if ($country) { // }
73. Uploaded Files
74. Given file input names files[0] and files[1] What you might expect: [ 'files' => [ 0 => [ 'name' => 'file0.txt', 'type' => 'text/plain', /* etc. */ ], 1 => [ 'name' => 'file1.html', 'type' => 'text/html', /* etc. */ ], ], ];
75. Given file input names files[0] and files[1] What you actually get: [ 'files' => [ 'name' => [ 0 => 'file0.txt', 1 => 'file1.html', ], 'type' => [ 0 => 'text/plain', 1 => 'text/html', ], /* etc. */ ], ]
76. PSR-7 enforces a normalized $_FILES
77. $file0 = $request->getUploadedFiles()['files'][0]; $file1 = $request->getUploadedFiles()['files'][1]; printf( "Received the files %s and %s", $file0->getClientFilename(), $file1->getClientFilename() ); // "Received the files file0.txt and file1.html"
78. Underlying "filename" is protected // Move a file to an upload directory $filename = sprintf( '%s.%s', create_uuid(), pathinfo($file0->getClientFilename(), PATHINFO_EXTENSION) ); $file0->moveTo(DATA_DIR . '/' . $filename); // Stream a file to Amazon S3. // Assume $s3wrapper is a PHP stream that will write to S3, and that // Psr7StreamWrapper is a class that will decorate a StreamInterface as a PHP // StreamWrapper. $stream = new Psr7StreamWrapper($file1->getStream()); stream_copy_to_stream($stream, $s3wrapper);
79. Parsed Body
80. application/x-www-form-urlencoded multipart/form-data $_POST
81. function ($request, $response, $next) { $contentType = $request->getHeaderLine('Content-Type'); if ('application/json' === $contentType) { $json = json_decode($request->getBody(), true); $request = $request->withParsedBody($json); } return $next( $request, $response ); }
82. Middleware In the wild today
83. function ($request, $response, $next) { return $next( $request, $response ); }
84. function ($request, $response, $next) { $response = $next( $request, $response ); return $response->withAddedHeader( 'X-Clacks-Overhead', 'GNU Terry Pratchett' ); }
85. namespace Acme; class ClacksOverhead { public function __invoke($request, $response, $next) { $response = $next( $request, $response ); return $response->withAddedHeader( 'X-Clacks-Overhead', 'GNU Terry Pratchett' ); } }
86. Stratigility use Zend\Stratigility\MiddlewarePipe; $app = new MiddlewarePipe(); // ... $app->pipe(new \Acme\ClacksOverhead()); // ...
87. Relay use Relay\RelayBuilder; $relayBuilder = new RelayBuilder(); $relay = $relayBuilder->newInstance([ // ... new \Acme\ClacksOverhead(), // ... ]); $response = $relay($request, $response);
89. Framework Agnostic HTTP Libraries
90. What do we want? Re-use at the web layer! — http://stackphp.com
91. What about cookies? — people
92. dflydev/fig-cookies
93. use Dflydev\FigCookies\FigRequestCookies; // Assume this header is set on $request // Cookie: theme=red; foo=bar $cookie = FigRequestCookies::get($request, 'theme'); $cookie->getValue(); // "red" $request = FigRequestCookies::set($request, $cookie->withValue('blue')); $request = FigRequestCookies::set($request, Cookie::create('name', 'beau')); $request = FigRequestCookies::remove($request, 'foo'); // The $request now has the following header: // Cookie: theme=blue; name=beau
94. dflydev/encrypted-fig-cookies WIP
95. class EncryptedFigCookiesMiddleware { public function __invoke( RequestInterface $request, ResponseInterface $response, callable $next ) { $request = $this->requestCookieDecryptor->decrypt( $request, $this->cookieNames ); $response = $next($request, $response); return $this->responseCookieEncryptor->encrypt( $response, $this->cookieNames ); } }
97. Frameworks
98. Slim 3 www.slimframework.com First previously existing framework that intended to implement native support PSR-7
99. Zend Expressive github.com/zendframework/zend-expressive Builds on Stratigility to provide a minimalist PSR-7 middleware framework for PHP
100. Radar github.com/radarphp Radar is a PSR-7 compliant Action-Domain-Responder (ADR) system
101. Nimble monii/nimble-framework A light PSR-7 framework built on top of Laravel's Container, nikic/fast- route, and Relay WIP
102. Rolling your own PSR-7 microframework...
103. (middleware in the real world)
104. NikicFastRoute monii/nikic-fast-route-psr7-middleware WIP
105. There were at least two other existing nikic/fast-route middleware implementations jowy/routing-middleware & oscarotero/psr7-middlewares
106. class NikicFastRoute { public function __invoke($request, $response, $next) { $routeInfo = $this->dispatcher->dispatch( $request->getMethod(), $request->getUri()->getPath() ); } }
107. class NikicFastRoute { public function __invoke($request, $response, $next) { $routeInfo = $this->dispatcher->dispatch( $request->getMethod(), $request->getUri()->getPath() ); switch ($routeInfo[0]) { case FastRoute\Dispatcher::NOT_FOUND: return $response->withStatus(404); } } }
108. class NikicFastRoute { public function __invoke($request, $response, $next) { $routeInfo = $this->dispatcher->dispatch( $request->getMethod(), $request->getUri()->getPath() ); switch ($routeInfo[0]) { case FastRoute\Dispatcher::NOT_FOUND: return $response->withStatus(404); case FastRoute\Dispatcher::METHOD_NOT_ALLOWED: return $response->withStatus(405); } } }
109. class NikicFastRoute { public function __invoke($request, $response, $next) { $routeInfo = $this->dispatcher->dispatch( $request->getMethod(), $request->getUri()->getPath() ); switch ($routeInfo[0]) { case FastRoute\Dispatcher::NOT_FOUND: return $response->withStatus(404); case FastRoute\Dispatcher::METHOD_NOT_ALLOWED: return $response->withStatus(405); case FastRoute\Dispatcher::FOUND: $action = $routeInfo[1]; $parameters = $routeInfo[2]; $request = $request ->withAttribute('action', $action) ->withAttribute('parameters', $parameters) ; return $next($request, $response, $next); } } }
110. class NikicFastRoute { public function __invoke($request, $response, $next) { $routeInfo = $this->dispatcher->dispatch( $request->getMethod(), $request->getUri()->getPath() ); switch ($routeInfo[0]) { case FastRoute\Dispatcher::NOT_FOUND: return $response->withStatus(404); case FastRoute\Dispatcher::METHOD_NOT_ALLOWED: return $response->withStatus(405); case FastRoute\Dispatcher::FOUND: $action = $routeInfo[1]; $parameters = $routeInfo[2]; $request = $request ->withAttribute('action', $action) ->withAttribute('parameters', $parameters) ; return $next($request, $response, $next); default: return $response->withStatus(500); } } }
111. ActionHandler monii/action-handler-psr7-middleware WIP
112. class ActionHandler { public function __construct(ActionHandlerResolver $actionResolver) { $this->actionResolver = $actionResolver; } function __invoke($request, $response, $next) { $action = $request->getAttribute('action'); if (is_null($action)) { throw new \RuntimeException('No action specified for request.'); } $handler = $this->actionResolver->resolve($action); return $handler($request, $response, $next); } }
113. $container->bind(Relay::class, function (Container $container) { $relayBuilder = $container->make(RelayBuilder::class); return $relayBuilder->newInstance([ $container->make(NikicFastRoute::class), // ... other middleware $container->make(ActionHandler::class), ]); }); $relay = $container->make(Relay::class); $response = $relay( $container->make(ServerRequestInterface::class), $container->make(ResponseInterface::class) ); send_response($response);
114. More Middleware In the real world.
117. Managed Technical Debt Making a distinction between Managed and Unmanaged Technical Debt. http://verraes.net/2013/07/managed-technical-debt/
118. class CorsCompletelyOpenForDevelopment { public function __invoke($request, $response, callable $next) { /** @var ResponseInterface $response */ $response = $next($request, $response); if ($response->hasHeader('Access-Control-Allow-Origin')) { // If the response already has an expected header we will // assume that CORS has been handled successfully. return $response; } // This is unsafe and not what people will want in production // unless they really know what they are doing. return $response ->withHeader('Access-Control-Allow-Origin', '*') ->withHeader( 'X-Completely-Open-Cors-For-Development', 'unsafe' ) ; } }
119. $container->bind(Relay::class, function (Container $container) { $relayBuilder = $container->make(RelayBuilder::class); return $relayBuilder->newInstance([ $container->make(NikicFastRoute::class), // ... other middleware $container->make(ActionHandler::class), ]); });
120. $container->bind(Relay::class, function (Container $container) { $relayBuilder = $container->make(RelayBuilder::class); return $relayBuilder->newInstance([ $container->make(NikicFastRoute::class), $container->make(CorsCompletelyOpenForDevelopment::class), // ... other middleware $container->make(ActionHandler::class), ]); });
121. Quick Win
122. Minimal Impact
124. neomerx/cors-psr7 https://github.com/neomerx/cors-psr7 Managed technical debt paid off by someone else!
126. Server, Middleware, and Client interfaces are missing Some of us are still working on that...
127. Problem: No standard way to write PSR-7 middleware.
128. PSR-15 HTTP Middleware
129. PSR-7 + PSR-15 = Stack's Vision. Realized.
130. Problem: In many cases it is hard to write PSR-7 code that is not tied to an implementation.
131. PSR-17 HTTP Factories
132. With PSR-7, PSR-15 and PSR-17 combined we can truly start writing Framework Agnostic HTTP applications.
134. Implementations zend/diactoros (phly/http), Slim, Guzzle, phpixie/http
135. Want to start using PSR-7 today in your existing Symfony, Laravel, Lumen, or Drupal 8 app?
137. Symfony Bridge https://github.com/symfony/psr-http-message-bridge
139. Thanks! joind.in/talk/aef0a beau.io • @beausimensen monii.io • @moniidev thatpodcast.io • @thatpodcast