psr-7_ http message interfaces - php-fig

7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG

1/55

PHP-FIGHomeRecommendations (PSRs)MembersBylawsFAQsGet InvolvedPSR-7:HTTP message interfacesPSR-7:HTTP message interfaces

Thisdocument describescommon interfacesforrepresenting HTTP

messagesasdescribedin RFC 7230andRFC 7231, andURIsforuse with HTTP

messagesasdescribedin RFC 3986.

HTTP messagesare the foundation of web development. Web browsersand

HTTP clientssuch ascURL create HTTP request messagesthat are sent to a

web server, which providesan HTTP response message. Server-side code

receivesan HTTP request message, andreturnsan HTTP response message.

HTTP messagesare typically abstractedfrom the end-userconsumer, but as

developers, we typically needto knowhowthey are structuredandhowto

accessormanipulate them in orderto perform ourtasks, whetherthat might

be making a request to an HTTP API, orhandling an incoming request.

Every HTTP request message hasa specific form:

ST/pathHTT /1.1

Host: example.com

foo=bar&baz=bat

The first line of a request isthe "request line", andcontains, in order, the

HTTP request method, the request target (usually eitheran absolute URIora

path on the web server), andthe HTTP protocol version. Thisisfollowedby

7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p

55 19/06/2016 0


2/55

one ormore HTTP headers, an empty line, andthe message body.

HTTP response messageshave a similarstructure:

HTT /1.1200 K

Content-Type: text/plain

This is the response body

The first line isthe "statusline", andcontains, in order, the HTTP protocol

version, the HTTP statuscode, anda "reason phrase," a human-readable

description of the statuscode. Like the request message, thisisthen followedby one ormore HTTP headers, an empty line, andthe message body.

The interfacesdescribedin thisdocument are abstractionsaroundHTTP

messagesandthe elementscomposing them.

The key words"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",

"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and"OPTIONAL" inthisdocument are to be interpretedasdescribedin RFC 2119.

References

RFC 2119

RFC 3986

RFC 7230

RFC 7231

1. Speci cation


55 19/06/2016 0


3/55

1.1Messages

An HTTP message iseithera request from a client to a serverora response

from a serverto a client. Thisspecification definesinterfacesforthe HTTP

messages Psr\Http\Message\RequestInterface and Psr\Http\Message

\ResponseInterface respectively.

Both Psr\Http\Message\RequestInterface and Psr\Http\Message

\ResponseInterface extend Psr\Http\Message\MessageInterface . While

Psr\Http\Message\MessageInterface MAY be implementeddirectly,

implementorsSHOULD implement Psr\Http\Message\RequestInterface and

Psr\Http\Message\ResponseInterface .

From here forward, the namespace Psr\Http\Message will be omittedwhen

referring to these interfaces.

1.2HTTP Headers

Case-insensitive headerfieldnames

HTTP messagesinclude case-insensitive headerfieldnames. Headersare

retrievedby name from classesimplementing the MessageInterface in a

case-insensitive manner. Forexample, retrieving the foo headerwill return

the same result asretrieving the FoO header. Similarly, setting the Foo

headerwill overwrite any previously set foo headervalue.

$message = $message->withHeader('foo', 'bar');

echo $message->getHeaderLine('foo');

// Outputs: bar

echo $message->getHeaderLine('FOO');


55 19/06/2016 0


4/55

// Outputs: bar

$message = $message->withHeader('fOO', 'baz');

echo $message->getHeaderLine('foo');

// Outputs: baz

Despite that headersmay be retrievedcase-insensitively, the original case

MUST be preservedby the implementation, in particularwhen retrievedwith

getHeaders() .

Non-conforming HTTP applicationsmay dependon a certain case, so it is

useful fora userto be able to dictate the case of the HTTP headerswhen

creating a request orresponse.

Headerswith multiple values

In orderto accommodate headerswith multiple valuesyet still provide the

convenience of working with headersasstrings, headerscan be retrieved

from an instance of a MessageInterface asan array ora string. Use the

getHeaderLine() methodto retrieve a headervalue asa string containing all

headervaluesof a case-insensitive headerby name concatenatedwith a

comma. Use getHeader() to retrieve an array of all the headervaluesfora

particularcase-insensitive headerby name.


55 19/06/2016 0


5/55

$message = $message

->withHeader('foo', 'bar')

->withAddedHeader('foo', 'baz');

$header = $message->getHeaderLine('foo');

// $header contains: 'bar, baz'

$header = $message->getHeader('foo');

// ['bar', 'baz']

Note: Not all headervaluescan be concatenatedusing a comma (e.g.,

Set-Cookie ). When working with such headers, consumersof

MessageInterface -basedclassesSHOULD rely on the getHeader() methodfor

retrieving such multi-valuedheaders.

Host header

In requests, the Host headertypically mirrorsthe host component of the URI,

aswell asthe host usedwhen establishing the TCP connection. However, the

HTTP specification allowsthe Host headerto differfrom each of the two.

During construction, implementationsMUST attempt to set the Host header

from a providedURIif no Host headerisprovided.

RequestInterface::withUri() will, by default, replace the returnedrequest's

Host headerwith a Host headermatching the host component of the passed

UriInterface .

Youcan opt-in to preserving the original state of the Host headerby passing

true forthe second( $preserveHost ) argument. When thisargument isset to

true , the returnedrequest will not update the Host headerof the returned

message -- unlessthe message containsno Host header.


55 19/06/2016 0


6/55

Thistable illustrateswhat getHeaderLine('Host') will return fora request

returnedby withUri() with the $preserveHost argument set to true for

variousinitial requestsandURIs.

REQUESTHOST

HEADER1

REQUESTHOST

COMPONENT2

URIHOST

COMPONENT3

RESULT

'' '' '' ''

'' foo.com '' foo.com

'' foo.com bar.com foo.com

foo.com '' bar.com foo.com

foo.com bar.com baz.com foo.com

1 Host headervalue priorto operation.

2Host component of the URIcomposedin the request priorto the

operation.

3Host component of the URIbeing injectedvia withUri() .

1.3Streams

HTTP messagesconsist of a start-line, headers, anda body. The body of an

HTTP message can be very small orextremely large. Attempting to represent

the body of a message asa string can easily consume more memory than

intendedbecause the body must be storedcompletely in memory.

Attempting to store the body of a request orresponse in memory would

preclude the use of that implementation from being able to work with large

message bodies. StreamInterface isusedin orderto hide the implementation

detailswhen a stream of data isreadfrom orwritten to. Forsituationswhere

a string wouldbe an appropriate message implementation, built-in streams

such as php://memory and php://temp may be used.


55 19/06/2016 0


7/55

StreamInterface exposesseveral methodsthat enable streamsto be read

from, written to, andtraversedeffectively.

Streamsexpose theircapabilitiesusing three methods: isReadable() ,

isWritable() , and isSeekable() . These methodscan be usedby stream

collaboratorsto determine if a stream iscapable of theirrequirements.

Each stream instance will have variouscapabilities: it can be read-only,

write-only, orread-write. It can also allowarbitrary random access(seeking

forwardsorbackwardsto any location), oronly sequential access(for

example in the case of a socket, pipe, orcallback-basedstream).

Finally, StreamInterface definesa __toString() methodto simplify retrieving

oremitting the entire body contentsat once.

Unlike the request andresponse interfaces, StreamInterface doesnot model

immutability. In situationswhere an actual PHP stream iswrapped,

immutability isimpossible to enforce, asany code that interactswith the

resource can potentially change itsstate (including cursorposition, contents,andmore). Ourrecommendation isthat implementationsuse read-only

streamsforserver-side requestsandclient-side responses. Consumers

shouldbe aware of the fact that the stream instance may be mutable, and, as

such, couldalterthe state of the message; when in doubt, create a new

stream instance andattach it to a message to enforce state.

1.4 Request TargetsandURIs

PerRFC 7230, request messagescontain a "request-target" asthe second

segment of the request line. The request target can be one of the following

forms:


55 19/06/2016 0


8/55

origin-form, which consistsof the path, and, if present, the query string;

thisisoften referredto asa relative URL. Messagesastransmittedover

TCP typically are of origin-form; scheme andauthority data are usually

only present via CGIvariables.

absolute-form, which consistsof the scheme, authority ("[user-

info@]host[:port]", where itemsin bracketsare optional), path (if

present), query string (if present), andfragment (if present). Thisisoften

referredto asan absolute URI, andisthe only form to specify a URIas

detailedin RFC 3986. Thisform iscommonly usedwhen making requests

to HTTP proxies.

authority-form, which consistsof the authority only. Thisistypically used

in CONNECT requestsonly, to establish a connection between an HTTPclient anda proxy server.

asterisk-form, which consistssolely of the string * , andwhich isused

with the OPTIONS methodto determine the general capabilitiesof a web

server.

Aside from these request-targets, there isoften an 'effective URL' which is

separate from the request target. The effective URL isnot transmittedwithinan HTTP message, but it isusedto determine the protocol (http/https), port

andhostname formaking the request.

The effective URL isrepresentedby UriInterface . UriInterface modelsHTTP

andHTTPS URIsasspecifiedin RFC 3986(the primary use case). The

interface providesmethodsforinteracting with the variousURIparts, which

will obviate the needforrepeatedparsing of the URI. It also specifiesa

__toString() methodforcasting the modeledURIto itsstring

representation.

When retrieving the request-target with getRequestTarget() , by default this

methodwill use the URIobject andextract all the necessary componentsto


55 19/06/2016 0


9/55

construct the origin-form. The origin-formisby farthe most common request-

target.

If it'sdesiredby an end-userto use one of the otherthree forms, orif the user

wantsto explicitly override the request-target, it ispossible to do so with

withRequestTarget() .

Calling thismethoddoesnot affect the URI, asit isreturnedfrom getUri() .

Forexample, a usermay want to make an asterisk-form request to a server:

$request = $request

->withMethod('OPTIONS')

->withRequestTarget('*')

->withUri(new Uri('https://example.org/'));

Thisexample may ultimately result in an HTTP request that lookslike this:

TI NS

*HTT /

1.1

But the HTTP client will be able to use the effective URL (from getUri() ), to

determine the protocol, hostname andTCP port.

An HTTP client MUST ignore the valuesof Uri::getPath() and

Uri::getQuery() , andinsteaduse the value returnedby getRequestTarget() ,

which defaultsto concatenating these two values.

Clientsthat choose to not implement 1ormore of the 4 request-target forms,

MUST still use getRequestTarget() . These clientsMUST reject request-targets

they do not support, andMUST NOT fall back on the valuesfrom getUri() .

RequestInterface providesmethodsforretrieving the request-target or


55 19/06/2016 0


10/55

creating a newinstance with the providedrequest-target. By default, if no

request-target isspecifically composedin the instance, getRequestTarget()

will return the origin-form of the composedURI(or"/" if no URIiscomposed).

withRequestTarget($requestTarget) createsa newinstance with the specified

request target, andthusallowsdevelopersto create request messagesthat

represent the otherthree request-target forms(absolute-form,

authority-form, andasterisk-form). When used, the composedURIinstance

can still be of use, particularly in clients, where it may be usedto create the

connection to the server.

1.5Server-side Requests

RequestInterface providesthe general representation of an HTTP request

message. However, server-side requestsneedadditional treatment, due to

the nature of the server-side environment. Server-side processing needsto

take into account Common Gateway Interface (CGI), and, more specifically,

PHP'sabstraction andextension of CGIvia itsServerAPIs(SAPI). PHP has

providedsimplification aroundinput marshaling via superglobalssuch as:

$_COOKIE , which deserializesandprovidessimplifiedaccessforHTTP

cookies.

$_GET , which deserializesandprovidessimplifiedaccessforquery string

arguments.

$_POST , which deserializesandprovidessimplifiedaccessforurlencoded

parameterssubmittedvia HTTP POST; generically, it can be consideredtheresultsof parsing the message body.

$_FILES , which providesserializedmetadata aroundfile uploads.

$_SERVER , which providesaccessto CGI/SAPIenvironment variables,

which commonly include the request method, the request scheme, the

request URI, andheaders.


55 19/06/2016 0


11/55

ServerRequestInterface extends RequestInterface to provide an abstraction

aroundthese varioussuperglobals. Thispractice helpsreduce coupling to the

superglobalsby consumers, andencouragesandpromotesthe ability to test

request consumers.

The serverrequest providesone additional property, "attributes", to allow

consumersthe ability to introspect, decompose, andmatch the request

against application-specific rules(such aspath matching, scheme matching,

host matching, etc.). Assuch, the serverrequest can also provide messaging

between multiple request consumers.

1.6Uploadedfiles

ServerRequestInterface specifiesa methodforretrieving a tree of uploadfiles

in a normalizedstructure, with each leaf an instance of

UploadedFileInterface .

The $_FILES superglobal hassome well-known problemswhen dealing with

arraysof file inputs. Asan example, if youhave a form that submitsan arrayof files e.g., the input name "files", submitting files[0] and files[1]

PHP will represent thisas:

array(

'files' => array(

'name' => array(

0 => 'file0.txt',

1 => 'file1.html',

),

'type' => array(

0 => 'text/plain',

1 => 'text/html',

),


55 19/06/2016 0


12/55

/* etc. */

),

)

insteadof the expected:

array(

'files' => array(

0 => array(

'name' => 'file0.txt',

'type' => 'text/plain',

/* etc. */

), 1 => array(

'name' => 'file1.html',

'type' => 'text/html',

/* etc. */

),

),

)

The result isthat consumersneedto knowthislanguage implementation

detail, andwrite code forgathering the data fora given upload.

Additionally, scenariosexist where $_FILES isnot populatedwhen file

uploadsoccur:

When the HTTP methodisnot POST .

When unit testing.

When operating undera non-SAPIenvironment, such asReactPHP.

In such cases, the data will needto be seededdifferently. Asexamples:


55 19/06/2016 0


13/55

A processmight parse the message body to discoverthe file uploads. In

such cases, the implementation may choose notto write the file uploads

to the file system, but insteadwrap them in a stream in orderto reduce

memory, I/O, andstorage overhead.

In unit testing scenarios, developersneedto be able to stub and/ormock

the file uploadmetadata in orderto validate andverify different

scenarios.

getUploadedFiles() providesthe normalizedstructure forconsumers.

Implementationsare expectedto:

Aggregate all information fora given file upload, anduse it to populate a

Psr\Http\Message\UploadedFileInterface instance.

Re-create the submittedtree structure, with each leaf being the

appropriate Psr\Http\Message\UploadedFileInterface instance forthe given

location in the tree.

The tree structure referencedshouldmimic the naming structure in which

fileswere submitted.

In the simplest example, thismight be a single namedform element

submittedas:

In thiscase, the structure in $_FILES wouldlook like:

array(

'avatar' => array(

'tmp_name' => 'phpUxcOty',

'name' => 'my-avatar.png',

'size' => 90996,


55 19/06/2016 0


14/55

'type' => 'image/png',

'error' => 0,

),

)

The normalizedform returnedby getUploadedFiles() wouldbe:

array(

'avatar' => /* UploadedFileInterface instance */

)

In the case of an input using array notation forthe name:

$_FILES endsup looking like this:

array(

'my-form' => array(

'details' => array(

'avatar' => array(

'tmp_name' => 'phpUxcOty',

'name' => 'my-avatar.png',

'size' => 90996,

'type' => 'image/png',

'error' => 0,

),

),

),

)

Andthe corresponding tree returnedby getUploadedFiles() shouldbe:


55 19/06/2016 0


15/55

array(

'my-form' => array(

'details' => array(

'avatar' => /* UploadedFileInterface instance */

),

),

)

In some cases, youmay specify an array of files:

Upload an avatar:

Upload an avatar:

(Asan example, JavaScript controlsmight spawn additional file uploadinputs

to allowuploading multiple filesat once.)

In such a case, the specification implementation must aggregate all

information relatedto the file at the given index. The reason isbecause

$_FILES deviatesfrom itsnormal structure in such cases:

array(

'my-form' => array(

'details' => array(

'avatars' => array(

'tmp_name' => array(

0 => '...',

1 => '...',

2 => '...',

),

'name' => array(

0 => '...',

1 => '...',

2 => '...',


55 19/06/2016 0


16/55

),

'size' => array(

0 => '...',

1 => '...',

2 => '...',

), 'type' => array(

0 => '...',

1 => '...',

2 => '...',

),

'error' => array(

0 => '...',

1 => '...',

2 => '...',

),

),

),

),

)

The above $_FILES array wouldcorrespondto the following structure as

returnedby getUploadedFiles() :

array(

'my-form' => array(

'details' => array(

'avatars' => array( 0 => /* UploadedFileInterface instance */,

1 => /* UploadedFileInterface instance */,

2 => /* UploadedFileInterface instance */,

),

),

),


55 19/06/2016 0


17/55

)

Consumerswouldaccessindex 1 of the nestedarray using:

$request->getUploadedFiles()['my-form']['details']['avatars'][1];

Because the uploadedfilesdata isderivative (derivedfrom $_FILES orthe

request body), a mutatormethod, withUploadedFiles() , isalso present in the

interface, allowing delegation of the normalization to anotherprocess.

In the case of the original examples, consumption resemblesthe following:

$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"

Thisproposal also recognizesthat implementationsmay operate in non-SAPI

environments. Assuch, UploadedFileInterface providesmethodsforensuring

operationswill work regardlessof environment. In particular:

moveTo($targetPath) isprovidedasa safe andrecommendedalternative

to calling move_uploaded_file() directly on the temporary uploadfile.

Implementationswill detect the correct operation to use basedon

environment.

getStream() will return a StreamInterface instance. In non-SAPI


55 19/06/2016 0


18/55


19/55


20/55

*

* @param string $version HTTP protocol version

* @return self

*/

public

function

with rotocolVersion

($version);

/**

* Retrieves all message header values.

*

* The keys represent the header name as it will be sent over the wire,

* each value is an array of strings associated with the header.

*

* // Represent the headers as a string

* foreach ($message->getHeaders() as $name => $values) {

* echo $name . ': ' . implode(', ', $values);

* }

*

* // Emit headers iteratively:

* foreach ($message->getHeaders() as $name => $values) {

* foreach ($values as $value) {

* header(sprintf('%s: %s', $name, $value), false); * }

* }

*

* While header names are not case-sensitive, getHeaders() will preser

* exact case in which headers were originally specified.

*

* @return string[][] Returns an associative array of the message's he

* Each key MUST be a header name, and each value MUST be an array

* strings for that header.

*/

public

function

getHeaders

();

/**

* Checks if a header exists by the given case-insensitive name.


55 19/06/2016 0


21/55

*

* @param string $name Case-insensitive header field name.

* @return bool Returns true if any header names match the given heade

* name using a case-insensitive string comparison. Returns false i

* no matching header name is found in the message.

*/

public

function

hasHeader

($name);

/**

* Retrieves a message header value by the given case-insensitive name.

*

* This method returns an array of all the header values of the given

* case-insensitive header name.

*

* If the header does not appear in the message, this method MUST retu

* empty array.

*

* @param string $name Case-insensitive header field name.

* @return string[] An array of string values as provided for the give

* header. If the header does not appear in the message, this metho

* return an empty array. */

publicfunctiongetHeader($name);

/**

* Retrieves a comma-separated string of the values for a single heade

*

* This method returns all of the header values of the given

* case-insensitive header name as a string concatenated together usin

* a comma.

*

* NOTE: Not all header values may be appropriately represented using

* comma concatenation. For such headers, use getHeader() instead

* and supply your own delimiter when concatenating.

*


55 19/06/2016 0


22/55


23/55

* immutability of the message, and MUST return an instance that has t

* new header and/or value.

*

* @param string $name Case-insensitive header field name to add.

* @param string|string[] $value Header value(s).

* @return self * @throws \InvalidArgumentException for invalid header names.

* @throws \InvalidArgumentException for invalid header values.

*/

publicfunctionwithAddedHeader($name, $value);

/**

* Return an instance without the specified header.

*

* Header resolution MUST be done without case-sensitivity.

*

* This method MUST be implemented in such a way as to retain the

* immutability of the message, and MUST return an instance that remov

* the named header.

*

* @param string $name Case-insensitive header field name to remove. * @return self

*/

publicfunctionwithoutHeader($name);

/**

* Gets the body of the message.

*

* @return StreamInterface Returns the body as a stream.

*/

publicfunctiongetBody();

/**

* Return an instance with the specified message body.

*


55 19/06/2016 0


24/55

* The body MUST be a StreamInterface object.

*


* immutability of the message, and MUST return a new instance that ha

* new body stream.

* * @param StreamInterface $body Body.

* @return self

* @throws \InvalidArgumentException When the body is not valid.

*/

publicfunctionwithBody(StreamInterface $body);

}

3.2Psr\Http\Message\RequestInterface


25/55

* be implemented such that they retain the internal state of the current

* message and return an instance that contains the changed state.

*/

interfaceRequestInterface extendsMessageInterface

{

/** * Retrieves the message's request target.

*

* Retrieves the message's request-target either as it will appear (fo

* clients), as it appeared at request (for servers), or as it was

* specified for the instance (see withRequestTarget()).

*

* In most cases, this will be the origin-form of the composed URI,

* unless a value was provided to the concrete implementation (see

* withRequestTarget() below).

*

* If no URI is available, and no request-target has been specifically

* provided, this method MUST return the string "/".

*

* @return string

*/ publicfunctiongetRequestTarget();

/**

* Return an instance with the specific request-target.

*

* If the request needs a non-origin-form request-target e.g., for

* specifying an absolute-form, authority-form, or asterisk-form

* this method may be used to create an instance with the specified

* request-target, verbatim.

*



* changed request target.

*


55 19/06/2016 0


26/55

* @see http://tools.ietf.org/html/rfc7230#section-2.7 (for the variou

* request-target forms allowed in request messages)

* @param mixed $requestTarget

* @return self

*/

publicfunctionwithRequestTarget($requestTarget);

/**

* Retrieves the HTTP method of the request.

*

* @return string Returns the request method.

*/

publicfunctiongetMethod();

/**

* Return an instance with the provided HTTP method.

*

* While HTTP method names are typically all uppercase characters, HTT

* method names are case-sensitive and thus implementations SHOULD NOT

* modify the given string.

* * This method MUST be implemented in such a way as to retain the


* changed request method.

*

* @param string $method Case-sensitive method.

* @return self

* @throws \InvalidArgumentException for invalid HTTP methods.

*/

public

function

withMethod

($method);

/**

* Retrieves the URI instance.

*

* This method MUST return a UriInterface instance.


55 19/06/2016 0


27/55

*

* @see http://tools.ietf.org/html/rfc3986#section-4.3

* @return UriInterface Returns a UriInterface instance

* representing the URI of the request.

*/

publicfunctiongetUri();

/**

* Returns an instance with the provided URI.

*

* This method MUST update the Host header of the returned request by

* default if the URI contains a host component. If the URI does not

* contain a host component, any pre-existing Host header MUST be carri

* over to the returned request.

*

* You can opt-in to preserving the original state of the Host header

* setting `$preserveHost` to `true`. When `$preserveHost` is set to

* `true`, this method interacts with the Host header in the following

*

* - If the the Host header is missing or empty, and the new URI contai

* a host component, this method MUST update the Host header in the* request.

* - If the Host header is missing or empty, and the new URI does not

* host component, this method MUST NOT update the Host header in th

* request.

* - If a Host header is present and non-empty, this method MUST NOT u

* the Host header in the returned request.

*



* new UriInterface instance.

*


* @param UriInterface $uri New request URI to use.

* @param bool $preserveHost Preserve the original state of the Host h


55 19/06/2016 0


28/55

* @return self

*/

public

function

withUri

(UriInterface $uri, $preserveHost=

false

);

}

3.2.1Psr\Http\Message\ServerRequestInterface


29/55


30/55

* @return array

*/

public

function

getCookie arams

();

/**

* Return an instance with the specified cookies. *

* The data IS NOT REQUIRED to come from the $_COOKIE superglobal, but

* be compatible with the structure of $_COOKIE. Typically, this data

* be injected at instantiation.

*

* This method MUST NOT update the related Cookie header of the reques

* instance, nor related values in the server params.

*



* updated cookie values.

*

* @param array $cookies Array of key/value pairs representing cookies.

* @return self

*/ publicfunctionwithCookie arams(array$cookies);

/**

* Retrieve query string arguments.

*

* Retrieves the deserialized query string arguments, if any.

*

* Note: the query params might not be in sync with the URI or server

* params. If you need to ensure you are only getting the original

* values, you may need to parse the query string from `getUri()->getQ

* or from the `QUERY_STRING` server param.

*

* @return array

*/


55 19/06/2016 0


31/55

publicfunctiongetQuery arams();

/**

* Return an instance with the specified query string arguments.

*

* These values SHOULD remain immutable over the course of the incomin * request. They MAY be injected during instantiation, such as from PH

* $_GET superglobal, or MAY be derived from some other value such as

* URI. In cases where the arguments are parsed from the URI, the data

* MUST be compatible with what PHP's parse_str() would return for

* purposes of how duplicate query parameters are handled, and how nes

* sets are handled.

*

* Setting query string arguments MUST NOT change the URI stored by th

* request, nor the values in the server params.

*



* updated query string arguments.

*

* @param array $query Array of query string arguments, typically from * $_GET.

* @return self

*/

publicfunctionwithQuery arams(array$query);

/**

* Retrieve normalized file upload data.

*

* This method returns upload metadata in a normalized tree, with each

* an instance of Psr\Http\Message\UploadedFileInterface.

*

* These values MAY be prepared from $_FILES or the message body durin

* instantiation, or MAY be injected via withUploadedFiles().

*


55 19/06/2016 0


32/55

* @return array An array tree of UploadedFileInterface instances; an

* array MUST be returned if no data is present.

*/

publicfunctiongetUploadedFiles();

/** * Create a new instance with the specified uploaded files.

*



* updated body parameters.

*

* @param array An array tree of UploadedFileInterface instances.

* @return self

* @throws \InvalidArgumentException if an invalid structure is provid

*/

publicfunctionwithUploadedFiles(array$uploadedFiles);

/**

* Retrieve any parameters provided in the request body.

* * If the request Content-Type is either application/x-www-form-urlenc

* or multipart/form-data, and the request method is POST, this method

* return the contents of $_POST.

*

* Otherwise, this method may return any results of deserializing

* the request body content; as parsing returns structured content, th

* potential types MUST be arrays or objects only. A null value indica

* the absence of body content.

*

* @return null|array|object The deserialized body parameters, if any.

* These will typically be an array or object.

*/

public

function

get arsedBody

();


55 19/06/2016 0


33/55

/**

* Return an instance with the specified body parameters.

*

* These MAY be injected during instantiation.

*

* If the request Content-Type is either application/x-www-form-urlenc * or multipart/form-data, and the request method is POST, use this me

* ONLY to inject the contents of $_POST.

*

* The data IS NOT REQUIRED to come from $_POST, but MUST be the resul

* deserializing the request body content. Deserialization/parsing ret

* structured data, and, as such, this method ONLY accepts arrays or o

* or a null value if nothing was available to parse.

*

* As an example, if content negotiation determines that the request d

* is a JSON payload, this method could be used to create a request

* instance with the deserialized parameters.

*



* updated body parameters. *

* @param null|array|object $data The deserialized body data. This wil

* typically be in an array or object.

* @return self

* @throws \InvalidArgumentException if an unsupported argument type i

* provided.

*/

publicfunctionwith arsedBody($data);

/**

* Retrieve attributes derived from the request.

*

* The request "attributes" may be used to allow injection of any

* parameters derived from the request: e.g., the results of path


55 19/06/2016 0


34/55

* match operations; the results of decrypting cookies; the results of

* deserializing non-form-encoded message bodies; etc. Attributes

* will be application and request specific, and CAN be mutable.

*

* @return mixed[] Attributes derived from the request.

*/

public

function

getAttributes

();

/**

* Retrieve a single derived request attribute.

*

* Retrieves a single derived request attribute as described in

* getAttributes(). If the attribute has not been previously set, retu

* the default value as provided.

*

* This method obviates the need for a hasAttribute() method, as it al

* specifying a default value to return if the attribute is not found.

*

* @see getAttributes()

* @param string $name The attribute name.

* @param mixed $default Default value to return if the attribute does* @return mixed

*/

publicfunctiongetAttribute($name, $default=null);

/**

* Return an instance with the specified derived request attribute.

*

* This method allows setting a single derived request attribute as

* described in getAttributes().

*



* updated attribute.

*


55 19/06/2016 0


35/55



* @param mixed $value The value of the attribute.

* @return self

*/

publicfunctionwithAttribute($name, $value);

/**

* Return an instance that removes the specified derived request attri

*

* This method allows removing a single derived request attribute as

* described in getAttributes().

*


* immutability of the message, and MUST return an instance that remov

* the attribute.

*



* @return self

*/ publicfunctionwithoutAttribute($name);

}

3.3Psr\Http\Message\ResponseInterface


36/55


37/55

* @param int $code The 3-digit integer result code to set.

* @param string $reasonPhrase The reason phrase to use with the

* provided status code; if none is provided, implementations MAY

* use the defaults as suggested in the HTTP specification.

* @return self

* @throws \InvalidArgumentException For invalid status code arguments. */

publicfunctionwithStatus($code, $reasonPhrase='');

/**

* Gets the response reason phrase associated with the status code.

*

* Because a reason phrase is not a required element in a response

* status line, the reason phrase value MAY be empty. Implementations

* choose to return the default RFC 7231 recommended reason phrase (or

* listed in the IANA HTTP Status Code Registry) for the response's

* status code.

*

* @see http://tools.ietf.org/html/rfc7231#section-6

* @see http://www.iana.org/assignments/http-status-codes/http-status-

* @return string Reason phrase; must return an empty string if none p */

publicfunctiongetReason hrase();

}

3.4 Psr\Http\Message\StreamInterface


38/55

* a wrapper around the most common operations, including serialization of

* the entire stream to a string.

*/

interfaceStreamInterface

{

/** * Reads all data from the stream into a string, from the beginning to

*

* This method MUST attempt to seek to the beginning of the stream bef

* reading data and read the stream until the end is reached.

*

* Warning: This could attempt to load a large amount of data into mem

*

* This method MUST NOT raise an exception in order to conform with PH

* string casting operations.

*

* @see http://php.net/manual/en/language.oop5.magic.php#object.tostri

* @return string

*/

publicfunction__toString();

/**

* Closes the stream and any underlying resources.

*

* @return void

*/

publicfunctionclose();

/**

* Separates any underlying resources from the stream.

*

* After the stream has been detached, the stream is in an unusable st

*

* @return resource|null Underlying PHP stream, if any

*/


55 19/06/2016 0


39/55

publicfunctiondetach();

/**

* Get the size of the stream if known.

*

* @return int|null Returns the size in bytes if known, or null if unk */

publicfunctiongetSize();

/**

* Returns the current position of the file read/write pointer

*

* @return int Position of the file pointer

* @throws \RuntimeException on error.

*/

publicfunctiontell();

/**

* Returns true if the stream is at the end of the stream.

*

* @return bool */

publicfunctioneof();

/**

* Returns whether or not the stream is seekable.

*

* @return bool

*/

public

function

isSeekable

();

/**

* Seek to a position in the stream.

*

* @see http://www.php.net/manual/en/function.fseek.php


55 19/06/2016 0


40/55

* @param int $offset Stream offset

* @param int $whence Specifies how the cursor position will be calcul

* based on the seek offset. Valid values are identical to the bui

* PHP $whence values for `fseek()`. SEEK_SET: Set position equal

* offset bytes SEEK_CUR: Set position to current location plus of

* SEEK_END: Set position to end-of-stream plus offset. * @throws \RuntimeException on failure.

*/

public

function

seek

($offset, $whence=

SEEK_SET);

/**

* Seek to the beginning of the stream.

*

* If the stream is not seekable, this method will raise an exception;

* otherwise, it will perform a seek(0).

*

* @see seek()

* @see http://www.php.net/manual/en/function.fseek.php

* @throws \RuntimeException on failure.

*/

publicfunctionrewind();

/**

* Returns whether or not the stream is writable.

*

* @return bool

*/

public

function

isWritable

();

/**

* Write data to the stream.

*

* @param string $string The string that is to be written.

* @return int Returns the number of bytes written to the stream.

* @throws \RuntimeException on failure.


55 19/06/2016 0


41/55

*/

publicfunctionwrite($string);

/**

* Returns whether or not the stream is readable.

* * @return bool

*/

public

function

isReadable

();

/**

* Read data from the stream.

*

* @param int $length Read up to $length bytes from the object and ret

* them. Fewer than $length bytes may be returned if underlying st

* call returns fewer bytes.

* @return string Returns the data read from the stream, or an empty s

* if no bytes are available.

* @throws \RuntimeException if an error occurs.

*/

publicfunctionread($length);

/**

* Returns the remaining contents in a string

*

* @return string

* @throws \RuntimeException if unable to read.

* @throws \RuntimeException if error occurs while reading.

*/

public

function

getContents

();

/**

* Get stream metadata as an associative array or retrieve a specific

*

* The keys returned are identical to the keys returned from PHP's


55 19/06/2016 0


42/55

* stream_get_meta_data() function.

*

* @see http://php.net/manual/en/function.stream-get-meta-data.php

* @param string $key Specific metadata to retrieve.

* @return array|mixed|null Returns an associative array if no key is

* provided. Returns a specific key value if a key is provided and* value is found, or null if the key is not found.

*/

public

function

getMetadata

($key=

null

);

}

3.5Psr\Http\Message\UriInterface


43/55

* @see http://tools.ietf.org/html/rfc3986 (the URI specification)

*/

interface

UriInterface

{

/**

* Retrieve the scheme component of the URI. *

* If no scheme is present, this method MUST return an empty string.

*

* The value returned MUST be normalized to lowercase, per RFC 3986

* Section 3.1.

*

* The trailing ":" character is not part of the scheme and MUST NOT b

* added.

*

* @see https://tools.ietf.org/html/rfc3986#section-3.1

* @return string The URI scheme.

*/

publicfunctiongetScheme();

/** * Retrieve the authority component of the URI.

*

* If no authority information is present, this method MUST return an

* string.

*

* The authority syntax of the URI is:

*

*

* [user-info@]host[:port]

*

*

* If the port component is not set or is the standard port for the cu

* scheme, it SHOULD NOT be included.

*


55 19/06/2016 0


44/55


* @return string The URI authority, in "[user-info@]host[:port]" form

*/

publicfunctiongetAuthority();

/** * Retrieve the user information component of the URI.

*

* If no user information is present, this method MUST return an empty

* string.

*

* If a user is present in the URI, this will return that value;

* additionally, if the password is also present, it will be appended

* user value, with a colon (":") separating the values.

*

* The trailing "@" character is not part of the user information and

* NOT be added.

*

* @return string The URI user information, in "username[:password]" f

*/

publicfunctiongetUserInfo();

/**

* Retrieve the host component of the URI.

*

* If no host is present, this method MUST return an empty string.

*

* The value returned MUST be normalized to lowercase, per RFC 3986

* Section 3.2.2.

*

* @see http://tools.ietf.org/html/rfc3986#section-3.2.2

* @return string The URI host.

*/

public

function

getHost

();


55 19/06/2016 0


45/55

/**

* Retrieve the port component of the URI.

*

* If a port is present, and it is non-standard for the current scheme,

* this method MUST return it as an integer. If the port is the standa

* used with the current scheme, this method SHOULD return null. *

* If no port is present, and no scheme is present, this method MUST r

* a null value.

*

* If no port is present, but a scheme is present, this method MAY ret

* the standard port for that scheme, but SHOULD return null.

*

* @return null|int The URI port.

*/

publicfunctionget ort();

/**

* Retrieve the path component of the URI.

*

* The path can either be empty or absolute (starting with a slash) or * rootless (not starting with a slash). Implementations MUST support

* three syntaxes.

*

* Normally, the empty path "" and absolute path "/" are considered eq

* defined in RFC 7230 Section 2.7.3. But this method MUST NOT automati

* do this normalization because in contexts with a trimmed base path,

* the front controller, this difference becomes significant. It's the

* of the user to handle both "" and "/".

*

* The value returned MUST be percent-encoded, but MUST NOT double-enc

* any characters. To determine what characters to encode, please refe

* RFC 3986, Sections 2 and 3.3.

*

* As an example, if the value should include a slash ("/") not intend


55 19/06/2016 0


46/55


47/55

*

* The leading "#" character is not part of the fragment and MUST NOT

* added.

*

* The value returned MUST be percent-encoded, but MUST NOT double-enc

* any characters. To determine what characters to encode, please refe* RFC 3986, Sections 2 and 3.5.

*

* @see https://tools.ietf.org/html/rfc3986#section-2


* @return string The URI fragment.

*/

publicfunctiongetFragment();

/**

* Return an instance with the specified scheme.

*

* This method MUST retain the state of the current instance, and retu

* an instance that contains the specified scheme.

*

* Implementations MUST support the schemes "http" and "https" case * insensitively, and MAY accommodate other schemes if required.

*

* An empty scheme is equivalent to removing the scheme.

*

* @param string $scheme The scheme to use with the new instance.

* @return self A new instance with the specified scheme.

* @throws \InvalidArgumentException for invalid schemes.

* @throws \InvalidArgumentException for unsupported schemes.

*/

publicfunctionwithScheme($scheme);

/**

* Return an instance with the specified user information.

*


55 19/06/2016 0


48/55


* an instance that contains the specified user information.

*

* Password is optional, but the user information MUST include the

* user; an empty string for the user is equivalent to removing user

* information. *

* @param string $user The user name to use for authority.

* @param null|string $password The password associated with $user.

* @return self A new instance with the specified user information.

*/

publicfunctionwithUserInfo($user, $password=null);

/**

* Return an instance with the specified host.

*


* an instance that contains the specified host.

*

* An empty host value is equivalent to removing the host.

* * @param string $host The hostname to use with the new instance.

* @return self A new instance with the specified host.

* @throws \InvalidArgumentException for invalid hostnames.

*/

public

function

withHost

($host);

/**

* Return an instance with the specified port.

*


* an instance that contains the specified port.

*

* Implementations MUST raise an exception for ports outside the

* established TCP and UDP port ranges.


55 19/06/2016 0


49/55

*

* A null value provided for the port is equivalent to removing the po

* information.

*

* @param null|int $port The port to use with the new instance; a null

* removes the port information. * @return self A new instance with the specified port.

* @throws \InvalidArgumentException for invalid ports.

*/

publicfunctionwith ort($port);

/**

* Return an instance with the specified path.

*


* an instance that contains the specified path.

*

* The path can either be empty or absolute (starting with a slash) or

* rootless (not starting with a slash). Implementations MUST support

* three syntaxes.

* * If an HTTP path is intended to be host-relative rather than path-re

* then it must begin with a slash ("/"). HTTP paths not starting with

* are assumed to be relative to some base path known to the applicati

* consumer.

*

* Users can provide both encoded and decoded path characters.

* Implementations ensure the correct encoding as outlined in getPath()

*

* @param string $path The path to use with the new instance.

* @return self A new instance with the specified path.

* @throws \InvalidArgumentException for invalid paths.

*/

public

function

with ath

($path);


55 19/06/2016 0


50/55

/**

* Return an instance with the specified query string.

*


* an instance that contains the specified query string.

* * Users can provide both encoded and decoded query characters.

* Implementations ensure the correct encoding as outlined in getQuery

*

* An empty query string value is equivalent to removing the query stri

*

* @param string $query The query string to use with the new instance.

* @return self A new instance with the specified query string.

* @throws \InvalidArgumentException for invalid query strings.

*/

publicfunctionwithQuery($query);

/**

* Return an instance with the specified URI fragment.

*

* This method MUST retain the state of the current instance, and retu * an instance that contains the specified URI fragment.

*

* Users can provide both encoded and decoded fragment characters.

* Implementations ensure the correct encoding as outlined in getFragm

*

* An empty fragment value is equivalent to removing the fragment.

*

* @param string $fragment The fragment to use with the new instance.

* @return self A new instance with the specified fragment.

*/

public

function

withFragment

($fragment);

/**

* Return the string representation as a URI reference.


55 19/06/2016 0


51/55

*

* Depending on which components of the URI are present, the resulting

* string is either a full URI or relative reference according to RFC

* Section 4.1. The method concatenates the various components of the

* using the appropriate delimiters:

* * - If a scheme is present, it MUST be suffixed by ":".

* - If an authority is present, it MUST be prefixed by "//".

* - The path can be concatenated without delimiters. But there are tw

* cases where the path has to be adjusted to make the URI reference

* valid as PHP does not allow to throw an exception in __toString():

* - If the path is rootless and an authority is present, the path

* be prefixed by "/".

* - If the path is starting with more than one "/" and no authori

* present, the starting slashes MUST be reduced to one.

* - If a query is present, it MUST be prefixed by "?".

* - If a fragment is present, it MUST be prefixed by "#".

*


* @return string

*/ publicfunction__toString();

}

3.6Psr\Http\Message\UploadedFileInterface


52/55

* state of the current instance and return an instance that contains the

* changed state.

*/

interfaceUploadedFileInterface

{

/** * Retrieve a stream representing the uploaded file.

*

* This method MUST return a StreamInterface instance, representing th

* uploaded file. The purpose of this method is to allow utilizing nati

* stream functionality to manipulate the file upload, such as

* stream_copy_to_stream() (though the result will need to be decorate

* native PHP stream wrapper to work with such functions).

*

* If the moveTo() method has been called previously, this method MUST

* an exception.

*

* @return StreamInterface Stream representation of the uploaded file.

* @throws \RuntimeException in cases when no stream is available.

* @throws \RuntimeException in cases when no stream can be created.

*/ publicfunctiongetStream();

/**

* Move the uploaded file to a new location.

*

* Use this method as an alternative to move_uploaded_file(). This met

* guaranteed to work in both SAPI and non-SAPI environments.

* Implementations must determine which environment they are in, and u

* appropriate method (move_uploaded_file(), rename(), or a stream

* operation) to perform the operation.

*

* $targetPath may be an absolute path, or a relative path. If it is a

* relative path, resolution should be the same as used by PHP's renam

* function.


55 19/06/2016 0


53/55

*

* The original file or stream MUST be removed on completion.

*

* If this method is called more than once, any subsequent calls MUST

* an exception.

* * When used in an SAPI environment where $_FILES is populated, when w

* files via moveTo(), is_uploaded_file() and move_uploaded_file() SHO

* used to ensure permissions and upload status are verified correctly.

*

* If you wish to move to a stream, use getStream(), as SAPI operation

* cannot guarantee writing to stream destinations.

*

* @see http://php.net/is_uploaded_file

* @see http://php.net/move_uploaded_file

* @param string $targetPath Path to which to move the uploaded file.

* @throws \InvalidArgumentException if the $path specified is invalid.

* @throws \RuntimeException on any error during the move operation.

* @throws \RuntimeException on the second or subsequent call to the m

*/

publicfunctionmoveTo($targetPath);

/**

* Retrieve the file size.

*

* Implementations SHOULD return the value stored in the "size" key of

* the file in the $_FILES array if available, as PHP calculates this

* on the actual size transmitted.

*

* @return int|null The file size in bytes or null if unknown.

*/

public

function

getSize

();

/**

* Retrieve the error associated with the uploaded file.


55 19/06/2016 0


54/55

*

* The return value MUST be one of PHP's UPLOAD_ERR_XXX constants.

*

* If the file was uploaded successfully, this method MUST return

* UPLOAD_ERR_OK.

* * Implementations SHOULD return the value stored in the "error" key o

* the file in the $_FILES array.

*

* @see http://php.net/manual/en/features.file-upload.errors.php

* @return int One of PHP's UPLOAD_ERR_XXX constants.

*/

publicfunctiongetError();

/**

* Retrieve the filename sent by the client.

*

* Do not trust the value returned by this method. A client could send

* a malicious filename with the intention to corrupt or hack your

* application.

* * Implementations SHOULD return the value stored in the "name" key of


*

* @return string|null The filename sent by the client or null if none

* was provided.

*/

public

function

getClientFilename

();

/**

* Retrieve the media type sent by the client.

*

* Do not trust the value returned by this method. A client could send

* a malicious media type with the intention to corrupt or hack your

* application.


55 19/06/2016 0


55/55

*

* Implementations SHOULD return the value stored in the "type" key of


*

* @return string|null The media type sent by the client or null if no

* was provided. */

publicfunctiongetClientMediaType();

}

Additional Info:

Available tran

slation

s:

PSR-7: HTTP message interfaces

PSR-7: HTTP Message Meta Document

English (official)

Followuson Twitter Chat on IRC Channel Contribute via Github Join ourmailing list


psr-7_ http message interfaces - php-fig

Documents