Improving the usage section

[ibrahimab]

• added examples on how to use the PSR-7 standard:
  • using it to create your own implementation
  • consuming it with an real world api service example

[Tobion]

👎 there are already enough implementations

[Tobion]

I don't think this belongs here. Just put a link to https://packagist.org/providers/psr/http-message-implementation and done.

[weierophinney]

I agree with @Tobion that we likely do not and should not detail how to implement, other than to say "implementations should implement all functionality in each interface" and leave it at that.

I also agree with @Tobion that the "consuming PSR-7" section should link to providers.

Are you willing to make those changes, @ibrahimab ?

[ibrahimab]

I am, I will post my new changes tomorrow night.

[ibrahimab]

@weierophinney I have made the changes and pushed it into this pull request. Can you review if this is acceptable to you?

[vladkras]

I don't think Guzzle implementation is valuable. For example, I don't need it at all. IMHO This section should be

1. clone repo
2. write this
3. implement that
4. don't forget to
5. profit

[sharifzadesina]

Guzzle is not good implementation for PSR-7.
Why we should have request method in the Client class? the Client class is not a factory. see PSR-17 for more info.

[ibrahimab]

It is not about how Guzzle uses the PSR in its Client class, it is about how Guzzle depends on the specification to define its request/response/etc. classes. The Client class is not on trial here.

The fact that I can replace each and every class in Guzzle that implements PSR-7 is a good enough reason to include it.

edit
@vladkras the fact that you don't need it, is not a reason. I don't need it either, but I also do not need a better usage section, as I know exactly how to use the PSR standards. It is for the people that are beginning with the PSR standards and for me Guzzle is the easiest library so far that I can use to explain it in lamen terms.

[vladkras]

Good enough to accompany Guzzle's repo with descriptions of how it's depends on or implemets PSR-7

[ibrahimab]

@vladkras what do you mean?

[ibrahimab]

I just think, having a usage section that just says "We'll certainly need some stuff in here." will scare off beginners and my commit helps them on their way.

[vladkras]

@ibrahimab I mean when you say "Guzzle needs ..." or "Guzzle supports ..." or "Guzzle depends on ..." you MUST write it in Guzzle. It has nothing to do with explaining how to implement http-messages

edit
Guzzle is the easiest library for you meantime for most users it's useless and is contrary to the idea of agnostic approach

[ibrahimab]

@vladkras If you read my explanation in the "consuming" chapter, you can read that I only use guzzle as an example. The example code I provide can work on any PSR-7 compatible library.

But what about the example code is non-agnostic to you? The ClientInterface is not a part of PSR-7 but an example as to how to make the Guzzle implementation agnostic for your services like PostsService did in the example code (see OtherHttpClient class).

[vladkras]

@ibrahimab There's nothing wrong with your example except the place where you are trying to post it. Feel free to fork this repo and implement it. No need to paste your code in README. But as far as Guzzle already has it's own PSR-7 https://github.com/guzzle/psr7 You can just provide a link to https://github.com/guzzle/guzzle/blob/master/src/ClientInterface.php in Links section not Usage one

[ibrahimab]

@vladkras Do you not agree that beginners who want to get started working with PSR-7 who do not know how to use PSR-7 can be helped with the example code in the usage section? I could change the section to use a fictitious library to make it less coupled?

[ibrahimab]

@vladkras the link you provided shows beginners how to use Guzzle but does not explain what Psr-7 has to do with it. It does not show how to write your own application code to decouple it from Guzzle where my example does do that.

[vladkras]

@ibrahimab Exactly, I think Usage section MUST NOT contain Guzzle, it MUST be pure PHP, but you MAY mention it in Links section (and even mark as *easiest), along with Zend, Symfony and other implementations

[ibrahimab]

@vladkras Okay, I will rewrite the usage section to use a fictitious library instead of Guzzle and link to several implementations.

[vladkras]

@ibrahimab, So do you just want to write the instruction that Guzzle best matches to? I'm integrating it right now in my project and my steps should be:

1. clone repo
2. run composer
3. check if classes are loaded
4. implement a, b, c, ...
5. define d, e, f, ...

This what "usage" means. Kind of quick start guide, not "use my favorite library cause it's a best approach". I don't argue Guzzle is good, but you should fork this repo, compose with Guzzle and push your own implemetation to your repo, write best README ever there and provide link. If you're sure this is not already done here https://github.com/guzzle/psr7