psr-7_ http message meta document - php-fig

7/25/2019 PSR-7_HTTP Message Meta Document - PHP-FIG

1/22

PHP-FIGHomeRecommendations (PSRs)MembersBylawsFAQsGet InvolvedPSR-7:HTTP Message Meta DocumentPSR-7:HTTP Message Meta Document

1. Summary

The purpose of thisproposal isto provide a set of common interfacesfor

HTTP messagesasdescribedin RFC 7230andRFC 7231, andURIsasdescribed

in RFC 3986(in the context of HTTP messages).

RFC 7230: http://www.ietf.org/rfc/rfc7230.txt

RFC 7231: http://www.ietf.org/rfc/rfc7231.txt

RFC 3986: http://www.ietf.org/rfc/rfc3986.txt

All HTTP messagesconsist of the HTTP protocol version being used, headers,

anda message body. A Requestbuildson the message to include the HTTPmethodusedto make the request, andthe URIto which the request ismade.

A Responseincludesthe HTTP statuscode andreason phrase.

In PHP, HTTP messagesare usedin two contexts:

To sendan HTTP request, via the ext/curl extension, PHP'snative stream

layer, etc., andprocessthe receivedHTTP response. In otherwords, HTTPmessagesare usedwhen using PHP asan HTTP client.

To processan incoming HTTP request to the server, andreturn an HTTP

response to the client making the request. PHP can use HTTP messages

when usedasa server-side applicationto fulfill HTTP requests.

Thisproposal presentsan APIforfully describing all partsof the variousHTTP

7: HTTP Message Meta Document - PHP-FIG http://www.php-fig.org/psr/ps

22 19/06/2016 0

7/25/2019 PSR-7_HTTP Message Meta Document - PHP-FIG

2/22

messageswithin PHP.

2. HTTP Messagesin PHP

PHP doesnot have built-in support forHTTP messages.

Client-side HTTP support

PHP supportssending HTTP requestsvia several mechanisms:

PHP streams

The cURL extension

ext/http(v2also attemptsto addressserver-side support)

PHP streamsare the most convenient andubiquitousway to sendHTTP

requests, but pose a numberof limitationswith regardsto properly

configuring SSL support, andprovide a cumbersome interface aroundsetting

thingssuch asheaders. cURL providesa complete andexpandedfeature-set,

but, asit isnot a default extension, isoften not present. The http extension

suffersfrom the same problem ascURL, aswell asthe fact that it has

traditionally hadfarfewerexamplesof usage.

Most modern HTTP client librariestendto abstract the implementation, to

ensure they can work on whateverenvironment they are executedon, and

acrossany of the above layers.

Server-side HTTP Support

PHP usesServerAPIs(SAPI) to interpret incoming HTTP requests, marshal

input, andpassoff handling to scripts. The original SAPIdesign mirrored

Common Gateway Interface, which wouldmarshal request data andpush it

7: HTTP Message Meta Document - PHP-FIG http://www.php-fig.org/psr/ps

22 19/06/2016 0

7/25/2019 PSR-7_HTTP Message Meta Document - PHP-FIG

3/22

into environment variablesbefore passing delegation to a script; the script

wouldthen pull from the environment variablesin orderto processthe

request andreturn a response.

PHP'sSAPIdesign abstractscommon input sourcessuch ascookies, query

string arguments, andurl-encodedPOST content via superglobals( $_COOKIE ,

$_GET , and $_POST , respectively), providing a layerof convenience forweb

developers.

On the response side of the equation, PHP wasoriginally developedasa

templating language, andallowsintermixing HTML andPHP; any HTML

portionsof a file are immediately flushedto the output buffer. Modernapplicationsandframeworkseschewthispractice, asit can leadto issues

with regardsto emitting a statusline and/orresponse headers; they tendto

aggregate all headersandcontent, andemit them at once when all other

application processing iscomplete. Special care needsto be paidto ensure

that errorreporting andotheractionsthat sendcontent to the output buffer

do not flush the output buffer.

3. Why Bother?

HTTP messagesare usedin a wide numberof PHP projects-- both clientsand

servers. In each case, we observe one ormore of the following patternsor

situations:

Projectsuse PHP'ssuperglobalsdirectly.1.

Projectswill create implementationsfrom scratch.2.

Projectsmay require a specific HTTP client/serverlibrary that provides

HTTP message implementations.

3.

Projectsmay create adaptersforcommon HTTP message4.

7: HTTP Message Meta Document - PHP-FIG http://www.php-fig.org/psr/ps

22 19/06/2016 0

7/25/2019 PSR-7_HTTP Message Meta Document - PHP-FIG

4/22

implementations.

Asexamples:

Just about any application that began development before the rise of

frameworks, which includesa numberof very popularCMS, forum, andshopping cart systems, have historically usedsuperglobals.

1.

Frameworkssuch asSymfony andZendFramework each define HTTP

componentsthat form the basisof theirMVC layers; even small, single-

purpose librariessuch asoauth2-server-php provide andrequire their

own HTTP request/response implementations. Guzzle, Buzz, andother

HTTP client implementationseach create theirown HTTP message

implementationsaswell.

2.

Projectssuch asSilex, Stack, andDrupal 8have harddependencieson

Symfony'sHTTP kernel. Any SDK built on Guzzle hasa hardrequirement

on Guzzle'sHTTP message implementations.

3.

Projectssuch asGeocodercreate redundant adaptersforcommon

libraries.

4.

Direct usage of superglobalshasa numberof concerns. First, these are

mutable, which makesit possible forlibrariesandcode to alterthe values,

andthusalterstate forthe application. Additionally, superglobalsmake unit

andintegration testing difficult andbrittle, leading to code quality

degradation.

In the current ecosystem of frameworksthat implement HTTP messageabstractions, the net result isthat projectsare not capable of interoperability

orcross-pollination. In orderto consume code targeting one framework from

another, the first orderof businessisbuilding a bridge layerbetween the

HTTP message implementations. On the client-side, if a particularlibrary

doesnot have an adapteryoucan utilize, youneedto bridge the

7: HTTP Message Meta Document - PHP-FIG http://www.php-fig.org/psr/ps

22 19/06/2016 0

7/25/2019 PSR-7_HTTP Message Meta Document - PHP-FIG

5/22

request/response pairsif youwish to use an adapterfrom anotherlibrary.

Finally, when it comesto server-side responses, PHP getsin itsown way: any

content emittedbefore a call to header() will result in that call becoming a

no-op; depending on errorreporting settings, thiscan often mean headers

and/orresponse statusare not correctly sent. One way to work aroundthisis

to use PHP'soutput buffering features, but nesting of output bufferscan

become problematic anddifficult to debug. Frameworksandapplications

thustendto create response abstractionsforaggregating headersand

content that can be emittedat once - andthese abstractionsare often

incompatible.

Thus, the goal of thisproposal isto abstract both client- andserver-side

request andresponse interfacesin orderto promote interoperability between

projects. If projectsimplement these interfaces, a reasonable level of

compatibility may be assumedwhen adopting code from different libraries.

It shouldbe notedthat the goal of thisproposal isnot to obsolete the current

interfacesutilizedby existing PHP libraries. Thisproposal isaimedat

interoperability between PHP packagesforthe purpose of describing HTTP

messages.

4. Scope

4.1Goals

Provide the interfacesneededfordescribing HTTP messages.

Focuson practical applicationsandusability.

Define the interfacesto model all elementsof the HTTP message andURI

specifications.

7: HTTP Message Meta Document - PHP-FIG http://www.php-fig.org/psr/ps

22 19/06/2016 0

7/25/2019 PSR-7_HTTP Message Meta Document - PHP-FIG

6/22

Ensure that the APIdoesnot impose arbitrary limitson HTTP messages.

Forexample, some HTTP message bodiescan be too large to store in

memory, so we must account forthis.

Provide useful abstractionsboth forhandling incoming requestsfor

server-side applicationsandforsending outgoing requestsin HTTP

clients.

4.2Non-Goals

Thisproposal doesnot expect all HTTP client librariesorserver-side

frameworksto change theirinterfacesto conform. It isstrictly meant for

interoperability.

While everyone'sperception of what isandisnot an implementation

detail varies, thisproposal shouldnot impose implementation details. As

RFCs7230, 7231, and3986do not force any particularimplementation,

there will be a certain amount of invention neededto describe HTTP

message interfacesin PHP.

5. Design Decisions

Message design

The MessageInterface providesaccessorsforthe elementscommon to all

HTTP messages, whetherthey are forrequestsorresponses. These elements

include:

HTTP protocol version (e.g., "1.0", "1.1")

HTTP headers

HTTP message body

More specific interfacesare usedto describe requestsandresponses, and

7: HTTP Message Meta Document - PHP-FIG http://www.php-fig.org/psr/ps

22 19/06/2016 0

7/25/2019 PSR-7_HTTP Message Meta Document - PHP-FIG

7/22

more specifically the context of each (client- vs. server-side). These divisions

are partly inspiredby existing PHP usage, but also by otherlanguagessuch