Merge pull request #73 from php-http/phpdoc

cleanup phpdoc and BatchResult interface

Author: dbu

spec/Exception/RequestExceptionSpec.php

@@ -27,18 +27,4 @@ function it_has_a_request(RequestInterface $request)
     {
         $this->getRequest()->shouldReturn($request);
     }
-
-    function it_wraps_an_exception(RequestInterface $request)
-    {
-        $e = new \Exception('message');
-
-        $requestException = $this->wrapException($request, $e);
-
-        $requestException->getMessage()->shouldReturn('message');
-    }
-
-    function it_does_not_wrap_if_request_exception(RequestInterface $request, RequestException $requestException)
-    {
-        $this->wrapException($request, $requestException)->shouldReturn($requestException);
-    }
 }

spec/Exception/TransferExceptionSpec.php

@@ -2,14 +2,14 @@
 
 namespace spec\Http\Client\Exception;
 
+use Http\Client\Exception\TransferException;
 use PhpSpec\ObjectBehavior;
-use Prophecy\Argument;
 
 class TransferExceptionSpec extends ObjectBehavior
 {
-    function it_is_initializable()
+    function let()
     {
-        $this->shouldHaveType('Http\Client\Exception\TransferException');
+        $this->beAnInstanceOf('spec\Http\Client\Exception\TransferExceptionStub');
     }
 
     function it_is_a_runtime_exception()
@@ -22,3 +22,7 @@ function it_is_an_exception()
         $this->shouldImplement('Http\Client\Exception');
     }
 }
+
+class TransferExceptionStub extends TransferException
+{
+}

src/BatchResult.php

@@ -13,6 +13,13 @@
  */
 interface BatchResult
 {
+    /**
+     * Checks if there are any successful responses at all.
+     *
+     * @return boolean
+     */
+    public function hasResponses();
+
     /**
      * Returns all successful responses.
      *
@@ -21,31 +28,24 @@ interface BatchResult
     public function getResponses();
 
     /**
-     * Returns the response for a successful request.
+     * Checks if there is a successful response for a request.
      *
      * @param RequestInterface $request
      *
-     * @return ResponseInterface
-     *
-     * @throws \UnexpectedValueException If request was not part of the batch or failed.
-     */
-    public function getResponseFor(RequestInterface $request);
-
-    /**
-     * Checks if there are any successful responses at all
-     *
      * @return boolean
      */
-    public function hasResponses();
+    public function isSuccessful(RequestInterface $request);
 
     /**
-     * Checks if there is a successful response for a request.
+     * Returns the response for a successful request.
      *
      * @param RequestInterface $request
      *
      * @return ResponseInterface
+     *
+     * @throws \UnexpectedValueException If request was not part of the batch or failed.
      */
-    public function hasResponseFor(RequestInterface $request);
+    public function getResponseFor(RequestInterface $request);
 
     /**
      * Adds a response in an immutable way.
@@ -58,22 +58,11 @@ public function hasResponseFor(RequestInterface $request);
     public function addResponse(RequestInterface $request, ResponseInterface $response);
 
     /**
-     * Checks if a request was successful.
-     *
-     * @param RequestInterface $request
-     *
-     * @return boolean
-     */
-    public function isSuccessful(RequestInterface $request);
-
-    /**
-     * Checks if a request has failed.
-     *
-     * @param RequestInterface $request
+     * Checks if there are any unsuccessful requests at all.
      *
      * @return boolean
      */
-    public function isFailed(RequestInterface $request);
+    public function hasExceptions();
 
     /**
      * Returns all exceptions for the unsuccessful requests.
@@ -83,24 +72,24 @@ public function isFailed(RequestInterface $request);
     public function getExceptions();
 
     /**
-     * Returns the exception for a failed request.
+     * Checks if there is an exception for a request, meaning the request failed.
      *
      * @param RequestInterface $request
      *
-     * @return Exception
-     *
-     * @throws \UnexpectedValueException If request was not part of the batch or was successful.
+     * @return boolean
      */
-    public function getExceptionFor(RequestInterface $request);
+    public function isFailed(RequestInterface $request);
 
     /**
-     * Checks if there is an exception for a request.
+     * Returns the exception for a failed request.
      *
      * @param RequestInterface $request
      *
-     * @return boolean
+     * @return Exception
+     *
+     * @throws \UnexpectedValueException If request was not part of the batch or was successful.
      */
-    public function hasExceptionFor(RequestInterface $request);
+    public function getExceptionFor(RequestInterface $request);
 
     /**
      * Adds an exception in an immutable way.

src/Exception.php

@@ -3,7 +3,7 @@
 namespace Http\Client;
 
 /**
- * Every HTTP Client related Exception should implement this interface
+ * Every HTTP Client related Exception must implement this interface
  *
  * @author Márk Sági-Kazár <[email protected]>
  */

src/Exception/BatchException.php

@@ -6,13 +6,13 @@
 use Http\Client\Exception;
 
 /**
- * This exception is thrown when a batch of requests led to at least one failure.
+ * This exception is thrown when HttpClient::sendRequests led to at least one failure.
  *
- * It holds the response/exception pairs and gives access to a BatchResult with the successful responses.
+ * It gives access to a BatchResult with the request-exception and request-response pairs.
  *
  * @author Márk Sági-Kazár <[email protected]>
  */
-final class BatchException extends \RuntimeException implements Exception
+final class BatchException extends TransferException implements Exception
 {
     /**
      * @var BatchResult

src/Exception/HttpException.php

@@ -8,7 +8,7 @@
 /**
  * Thrown when a response was received but has an error status code.
  *
- * This exception always provides the request and response objects.
+ * In addition to the request, this exception always provides access to the response object.
  *
  * @author Márk Sági-Kazár <[email protected]>
  */
@@ -31,11 +31,10 @@ public function __construct(
         ResponseInterface $response,
         \Exception $previous = null
     ) {
+        parent::__construct($message, $request, $previous);
+
         $this->response = $response;
         $this->code = $response->getStatusCode();
-
-
-        parent::__construct($message, $request, $previous);
     }
 
     /**

src/Exception/NetworkException.php

@@ -3,7 +3,9 @@
 namespace Http\Client\Exception;
 
 /**
- * Thrown when the request cannot be completed caused by network issues
+ * Thrown when the request cannot be completed because of network issues.
+ *
+ * There is no response object as this exception is thrown when no response has been received.
  *
  * @author Márk Sági-Kazár <[email protected]>
  */

src/Exception/RequestException.php

@@ -5,7 +5,10 @@
 use Psr\Http\Message\RequestInterface;
 
 /**
- * Base exception for when a request failed.
+ * Exception for when a request failed, providing access to the failed request.
+ *
+ * This could be due to an invalid request, or one of the extending exceptions
+ * for network errors or HTTP error responses.
  *
  * @author Márk Sági-Kazár <[email protected]>
  */
@@ -37,19 +40,4 @@ public function getRequest()
     {
         return $this->request;
     }
-
-    /**
-     * @param RequestInterface $request
-     * @param \Exception       $e
-     *
-     * @return RequestException
-     */
-    public static function wrapException(RequestInterface $request, \Exception $e)
-    {
-        if (!$e instanceof RequestException) {
-            $e = new RequestException($e->getMessage(), $request, $e);
-        }
-
-        return $e;
-    }
 }

src/Exception/TransferException.php

@@ -9,6 +9,6 @@
  *
  * @author Márk Sági-Kazár <[email protected]>
  */
-class TransferException extends \RuntimeException implements Exception
+abstract class TransferException extends \RuntimeException implements Exception
 {
 }

src/HttpClient.php

@@ -16,7 +16,7 @@
 interface HttpClient
 {
     /**
-     * Sends a PSR request
+     * Sends a PSR-7 request.
      *
      * @param RequestInterface $request
      *
@@ -27,17 +27,20 @@ interface HttpClient
     public function sendRequest(RequestInterface $request);
 
     /**
-     * Sends PSR requests
+     * Sends several PSR-7 requests.
      *
-     * If one or more requests led to an exception, the BatchException is thrown.
-     * The BatchException also gives access to the BatchResult for the successful responses.
+     * If the client is able to, these requests should be sent in parallel. Otherwise they will be sent sequentially.
+     * Either way, the caller may not rely on them being executed in any particular order.
+     *
+     * If one or more requests led to an exception, the BatchException is thrown. The BatchException gives access to the
+     * BatchResult that contains responses for successful calls and exceptions for unsuccessful calls.
      *
      * @param RequestInterface[] $requests
      *
      * @return BatchResult If all requests where successful.
      *
-     * @throws Exception
-     * @throws BatchException
+     * @throws Exception      On general setup problems.
+     * @throws BatchException If one or more requests led to exceptions.
      */
     public function sendRequests(array $requests);
 }