Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[PSR-7] Clarify superglobal usage #354

Merged
merged 2 commits into from
Oct 16, 2014
Merged

[PSR-7] Clarify superglobal usage #354

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
93fea89
[PSR-7] Clarify superglobals/query parameters
weierophinney Oct 14, 2014
0de092b
[PSR-7] Updated IncomingRequestInterface param/return values
weierophinney Oct 15, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 32 additions & 44 deletions proposed/http-message.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -365,7 +365,7 @@ namespace Psr\Http\Message;
* This interface further describes a server-side request and provides
* accessors and mutators around common request data, such as query
* string arguments, body parameters, upload file metadata, cookies, and
* matched routing parameters.
* arbitrary attributes derived from the request.
*/
interface IncomingRequestInterface extends RequestInterface
{
Expand All @@ -375,13 +375,10 @@ interface IncomingRequestInterface extends RequestInterface
* Retrieves cookies sent by the client to the server.
*
* The assumption is these are injected during instantiation, typically
* from PHP's $_COOKIE superglobal, and should remain immutable over the
* course of the incoming request.
* from PHP's $_COOKIE superglobal. The data IS NOT REQUIRED to come from
* $_COOKIE, but MUST be compatible with the structure of $_COOKIE.
*
* The return value can be either an array or an object that acts like
* an array (e.g., implements ArrayAccess, or an ArrayObject).
*
* @return array|\ArrayAccess
* @return array
*/
public function getCookieParams();

Expand All @@ -394,10 +391,9 @@ interface IncomingRequestInterface extends RequestInterface
* the original value, filter them, and re-inject into the incoming
* request..
*
* The value provided should be an array or array-like object
* (e.g., implements ArrayAccess, or an ArrayObject).
* The value provided MUST be compatible with the structure of $_COOKIE.
*
* @param array|\ArrayAccess $cookies Cookie values/structs
* @param array $cookies Cookie values
*
* @return void
*/
Expand All @@ -408,12 +404,13 @@ interface IncomingRequestInterface extends RequestInterface
*
* Retrieves the deserialized query string arguments, if any.
*
* The assumption is these are injected during instantiation, typically
* from PHP's $_GET superglobal, and should remain immutable over the
* course of the incoming request.
*
* The return value can be either an array or an object that acts like
* an array (e.g., implements ArrayAccess, or an ArrayObject).
* These values SHOULD remain immutable over the course of the incoming
* request. They MAY be injected during instantiation, such as from PHP's
* $_GET superglobal, or MAY be derived from some other value such as the
* 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 nested
* sets are handled.
*
* @return array
*/
Expand All @@ -422,15 +419,12 @@ interface IncomingRequestInterface extends RequestInterface
/**
* Retrieve the upload file metadata.
*
* This method should return file upload metadata in the same structure
* This method MUST return file upload metadata in the same structure
* as PHP's $_FILES superglobal.
*
* The assumption is these are injected during instantiation, typically
* from PHP's $_FILES superglobal, and should remain immutable over the
* course of the incoming request.
*
* The return value can be either an array or an object that acts like
* an array (e.g., implements ArrayAccess, or an ArrayObject).
* These values SHOULD remain immutable over the course of the incoming
* request. They MAY be injected during instantiation, such as from PHP's
* $_FILES superglobal, or MAY be derived from other sources.
*
* @return array Upload file(s) metadata, if any.
*/
Expand All @@ -439,58 +433,52 @@ interface IncomingRequestInterface extends RequestInterface
/**
* Retrieve any parameters provided in the request body.
*
* If the request body can be deserialized, and if the deserialized values
* can be represented as an array or object, this method can be used to
* retrieve them.
* If the request body can be deserialized to an array, this method can be
* used to retrieve them.
*
* In other cases, the parent getBody() method should be used to retrieve
* the body content.
*
* @return array|object The deserialized body parameters, if any. These may
* be either an array or an object, though an array or
* array-like object is recommended.
* @return array The deserialized body parameters, if any.
*/
public function getBodyParams();

/**
* Set the request body parameters.
*
* If the body content can be deserialized, the values obtained may then
* be injected into the response using this method. This method will
* typically be invoked by a factory marshaling request parameters.
* If the body content can be deserialized to an array, the values obtained
* may then be injected into the response using this method. This method
* will typically be invoked by a factory marshaling request parameters.
*
* @param array|object $values The deserialized body parameters, if any.
* These may be either an array or an object,
* though an array or array-like object is
* recommended.
* @param array $values The deserialized body parameters, if any.
*
* @return void
*/
public function setBodyParams($values);

/**
* Retrieve parameters matched during routing.
* Retrieve attributes derived from the request.
*
* If a router or similar is used to match against the path and/or request,
* this method can be used to retrieve the results, so long as those
* results can be represented as an array or array-like object.
* results can be represented as an array.
*
* @return array|\ArrayAccess Path parameters matched by routing
* @return array Path parameters matched by routing
*/
public function getPathParams();
public function getAttributes();

/**
* Set parameters discovered by matching that path
* Set attributes derived from the request
*
* If a router or similar is used to match against the path and/or request,
* this method can be used to inject the request with the results, so long
* as those results can be represented as an array or array-like object.
* as those results can be represented as an array.
*
* @param array|\ArrayAccess $values Path parameters matched by routing
* @param array $attributes Path parameters matched by routing
*
* @return void
*/
public function setPathParams(array $values);
public function setAttributes(array $attributes);
}
```

Expand Down