Added PSR-7 Interfaces brief explanations and Basic Usage Guide #79
Conversation
There was a problem hiding this comment.
Overall, I think this will be a welcome addition.
I'm unsure if the PSR7-Interfaces.md file is strictly necessary; it feels like we could direct developers to the specification, which details each interface, and the methods. That said, having a tabular format is relatively useful for easy lookup of arguments and expected return values. I'm curious if others could weigh in with their opinions.
Second, as noted, I'm reluctant to use Diactoros for the examples, as that could be construed as recommendation of that specific implementation. I think it would suffice to indicate that instantiation will vary based on implementation, and just indicate which interface each of $request, $response, etc. refer to.
docs/PSR7-Interfaces.md
Outdated
| | Method Name | Description | Notes | | ||
| |------------------------------------| ----------- | ----- | | ||
| | `getProtocolVersion()` | Gets HTTP protocol version | 1.0 or 1.1 | | ||
| | `withProtocolVersion($version)` | Sets HTTP protocol version | | |
There was a problem hiding this comment.
I'd be careful about using the term "sets" when discussing the various with*() methods. They return a new instance that incorporates the data you provide, while leaving the original instance unchanged. This is more clear in the request/response-specific sections below, but the verbiage for these general message methods needs to be the same.
There was a problem hiding this comment.
What if I write "Sets***" then noting that "***" means returning a new instance with given parameter instead of actually modifying the original HTTP Message (or Request or Response) ?
docs/PSR7-Interfaces.md
Outdated
| | `hasHeader($name)` | Checks if HTTP Header with given name exists | | | ||
| | `getHeader($name)` | Retrieves a array with the values for a single header | | | ||
| | `getHeaderLine($name)` | Retrieves a comma-separated string of the values for a single header | | | ||
| | `withHeader($name, $value)` | Sets a HTTP Header | If header already exists, value will be overwritten | |
There was a problem hiding this comment.
"Returns a new message instance that includes the provided header; if the header existed in the original instance, replaces the header value from the original message with the value provided when creating the new instance."
docs/PSR7-Interfaces.md
Outdated
| | `getHeader($name)` | Retrieves a array with the values for a single header | | | ||
| | `getHeaderLine($name)` | Retrieves a comma-separated string of the values for a single header | | | ||
| | `withHeader($name, $value)` | Sets a HTTP Header | If header already exists, value will be overwritten | | ||
| | `withAddedHeader($name, $value)` | Appends value to given header | If header already exists value will be appended, if not a new header will be created | |
There was a problem hiding this comment.
Do similar here as with the withHeader() (start with Returns a new message ...).
docs/PSR7-Interfaces.md
Outdated
| | `getHeaderLine($name)` | Retrieves a comma-separated string of the values for a single header | | | ||
| | `withHeader($name, $value)` | Sets a HTTP Header | If header already exists, value will be overwritten | | ||
| | `withAddedHeader($name, $value)` | Appends value to given header | If header already exists value will be appended, if not a new header will be created | | ||
| | `withoutHeader($name)` | Removes HTTP Header with given name| | |
There was a problem hiding this comment.
"Returns a new message instance that does not include the specified HTTP header."
docs/PSR7-Interfaces.md
Outdated
| | `getUserInfo()` | Retrieve the user information component of the URI. | | | ||
| | `getHost()` | Retrieve the host component of the URI. | | | ||
| | `getPort()` | Retrieve the port component of the URI. | | | ||
| | `getPath()` | etrieve the path component of the URI. | | |
There was a problem hiding this comment.
Missing R in Retreive.
docs/PSR7-Usage.md
Outdated
| > When using `ServerRequestInterface`, both `RequestInterface` and `Psr\Http\Message\MessageInterface` methods are considered. | ||
|
|
||
|
|
||
| Enough with the talking, let's put things in practice. |
docs/PSR7-Usage.md
Outdated
| #####Examples (using Zend Diactoros) | ||
|
|
||
| Zend Diactoros is an implementation for PSR-7 interfaces. It will be used to illustrate these examples. | ||
| Installation guide for Zend Diactoros: [Zend Diactoros Documentation - Installation](https://zendframework.github.io/zend-diactoros/install/) |
There was a problem hiding this comment.
I'm not sure we should use Diactoros here, as that sounds like an endorsement of a specific implementation. I'd change this to indicate that instantiation of messages will vary based on implementation, and leave it at that. The rest of the examples will work fine, and should work the same across implementations.
docs/PSR7-Usage.md
Outdated
| ```php | ||
| $body = $response->getBody(); | ||
| $body->rewind(); // or $body->seek(0); | ||
| $bodyText = $body->getContends(); |
There was a problem hiding this comment.
s/getContends/getContents/
corrected PSR-7 methods explanations corrected typos removed concrete usage of diactoros removed unnecessary text removed zend-diactoros autoload added assumption of $request and $response
|
@weierophinney , I have just corrected them with a more technical approach, I made the changes you suggested. Thank you for pointing out the inaccuracies. Please check if other issues exist. |
gabidj
changed the title
gabidj
changed the title
|
@weierophinney - Suggested changes were made. |
Added some examples for basic PSR-7 interfaces usage