Minor cleanup, adding comments and renaming properties (#353)

* Minor cleanup

* Added docs

* Added some more comments

* Comments

* cs

Author: Nyholm

src/AbstractApi.php

@@ -21,7 +21,7 @@
 use Symfony\Contracts\HttpClient\HttpClientInterface;
 
 /**
- * Base class most APIs are inheriting.
+ * Base class all API clients are inheriting.
  *
  * @author Tobias Nyholm <[email protected]>
  * @author Jérémy Derussé <[email protected]>

src/Response.php

@@ -25,20 +25,21 @@
  */
 class Response
 {
-    private $response;
+    private $httpResponse;
 
     private $httpClient;
 
     /**
      * A Result can be resolved many times. This variable contains the last resolve result.
+     * Null means that the result has never been resolved.
      *
      * @var bool|NetworkException|HttpException|null
      */
     private $resolveResult;
 
     public function __construct(ResponseInterface $response, HttpClientInterface $httpClient)
     {
-        $this->response = $response;
+        $this->httpResponse = $response;
         $this->httpClient = $httpClient;
     }
 
@@ -52,7 +53,8 @@ public function __destruct()
     /**
      * Make sure the actual request is executed.
      *
-     * @param float|null $timeout Duration in seconds before aborting. When null wait until the end of execution.
+     * @param float|null $timeout Duration in seconds before aborting. When null wait
+     *                            until the end of execution. Using 0 means non-blocking
      *
      * @return bool whether the request is executed or not
      *
@@ -74,7 +76,7 @@ public function resolve(?float $timeout = null): bool
         }
 
         try {
-            foreach ($this->httpClient->stream($this->response, $timeout) as $chunk) {
+            foreach ($this->httpClient->stream($this->httpResponse, $timeout) as $chunk) {
                 if ($chunk->isTimeout()) {
                     return false;
                 }
@@ -83,21 +85,21 @@ public function resolve(?float $timeout = null): bool
                 }
             }
 
-            $statusCode = $this->response->getStatusCode();
+            $statusCode = $this->httpResponse->getStatusCode();
         } catch (TransportExceptionInterface $e) {
             throw $this->resolveResult = new NetworkException('Could not contact remote server.', 0, $e);
         }
 
         if (500 <= $statusCode) {
-            throw $this->resolveResult = new ServerException($this->response);
+            throw $this->resolveResult = new ServerException($this->httpResponse);
         }
 
         if (400 <= $statusCode) {
-            throw $this->resolveResult = new ClientException($this->response);
+            throw $this->resolveResult = new ClientException($this->httpResponse);
         }
 
         if (300 <= $statusCode) {
-            throw $this->resolveResult = new RedirectionException($this->response);
+            throw $this->resolveResult = new RedirectionException($this->httpResponse);
         }
 
         return $this->resolveResult = true;
@@ -116,45 +118,45 @@ public function info(): array
     {
         return [
             'resolved' => null !== $this->resolveResult,
-            'response' => $this->response,
-            'status' => (int) $this->response->getInfo('http_code'),
+            'response' => $this->httpResponse,
+            'status' => (int) $this->httpResponse->getInfo('http_code'),
         ];
     }
 
     public function cancel(): void
     {
-        $this->response->cancel();
+        $this->httpResponse->cancel();
         $this->resolveResult = false;
     }
 
     public function getHeaders(): array
     {
         $this->resolve();
 
-        return $this->response->getHeaders(false);
+        return $this->httpResponse->getHeaders(false);
     }
 
     public function getContent(): string
     {
         $this->resolve();
 
-        return $this->response->getContent(false);
+        return $this->httpResponse->getContent(false);
     }
 
     public function toArray(): array
     {
         $this->resolve();
 
-        return $this->response->toArray(false);
+        return $this->httpResponse->toArray(false);
     }
 
     public function getStatusCode(): int
     {
-        return $this->response->getStatusCode();
+        return $this->httpResponse->getStatusCode();
     }
 
     public function toStream(): ResultStream
     {
-        return new ResponseBodyStream($this->httpClient->stream($this->response));
+        return new ResponseBodyStream($this->httpClient->stream($this->httpResponse));
     }
 }

src/Result.php

@@ -26,9 +26,6 @@ class Result
 
     protected $initialized = false;
 
-    /**
-     * @var Response
-     */
     private $response;
 
     /**

src/Waiter.php

@@ -122,6 +122,8 @@ final public function getState(): string
      *
      * @param float|null $timeout Duration in seconds before aborting. When null wait until the end of execution.
      *
+     * @return bool false on timeout. True if the response has returned with as status code.
+     *
      * @throws NetworkException
      */
     final public function resolve(?float $timeout = null): bool
@@ -159,6 +161,8 @@ final public function cancel(): void
      *
      * @param float $timeout Duration in seconds before aborting
      * @param float $delay   Duration in seconds between each check
+     *
+     * @return bool true if a final state was reached
      */
     final public function wait(float $timeout = null, float $delay = null): bool
     {
@@ -167,19 +171,21 @@ final public function wait(float $timeout = null, float $delay = null): bool
 
         $start = \microtime(true);
         while (true) {
+            // If request times out
             if (!$this->resolve($timeout - (\microtime(true) - $start))) {
                 break;
             }
 
-            switch ($this->getState()) {
-                case self::STATE_SUCCESS:
-                case self::STATE_FAILURE:
-                    return true;
+            // If we reached a final state
+            if (\in_array($this->getState(), [self::STATE_SUCCESS, self::STATE_FAILURE])) {
+                return true;
             }
 
+            // If the timeout will expire during our sleep, then exit early.
             if ($delay > $timeout - (\microtime(true) - $start)) {
                 break;
             }
+
             \usleep((int) ceil($delay * 1000000));
             $this->stealResponse($this->refreshState());
         }