php-http / documentation Goto Github PK
View Code? Open in Web Editor NEWDocumentation for PHP-HTTP including HTTPlug
Home Page: http://docs.php-http.org
License: MIT License
Documentation for PHP-HTTP including HTTPlug
Home Page: http://docs.php-http.org
License: MIT License
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
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
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:
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
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.
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:
I think we can make an exception in case of plugins and move plugin documentation to the plugin repo.
Advantages:
see #30
see #30
I think plugin namespace is Http\Client\Plugin
Discovery, message factories can cause a complex dependency tree.
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.
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
see #30
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.