php-http / documentation Goto Github PK

http://docs.httplug.io/en/latest/httplug/#usage-in-a-project
http://docs.httplug.io/en/latest/virtual-package/

Hey.
I know there is a lot going on right now. I've been watching all of this repositories for a while and Im still not 100% sure what all of the does and which one is deprecated or not.

I (and possibly many other new developers to this project) would appreciate a table of each repository and a short description of the current status and purpose.

Document functionality added in php-http/plugins#18

/cc @joelwurtz

most important is explaining in what situation which exception will be thrown and that everything ever thrown implements Http\Client\Exception.

Hierarchy is the following

\InvalidArgumentException
`- \Http\Client\Exception\InvalidArgumentException (implements \Http\Client\Exception)

\RuntimeException
`- \Http\Client\Exception\RuntimeException (implements \Http\Client\Exception)
   `- \Http\Client\Exception\TransferException
      |- \Http\Client\Exception\BatchException
      `- \Http\Client\Exception\RequestException
         |- \Http\Client\Exception\NetworkException
         `- \Http\Client\Exception\HttpException
            |- \Http\Client\Exception\ServerException
            `- \Http\Client\Exception\ClientException

https://github.com/php-http/buzz-adapter

We have a page describing auto discovery for library developers. I get the feeling that this page is not targeting the end developer, the one that is using the auto discovery service.

I think I'm missing a page that says:

To make everything work our of the box you need Puli. Install Puli like this... If you get an error like "no factories" you need to install http-php/message ... etc etc.

Related to https://github.com/florianv/swap/pull/26/files#r55143439

• Request matcher
• AutoBasic auth

on the start page, we list some php-http packages. the choice which ones to highlight is a bit random. i would propose we highlight the following:

• Httplug
• Message Factory
• Plugins
• Utilities

which would mean adding plugins and dropping discovery. i think plugins is of more general interest than discovery - discovery is a very opinionated tool that some people will hate and many won't need. plugins is a direct added value on top of independence from a specific client implementation.

Do we want to use phpDocumentor?

@mekras raised the idea.

Honestly, I am not sure it is even possible given that the project is separated into several repos, but would be nice to have.

document the BatchClient, BatchResponse and BatchException concept added in php-http/utils#16

see #30

document functionality added in php-http/plugins#15

/cc @Nyholm

See php-http/HttplugBundle#84 and php-http/HttplugBundle#87

Document the new configuration options added in php-http/HttplugBundle#83

Imo adding this to the config reference is good enough.

The sendResponses method return a batch result. User can retrieve response and/or exception with the getResponseFor / getExceptionFor.

If the request is updated in the sendRequests method and this transformed request is used to index the response / exception in the batch result user wil never retrieve the result.

IMO we should add a line for implementation client saying that they must used the original request to index the response / exception.

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.

the plugin system needs to be documented once its implemented.

for the discussion, see php-http/message-factory#13

document how to use the message factory.

we need to be sure of the target audience. what does a consumer of a generic library want to know? what does a library author want to know? implementation reasoning beyond that is only relevant for php-http contributors. we might create a page in the doc for that, also with the reasoning you explained on slack today:

From the three package (httplug, promise, message-factory) you actually need to require one, possibly two
httplug is required
message-factory is recommended, if you want to support multiple message implementations
For example in case of guzzle you probably don’t need it
promise is required by httplug, you don’t need to explicitly required
now comes the reasoning
We decided to decouple promise from the main package so that it is easier to decouple when a PSR or a sane standard is created
we just have to deprecate our own and require the standard (with a major version change)
we just need to rewrite some docblocks, but the contract does not really change in this case
also, the promise package is used to create some promise helpers in the client -utils package without requireing httplug
The message factory contract should actually be required by the message implementations
I am already preparing a PR to guzzle/psr7 to use our message factory interfaces. In case of diactoros it is much harder as it would introduce some BC breaks
Also, message factory is purely PSR-7 related, not httplug
from a reusable library point of view, httplug is your only dependency, it is the client implementation’s decision whether it wants to support multiple message implementations through message factories or just one

document some of the proposals and ideas from php-http/plugins#43

(and maybe also collect examples of libraries using HTTPlug to give people concrete use cases to look at)

We now have both

http://docs.httplug.io/en/latest/
and
http://docs.php-http.org/en/latest/

That’s rather confusing for users. Assuming that we keep all docs in one repository, which URL do we prefer? I’d say the latter makes most sense.

@dbu just said this on slack:

"the goal is that all clients behave the same so you can switch them without nasty surprises"

I do not think we mention that in the documentation. I think we should say something like:

"The clients/adapters comply with Liskov substitution principle, which means that you are free to switch them in and out without experiencing any nasty surprises"

Is MIT good for documentation License as well? I regularly see Creative Commons and other licenses.

is there already a symfony bundle for php-http that either uses the locator or can be configured to an explicit client adapter / message factory?

should the documentation be markdown or reStructured text?

rst would have the advantage of more flexible formatting and styling and things like cross-linking in a nice and clean way. i can offer to transform the existing doc to rst if we want to go that way.

@dbu

i am still new to promises. lets integrate the answers of #30 (comment) 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)

I think we can make an exception in case of plugins and move plugin documentation to the plugin repo.

Advantages:

• Plugins is a large portion of HTTPlug which requires large documentation. This way the core documentation can be kept smaller
• We can serve plugins under http://plugins.httplug.io (Downside: if we ever decide to have a fancy plugin registry, we can't serve it there, or at least we are forced to do it in the documentation)
• We can keep documentation in the same repo. Unlike HTTPlug, plugins is not a contract which allows us a more frequent release cycle.

see #30

see #30

I think plugin namespace is Http\Client\Plugin

Discovery, message factories can cause a complex dependency tree.

See php-http/httplug#104

the message factory documentation is outdated.

and we should explain how to get those factories, e.g. with a diactoros example. the client doc references http://php-http.readthedocs.org/en/latest/message/message-factory.html , we should explain how to make sure one of the factories actually is installed, list known implementations and so on.

I think most people fear from breaking BC. I absolutely agree with them, that's why I think we should recommend them a two step migration.

1. Use HTTPlug internally, don't change the public API. In most cases this is a simple constructor injection of an HTTP Client. We could just wrap this around one of our adapter and use HTTPlug API internally.
2. Once the author is confident that the package is stable and HTTPlug works, he can change the public API as well, fully decoupling the package from the actual implementation.

Have a FAQ which list common error / exception message with a small explanation and links to other documentations related

With php-http/discovery#34 coming, we should update the documentation.

while reading the current discovery doc, i wonder whether the "discovery" class needs to be in a specific namespace or anything or if its automatically discoverd. or are only guzzle 5, 6 and dactilos automatically discovered and other adapters must be registered manually to be found?

The http://php-http.org/ link in the repo description points to a Gandi page saying that the domain is registered. This should rather point to the library documentation

see #30

the tutorial added in #10 started the outline for a tutorial. work this out and solve the TODOs

we promise information for library developers in the intro, but never come to that point.

So we can be sure that PRs don’t break them.

see #30

I don't know why, but RTD works weird with our mkdocs architecture. Github links don't work at all.

I was doing some research, but haven't found anything.

Here is an article about RTD and mkdocs and it works fine there:

http://www.sitepoint.com/building-product-documentation-mkdocs/

I also found an article explaining how to use sphinx for MD. It would allow us to generate PDFs as well.

http://searchvoidstar.tumblr.com/post/125486358368/making-pdfs-from-markdown-on-readthedocsorg-using

https://github.com/ericholscher/sphinx-markdown-test/

see #30

• HttpClient instead of HttpPsrClient and HttpMethodsClient
• Utilities for HttpMethodsClient
• Client instead of Adapter
• httplug composer package name