Hello, PSR-7. (PHP Benelux 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/58c66 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
24. The Problem Client-Side Edition
25. Guzzle, Buzz, Requests
27. 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
29. History of PSR-7
30. PHP-FIG PHP Framework Interoperability Group
32. March 24th, 2012 HTTP Client interface Benjamin Eberlei
33. $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()); }
34. December 31st, 2012 HTTP Message Chris Wilkinson
35. 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
36. 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); }
37. 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); }
38. 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); }
39. January 28th, 2014 PSR-7 HTTP Message - DRAFT Michael Dowling
40. August 29th, 2014 PSR-7 HTTP Message - Retracted Michael Dowling
41. Matthew Weier O'Phinney
42. phly/http http://github.com/phly/http (similar to node's http.Server)
43. phly/conduit http://github.com/phly/conduit (a port of Sencha Connect)
44. September 26th, 2014 PSR-7 HTTP Message Interfaces Matthew Weier O'Phinney
45. accepted May 18th, 2015
47. Interfaces & Concepts
49. Bloated?
51. Immutability Messages and URIs are modeled as value objects
52. class Request implements RequestInterface { public function withMethod($method) { $new = clone $this; $new->method = $method; return $new; } }
53. use Zend\Diactoros\Request; use Zend\Diactoros\Uri; $request = (new Request()) ->withUri(new Uri('http://example.com')) ->withMethod('GET');
54. 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' );
55. 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' );
56. It will take some getting used to, but just try it. — Me
57. 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
58. Streams cannot be immutable. :(
59. Streams Message Bodies & Uploaded Files
60. Allows implementations to work with large message bodies
61. Strings? php://memory or php://temp $message = $message->withBody(new Stream('php://temp')); $message->getBody()->write('This is my content!');
62. REMEMBER Immutability cannot be enforced! Use read-only streams for server-side requests and client-side responses
63. Messages
64. <message line> Header: value Another-Header: value Message body
65. Headers
66. $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) { }
67. Host header Calling $request->withUri() updates Host header Unless you pass true to $preserveHost
68. Requests
69. 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);
70. Server Requests
71. CGI + SAPI $_COOKIE • $_GET • $_POST • $_FILES • $_SERVER
72. Attributes
73. $country = $this->resolveCountryForRequest($request); if ($country) { $request = $request->withAttribute( 'geocode.country', $country ); } // ... $country = $request->getAttribute('geocode.country'); if ($country) { // }
74. Uploaded Files
75. 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. */ ], ], ];
76. 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. */ ], ]
77. PSR-7 enforces a normalized $_FILES
78. $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"
79. 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);
80. Parsed Body
81. application/x-www-form-urlencoded multipart/form-data $_POST
82. 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 ); }
83. Middleware
84. function ($request, $response, $next) { return $next( $request, $response ); }
85. function ($request, $response, $next) { $response = $next( $request, $response ); return $response->withAddedHeader( 'X-Clacks-Overhead', 'GNU Terry Pratchett' ); }
86. namespace Acme; class ClacksOverhead { public function __invoke($request, $response, $next) { $response = $next( $request, $response ); return $response->withAddedHeader( 'X-Clacks-Overhead', 'GNU Terry Pratchett' ); } }
87. Stratigility use Zend\Stratigility\MiddlewarePipe; $app = new MiddlewarePipe(); // ... $app->pipe(new \Acme\ClacksOverhead()); // ...
88. Relay use Relay\RelayBuilder; $relayBuilder = new RelayBuilder(); $relay = $relayBuilder->newInstance([ // ... new \Acme\ClacksOverhead(), // ... ]); $response = $relay($request, $response);
90. Framework Agnostic HTTP Libraries
91. What do we want? Re-use at the web layer! — http://stackphp.com
92. What about cookies? — people
93. dflydev/fig-cookies
94. 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
95. dflydev/encrypted-fig-cookies WIP
96. 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 ); } }
98. Frameworks
99. Slim 3 www.slimframework.com First previously existing framework that intended to implement native support PSR-7
100. Zend Expressive github.com/zendframework/zend-expressive Builds on Stratigility to provide a minimalist PSR-7 middleware framework for PHP
101. Radar github.com/radarphp Radar is a PSR-7 compliant Action-Domain-Responder (ADR) system
102. Nimble monii/nimble-framework A light PSR-7 framework built on top of Laravel's Container, nikic/fast-route, and Relay WIP
103. Rolling your own PSR-7 microframework...
104. (middleware in the real world)
105. NikicFastRoute monii/nikic-fast-route-psr7-middleware WIP
106. There were at least two other existing nikic/fast-route middleware implementations jowy/routing-middleware & oscarotero/psr7-middlewares
107. class NikicFastRoute { public function __invoke($request, $response, $next) { $routeInfo = $this->dispatcher->dispatch( $request->getMethod(), $request->getUri()->getPath() ); } }
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); } } }
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); } } }
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); } } }
111. 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); } } }
112. ActionHandler monii/action-handler-psr7-middleware WIP
113. 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); } }
114. $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);
115. More Middleware In the real world.
118. Managed Technical Debt Making a distinction between Managed and Unmanaged Technical Debt. http://verraes.net/2013/07/managed-technical-debt/
119. 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' ) ; } }
120. $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), ]); });
121. $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), ]); });
122. Quick Win
123. Minimal Impact
125. neomerx/cors-psr7 https://github.com/neomerx/cors-psr7 Managed technical debt paid off by someone else!
127. Server, Middleware, and Client interfaces are missing Some of us are still working on that...
128. Implementations zend/diactoros (phly/http), Slim, Guzzle, phpixie/http
129. Want to start using PSR-7 today in your existing Symfony, Laravel, Lumen, or Drupal 8 app?
131. Symfony Bridge https://github.com/symfony/psr-http-message-bridge
133. Thanks! beau.io • @beausimensen monii.io • @moniidev thatpodcast.io • @thatpodcast joind.in/talk/58c66