Add plugin documentation

[joelwurtz]

See php-http/plugins#3

Don't know if we need to provide documentation of each plugin here, or if we can do it in another pull request ?

[sagikazarmark]

In general: the correct form is aN HTTP Client.

[sagikazarmark]

I think plugin docs can go into this PR.

[joelwurtz]

Ok this PR is based on a branch directly on this repo, if some people want to help to contribute on one of the plugin documentation you are welcome :)

[sagikazarmark]

Will do

[dbu]

s/allow/allows/

[dbu]

though "manipulate" is a bit misleading, as they are immutable. should we say "to look at requests and responses and replace them if needed"?

[dbu]

very interesting to read how the plugins work! i commented a lot of details, hope you don't mind joel.

process: i suggest we wrap up the main section and then merge without each plugin description already in. otherwise we might wait for quite a while until making this available. will also be easier to review the individual plugin docs in separate pull requests

plugins: how would a cache plugin work? it would simply not call $next but return the response as a promise, right?
what about something like the redirect plugin, it has to call $first, right? if a plugin wants to work with the response, it has to wait on the promise, right? and if it cares about exceptions (e.g. logging) it has to try-catch as well and rethrow?

[joelwurtz]

very interesting to read how the plugins work! i commented a lot of details, hope you don't mind joel.

Quite the opposite thanks for the remarks.

process: i suggest we wrap up the main section and then merge without each plugin description already in. otherwise we might wait for quite a while until making this available. will also be easier to review the individual plugin docs in separate pull requests

👍

plugins: how would a cache plugin work? it would simply not call $next but return the response as a promise, right?

Exactly, or return the exception as the promise if an error happens

what about something like the redirect plugin, it has to call $first, right?

Yes that exaclty what it's done actually see : https://github.com/php-http/plugins/blob/master/src/RedirectPlugin.php

if a plugin wants to work with the response, it has to wait on the promise, right?

No it's just call the then method to add behavior when the response is resolved, see the CookiePlugin for example : https://github.com/php-http/plugins/blob/master/src/CookiePlugin.php

However there is some case when you need to wait for the promise when you have an underlying request by example (like in the RetryPlugin or RedirectPlugin)

and if it cares about exceptions (e.g. logging) it has to try-catch as well and rethrow?

No it's simply define the second callable of the then method which allow to handle the exception, but you must rethrow the exception inside this callable (and not return, otherwise it will consider the exception like it was the Response and put in the next onFulfilled callable)

[dbu]

ah, still new to promises. makes a lot of sense. can you maybe integrate your answers into the documentation to make things more clear? i guess i am not the only one not familiar with promises, so having more details could help. maybe we should move the "write your own plugin" into its own chapter inside the plugins/ folder. in a way, its the least important, coming after using the existing plugins. it would be cool to show the core code of plugins to explain cases:

• alter a request
• alter a response
• prematurely end a request with a synthetic response (cache, vcr, mocking)
• start a new request and return that result instead
• abort a request prematurely with an error
• abort a response with an error (Error plugin, or for example server validation fails)

[sagikazarmark]

I am new to promises as well, so expect a few dumb questions @joelwurtz 😜

[joelwurtz]

So all things should be good unless there is still remarks ?

[dbu]

=> When you inject an array of plugins into the PluginClient, the order of the plugins matters.

otherwise the phrase is repeating itself

[dbu]

i have a few more grammatical comments, otherwise this looks ready to merge to me.
i will try to do #31, looking at the existing plugins and if necessary asking you questions. then i will learn about promises...