From 328676e3d499c28bbd4fe6708475b96ea84c82a0 Mon Sep 17 00:00:00 2001 From: David de Boer Date: Mon, 4 Jan 2016 21:54:11 +0100 Subject: [PATCH 1/2] Document exceptions --- httplug/exceptions.rst | 20 ++++++++++++++++++++ index.rst | 1 + 2 files changed, 21 insertions(+) create mode 100644 httplug/exceptions.rst diff --git a/httplug/exceptions.rst b/httplug/exceptions.rst new file mode 100644 index 0000000..3421d01 --- /dev/null +++ b/httplug/exceptions.rst @@ -0,0 +1,20 @@ +Exceptions +========== + +HTTPlug defines one Exception interface: ``Http\Client\Exception``. All HTTP +client exceptions must implement this interface. + +``HttpClient::sendRequest()`` can throw one of the following exceptions. + +================================== ====================== =================== +Exception Thrown when Methods available +================================== ====================== =================== +TransferException ??? +└ RequestException the request is invalid ``getRequest()`` + |nbsp| |nbsp| └ NetworkException no response received + due to network issues ``getRequest()`` + |nbsp| |nbsp| └ HttpException error response ``getRequest()`` + ``getResponse()`` +================================== ====================== =================== + +.. |nbsp| unicode:: U+00A0 .. non-breaking space 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 From d0f1145efa8cf0692fb2d30aac2d7f7d4c63ac3d Mon Sep 17 00:00:00 2001 From: David Buchmann Date: Wed, 2 Mar 2016 09:07:06 +0100 Subject: [PATCH 2/2] cleanup exception doc --- components/promise.rst | 3 +++ httplug/exceptions.rst | 28 +++++++++++++++++----------- httplug/introduction.rst | 1 + 3 files changed, 21 insertions(+), 11 deletions(-) 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 index 3421d01..77a58d6 100644 --- a/httplug/exceptions.rst +++ b/httplug/exceptions.rst @@ -1,20 +1,26 @@ Exceptions ========== -HTTPlug defines one Exception interface: ``Http\Client\Exception``. All HTTP -client exceptions must implement this interface. +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 ??? -└ RequestException the request is invalid ``getRequest()`` +================================== ============================= =================== +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()`` -================================== ====================== =================== + 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 ---------------