document how to use discovery

[dbu]

the discovery section only explains how to provide discovery for your own project. but i am trying to figure out how to just use discovery in my project. imho the doc should also explain that.

do i simply need to call HttpAdapterDiscovery::find() and thats it?

and for creating messages, i need the MessageFactoryDiscovery::find()->createRequest?

and what is the uri factory for? the MessageFactory accepts a string as well (the doc is incorrect btw, it should state that it can also accept an UriInterface)

i am happy to do a PR to add a usage section, but first want to be sure to understand correctly how things work.

[sagikazarmark]

The usage of discoveries is covered in the general section.

do i simply need to call HttpAdapterDiscovery::find() and thats it?

Yes, it is that simple.

and for creating messages, i need the MessageFactoryDiscovery::find()->createRequest?

It is not specifically mentioned in the documentation, but IIRC the discovery classes contain docblock about the returned types. MessageFactoryDiscovery returns a MessageFactory which you can use to create messages. While discoveries has caching builtin, I suggest storing the discovered object internally in your class, so that you only have to call the discovery once.

and what is the uri factory for?

IIRC @ddeboer created that one, he specifically needed that and I had nothing to say against it.

the MessageFactory accepts a string as well (the doc is incorrect btw, it should state that it can also accept an UriInterface)

No, it is on purpose. The factory accepts string as well so you can create your request object directly without the need for creating an Uri object first. The other reason it is there is that every PSR-7 implementation differs: one accepts string in it's constructor, another doesn't. This tries to make it consistent: each accepts everything.

I think I answered all your questions. If you feel a PR is still necessary or you think you can improve the docs so that other people won't have to ask these questions again, please feel free to submit a PR.

[dbu]

The usage of discoveries is covered in the general
http://php-http.readthedocs.org/en/latest/discovery/#general section.

ah, right. hm but that is rather abstract to read. i will try to do a PR
with a little usage tutorial.

the MessageFactory accepts a string as well (the doc is incorrect
btw, it should state that it can also accept an UriInterface)

No, it is on purpose. The factory accepts string as well so you can
create your request object directly without the need for creating an Uri
object first. The other reason it is there is that every PSR-7
implementation differs: one accepts string in it's constructor, another
doesn't. This tries to make it consistent: each accepts everything.

okay, the doc mistake was in guzzle psr7 Request:
guzzle/psr7#35

[sagikazarmark]

Looking at the docs, there are code examples about using the specific discoveries as well:

http://php-http.readthedocs.org/en/latest/discovery/#http-adapter-discovery

Thank you for contributing!