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

Download PSR-7_ HTTP Message Meta Document - PHP-FIG

Post on 01-Mar-2018




0 download

Embed Size (px)


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


    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:

    RFC 7231:

    RFC 3986:

    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

    22 19/06/2016 0

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


    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

    22 19/06/2016 0

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


    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


    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


    Projectsuse PHP'ssuperglobalsdirectly.1.

    Projectswill create implementationsfrom scratch.2.

    Projectsmay require a specific HTTP client/serverlibrary that provides

    HTTP message implementations.


    Projectsmay create adaptersforcommon HTTP message4.

    7: HTTP Message Meta Document - PHP-FIG

    22 19/06/2016 0

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




    Just about any application that began development before the rise of

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


    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



    Projectssuch asSilex, Stack, andDrupal 8have harddependencieson

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

    on Guzzle'sHTTP message implementations.


    Projectssuch asGeocodercreate redundant adaptersforcommon



    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


    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

    22 19/06/2016 0

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


    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


    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


    4. Scope


    Provide the interfacesneededfordescribing HTTP messages.

    Focuson practical applicationsandusability.

    Define the interfacesto model all elementsof the HTTP message andURI


    7: HTTP Message Meta Document - PHP-FIG

    22 19/06/2016 0

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


    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



    Thisproposal doesnot expect all HTTP client librariesorserver-side

    frameworksto change theirinterfacesto conform. It isstrictly meant for


    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


    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

    22 19/06/2016 0

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


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

    are partly inspiredby existing PHP usage, but also by otherlanguagessuch