Skip to content

Merge HTTPlug intro and re-group TOC #65

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jan 3, 2016
Merged

Merge HTTPlug intro and re-group TOC #65

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
95fed70
Merge HTTPlug intro and re-group TOC
ddeboer Jan 3, 2016
b4a7cf3
Restructure usage chapters
ddeboer Jan 3, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion clients.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,9 @@ Clients & Adapters
There are clients implementing one of the HTTPlug interfaces directly,
and adapter packages that implement the interface and forward the calls to HTTP clients not implementing the interface.

TODO
.. _`php-http/client-implementation`: https://packagist.org/providers/php-http/client-implementation
.. _`php-http/async-client-implementation`: https://packagist.org/providers/php-http/async-client-implementation:


Clients:

Expand Down
1 change: 1 addition & 0 deletions conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -301,4 +301,5 @@
rst_epilog = """
.. _PSR-7: http://www.php-fig.org/psr/psr-7
.. _Composer: https://getcomposer.org
.. _HttplugBundle: https://github.com/php-http/HttplugBundle
"""
29 changes: 0 additions & 29 deletions httplug.rst
View file
Open in desktop

This file was deleted.

77 changes: 43 additions & 34 deletions httplug/introduction.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,32 +1,48 @@
Introduction to HTTPlug
=======================
HTTPlug: HTTP client abstraction
================================

HTTPlug implementations
-----------------------
HTTPlug allows you to write reusable libraries and applications that need
an HTTP client without binding to a specific implementation.
When all packages used in an application only specify HTTPlug,
the application developers can choose the client that best fits their project
and use the same client with all packages.

The client interfaces
---------------------

HTTPlug defines two HTTP client interfaces that we kept as simple as possible:

* ``HttpClient`` defines a ``sendRequest`` method that sends a PSR-7
``RequestInterface`` and either returns a PSR-7 ``ResponseInterface`` or
throws an exception that implements ``Http\Client\Exception``.

* ``HttpAsyncClient`` defines a ``sendAsyncRequest`` method that sends a request
asynchronously and always returns a ``Http\Client\Promise``.

HTTPlug implementations typically are either HTTP clients of their own, or adapters wrapping existing clients
like Guzzle 6. In the latter case, they will depend on the required client implementation,
so you only need to require the adapter and not the actual client.
Implementations
---------------

PHP-HTTP offers two types of clients that implement the above interfaces:

There are two kind of implementations:
1. Standalone clients that directly implement the interfaces.

- `php-http/client-implementation`_:
the synchronous implementation that waits for the response / error before returning from the ``sendRequest`` method.
Examples: :doc:`/clients/curl-client` and :doc:`/clients/socket-client`.

- `php-http/async-client-implementation`_:
the asynchronous implementation that immediately returns a ``Http\Promise\Promise``,
allowing to send several requests in parallel and handling responses later.
2. Adapters that wrap existing HTTP client, such as Guzzle. These adapters act
as a bridge between the HTTPlug interfaces and the clients that do not (yet)
implement these interfaces.

Check links above for the full list of implementations.
Examples: :doc:`/clients/guzzle6-adapter` and :doc:`/clients/react-adapter`.

.. _`php-http/client-implementation`: https://packagist.org/providers/php-http/client-implementation
.. _`php-http/async-client-implementation`: https://packagist.org/providers/php-http/async-client-implementation:
.. note::

Ideally, all HTTP client libraries out there will implement the HTTPlug
interfaces. At that point, our adapters will no longer be necessary.

Usage in an application
-----------------------

When writing an application, you need to require a concrete implementation_.
When writing an application, you need to require a concrete implementation.

See :doc:`virtual-package` for more information on the topic of working with HTTPlug implementations.

Expand Down Expand Up @@ -69,27 +85,20 @@ Best point them to the :doc:`virtual-package` page.
To be able to send requests, you should not depend on a specific PSR-7 implementation,
but use the :ref:`message-factory` system.

Framework Integration
^^^^^^^^^^^^^^^^^^^^^

HTTPlug can be used in any PHP based project.
Nonetheless, we provide particular integration for some popular frameworks:

- HttplugBundle_: integration with the Symfony framework.

History
-------

This project has been started by `Eric Geloen`_ as `Ivory Http Adapter`_. It never made it to a stable release,
but it relied on PSR-7 which was not stable either that time. Because of the constantly changing PSR-7,
Eric had to rewrite the library over and over again (at least the message handling part,
which in most cases affected every adapter as well).
This project has been started by `Eric Geloen`_ as `Ivory Http Adapter`_. It
never made it to a stable release, but it relied on PSR-7 which was not stable
either that time. Because of the constantly changing PSR-7, Eric had to rewrite
the library over and over again (at least the message handling part, which in
most cases affected every adapter as well).

In 2015, a decision has been made to move the library to its own organization, so PHP HTTP was born.
In 2015, a decision has been made to move the library to its own organization,
so PHP-HTTP was born.

See :doc:`migrating` for a guide how to migrate your code from the Ivory adapter to HTTPlug.
See :doc:`migrating` for a guide how to migrate your code from the Ivory
adapter.

.. _implementation: https://packagist.org/providers/php-http/client-implementation
.. _HttplugBundle: https://github.com/php-http/HttplugBundle
.. _`Eric Geloen`: https://github.com/egeloen
.. _`Ivory Http Adapter`: https://github.com/egeloen/ivory-http-adapter).
.. _`Ivory Http Adapter`: https://github.com/egeloen/ivory-http-adapter
17 changes: 17 additions & 0 deletions httplug/usage.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
Usage
=====

HTTPlug is an abstraction for HTTP clients. There are two main use cases:

1. Usage in a project/application
2. Usage in a reusable package


Framework Integration
^^^^^^^^^^^^^^^^^^^^^

HTTPlug can be used in any PHP based project.
Nonetheless, we provide particular integration for some popular frameworks:

- HttplugBundle_: integration with the Symfony framework.

26 changes: 9 additions & 17 deletions index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,17 +29,7 @@ HTTPlug abstracts from HTTP clients written in PHP, offering a simple interface.
It also provides an implementation-independent plugin system to build pipelines
regardless of the HTTP client implementation used.

HTTPlug allows you to write reusable libraries and applications that need
an HTTP client without binding to a specific implementation.
When all packages used in an application only specify HTTPlug,
the application developers can choose the client that best fits their project
and use the same client with all packages.

There are clients implementing one of the HTTPlug interfaces directly,
and adapter packages that implement the interface and forward the calls to HTTP
clients not implementing the interface.

Get started by reading our :doc:`tutorial </httplug/tutorial>`.
Read more about :doc:`HTTPlug </httplug/introduction>`.

Packages
--------
Expand All @@ -64,17 +54,19 @@ for discussion around a future HTTP client PSR.

.. toctree::
:hidden:
:maxdepth: 3

PHP-HTTP <self>

.. toctree::
:hidden:

HTTPlug <httplug>

.. toctree::
:hidden:
:caption: HTTPlug
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i split out the overview from the introduction to avoid having this label with no link behind it. i would prefer to not have titles in the toc that dont link to anything. and currently httplug chapters are grouped together, this pr puts them on the same level as clients or plugins.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, these are group captions (in subdued grey), not links. I changed this to show right away the Introduction, Usage and Tutorial links, which to me makes a lot of sense for doc readers.

:maxdepth: 4

Introduction <httplug/introduction>
Usage <httplug/usage>
Tutorial <httplug/tutorial>
Migrating <httplug/migrating>
Virtual package <httplug/virtual-package>

clients
plugins/index
Expand Down