diff --git a/components/promise.rst b/components/promise.rst index 04a92c8..acb5a97 100644 --- a/components/promise.rst +++ b/components/promise.rst @@ -74,5 +74,8 @@ executed if the request results in an error:: } ); +The ``$exception`` of the failure callback SHOULD implement ``Http\Client\Exception``. +See :doc:`../httplug/exceptions` for more information on the exception classes you might encounter. + .. _`Promise PSR`: https://groups.google.com/forum/?fromgroups#!topic/php-fig/wzQWpLvNSjs .. _Promises/A+: https://promisesaplus.com diff --git a/httplug/exceptions.rst b/httplug/exceptions.rst new file mode 100644 index 0000000..77a58d6 --- /dev/null +++ b/httplug/exceptions.rst @@ -0,0 +1,26 @@ +Exceptions +========== + +HTTPlug defines a common interface for all exceptions thrown by HTTPlug implementations. +Every exception thrown by a HTTP client must implement ``Http\Client\Exception``. + +``HttpClient::sendRequest()`` can throw one of the following exceptions. + +================================== ============================= =================== +Exception Thrown when Methods available +================================== ============================= =================== +TransferException something unexpected happened - +└ RequestException the request is invalid ``getRequest()`` + |nbsp| |nbsp| └ NetworkException no response received + due to network issues ``getRequest()`` + |nbsp| |nbsp| └ HttpException error response ``getRequest()`` + ``getResponse()`` +================================== ============================= =================== + +.. note:: + + The ``sendAsyncRequest`` should never throw an exception but always return a + :doc:`../components/promise`. The exception classes used in ``Promise::wait`` and the ``then`` + callback are however the same as explained here. + +.. |nbsp| unicode:: U+00A0 .. non-breaking space diff --git a/httplug/introduction.rst b/httplug/introduction.rst index 9708fb3..fcc5dc1 100644 --- a/httplug/introduction.rst +++ b/httplug/introduction.rst @@ -18,6 +18,7 @@ HTTPlug defines two HTTP client interfaces that we kept as simple as possible: * ``HttpAsyncClient`` defines a ``sendAsyncRequest`` method that sends a request asynchronously and always returns a ``Http\Client\Promise``. + See :doc:`../components/promise` for more information. Implementations --------------- diff --git a/index.rst b/index.rst index 7051bc3..d48f19f 100644 --- a/index.rst +++ b/index.rst @@ -65,6 +65,7 @@ for discussion around a future HTTP client PSR. Introduction Usage + Exceptions Tutorial Migrating