psr-7_ http message interfaces - php-fig
TRANSCRIPT
-
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
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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');
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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.
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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.
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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.
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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:
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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.
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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',
),
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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:
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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,
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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:
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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 => '...',
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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 */,
),
),
),
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
18/55
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
19/55
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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.
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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.
*
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
22/55
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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.
*
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
24/55
* The body MUST be a StreamInterface object.
*
* This method MUST be implemented in such a way as to retain the
* 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
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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.
*
* This method MUST be implemented in such a way as to retain the
* immutability of the message, and MUST return an instance that has t
* changed request target.
*
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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
* immutability of the message, and MUST return an instance that has t
* 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.
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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.
*
* This method MUST be implemented in such a way as to retain the
* immutability of the message, and MUST return an instance that has t
* new UriInterface instance.
*
* @see http://tools.ietf.org/html/rfc3986#section-4.3
* @param UriInterface $uri New request URI to use.
* @param bool $preserveHost Preserve the original state of the Host h
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
28/55
* @return self
*/
public
function
withUri
(UriInterface $uri, $preserveHost=
false
);
}
3.2.1Psr\Http\Message\ServerRequestInterface
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
29/55
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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.
*
* This method MUST be implemented in such a way as to retain the
* immutability of the message, and MUST return an instance that has t
* 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
*/
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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.
*
* This method MUST be implemented in such a way as to retain the
* immutability of the message, and MUST return an instance that has t
* 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().
*
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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.
*
* This method MUST be implemented in such a way as to retain the
* immutability of the message, and MUST return an instance that has t
* 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
();
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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.
*
* This method MUST be implemented in such a way as to retain the
* immutability of the message, and MUST return an instance that has t
* 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
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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().
*
* This method MUST be implemented in such a way as to retain the
* immutability of the message, and MUST return an instance that has t
* updated attribute.
*
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
35/55
* @see getAttributes()
* @param string $name The attribute name.
* @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().
*
* 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 attribute.
*
* @see getAttributes()
* @param string $name The attribute name.
* @return self
*/ publicfunctionwithoutAttribute($name);
}
3.3Psr\Http\Message\ResponseInterface
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
36/55
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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
*/
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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.
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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.
*
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
44/55
* @see https://tools.ietf.org/html/rfc3986#section-3.2
* @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
();
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
46/55
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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
* @see https://tools.ietf.org/html/rfc3986#section-3.5
* @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.
*
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
48/55
* This method MUST retain the state of the current instance, and retu
* 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.
*
* This method MUST retain the state of the current instance, and retu
* 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.
*
* This method MUST retain the state of the current instance, and retu
* an instance that contains the specified port.
*
* Implementations MUST raise an exception for ports outside the
* established TCP and UDP port ranges.
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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.
*
* This method MUST retain the state of the current instance, and retu
* 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);
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
50/55
/**
* Return an instance with the specified query string.
*
* This method MUST retain the state of the current instance, and retu
* 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.
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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 "#".
*
* @see http://tools.ietf.org/html/rfc3986#section-4.1
* @return string
*/ publicfunction__toString();
}
3.6Psr\Http\Message\UploadedFileInterface
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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.
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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.
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
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
* the file in the $_FILES array.
*
* @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.
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p
55 19/06/2016 0
-
7/25/2019 PSR-7_HTTP Message Interfaces - PHP-FIG
55/55
*
* Implementations SHOULD return the value stored in the "type" key of
* the file in the $_FILES array.
*
* @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
7: HTTP message interfaces - PHP-FIG http://www.php-fig.org/p