Fix some missing or inaccurate return/throw types.

Author: ZebulanStanphill

src/Api/Attachment.php

@@ -12,6 +12,11 @@
 namespace Mailgun\Api;
 
 use Mailgun\Assert;
+use Mailgun\Exception\{
+    HttpClientException,
+    HttpServerException,
+    UnknownErrorException
+};
 use Psr\Http\Message\ResponseInterface;
 
 /**
@@ -20,9 +25,9 @@
 class Attachment extends HttpApi
 {
     /**
-     * @return ResponseInterface
+     * @throws HttpClientException|HttpServerException|UnknownErrorException
      */
-    public function show(string $url)
+    public function show(string $url): ResponseInterface
     {
         Assert::stringNotEmpty($url);
         Assert::regex($url, '@https://.*mailgun\.(net|org)/v.+@');

src/Api/EmailValidationV4.php

@@ -199,10 +199,8 @@ public function getBulkPreview(string $previewId)
 
     /**
      * @param string $previewId ID given when the list created
-     *
-     * @return bool
      */
-    public function deleteBulkPreview(string $previewId)
+    public function deleteBulkPreview(string $previewId): bool
     {
         Assert::stringNotEmpty($previewId);
 

src/Api/HttpApi.php

@@ -81,9 +81,10 @@ protected function hydrateResponse(ResponseInterface $response, string $class)
     /**
      * Throw the correct exception for this error.
      *
-     * @throws \Exception
+     * @throws HttpClientException|HttpServerException|UnknownErrorException
+     * @return never
      */
-    protected function handleErrors(ResponseInterface $response)
+    protected function handleErrors(ResponseInterface $response): void
     {
         $statusCode = $response->getStatusCode();
         switch ($statusCode) {

src/Assert.php

@@ -20,7 +20,11 @@
  */
 final class Assert extends \Webmozart\Assert\Assert
 {
-    protected static function reportInvalidArgument($message)
+    /**
+     * @throws InvalidArgumentException
+     * @return never
+     */
+    protected static function reportInvalidArgument($message): void
     {
         throw new InvalidArgumentException($message);
     }

src/Exception/HttpClientException.php

@@ -48,7 +48,7 @@ public function __construct(string $message, int $code, ResponseInterface $respo
         }
     }
 
-    public static function badRequest(ResponseInterface $response)
+    public static function badRequest(ResponseInterface $response): self
     {
         $body = $response->getBody()->__toString();
         if (0 !== strpos($response->getHeaderLine('Content-Type'), 'application/json')) {
@@ -63,37 +63,37 @@ public static function badRequest(ResponseInterface $response)
         return new self($message, 400, $response);
     }
 
-    public static function unauthorized(ResponseInterface $response)
+    public static function unauthorized(ResponseInterface $response): self
     {
         return new self('Your credentials are incorrect.', 401, $response);
     }
 
-    public static function requestFailed(ResponseInterface $response)
+    public static function requestFailed(ResponseInterface $response): self
     {
         return new self('Parameters were valid but request failed. Try again.', 402, $response);
     }
 
-    public static function notFound(ResponseInterface $response)
+    public static function notFound(ResponseInterface $response): self
     {
         return new self('The endpoint you have tried to access does not exist. Check if the domain matches the domain you have configure on Mailgun.', 404, $response);
     }
 
-    public static function conflict(ResponseInterface $response)
+    public static function conflict(ResponseInterface $response): self
     {
         return new self('Request conflicts with current state of the target resource.', 409, $response);
     }
 
-    public static function payloadTooLarge(ResponseInterface $response)
+    public static function payloadTooLarge(ResponseInterface $response): self
     {
         return new self('Payload too large, your total attachment size is too big.', 413, $response);
     }
 
-    public static function tooManyRequests(ResponseInterface $response)
+    public static function tooManyRequests(ResponseInterface $response): self
     {
         return new self('Too many requests.', 429, $response);
     }
 
-    public static function forbidden(ResponseInterface $response)
+    public static function forbidden(ResponseInterface $response): self
     {
         $body = $response->getBody()->__toString();
         if (0 !== strpos($response->getHeaderLine('Content-Type'), 'application/json')) {

src/Exception/HttpServerException.php

@@ -18,17 +18,17 @@
  */
 final class HttpServerException extends \RuntimeException implements Exception
 {
-    public static function serverError(int $httpStatus = 500)
+    public static function serverError(int $httpStatus = 500): self
     {
         return new self('An unexpected error occurred at Mailgun\'s servers. Try again later and contact support if the error still exists.', $httpStatus);
     }
 
-    public static function networkError(\Throwable $previous)
+    public static function networkError(\Throwable $previous): self
     {
         return new self('Mailgun\'s servers are currently unreachable.', 0, $previous);
     }
 
-    public static function unknownHttpResponseCode(int $code)
+    public static function unknownHttpResponseCode(int $code): self
     {
         return new self(sprintf('Unknown HTTP response code ("%d") received from the API server', $code));
     }

src/HttpClient/Plugin/History.php

@@ -28,15 +28,12 @@ final class History implements Journal
      */
     private $lastResponse;
 
-    /**
-     * @return ResponseInterface|null
-     */
-    public function getLastResponse()
+    public function getLastResponse(): ?ResponseInterface
     {
         return $this->lastResponse;
     }
 
-    public function addSuccess(RequestInterface $request, ResponseInterface $response)
+    public function addSuccess(RequestInterface $request, ResponseInterface $response): void
     {
         $this->lastResponse = $response;
     }

src/HttpClient/RequestBuilder.php

@@ -125,7 +125,12 @@ public function setMultipartStreamBuilder(MultipartStreamBuilder $multipartStrea
         return $this;
     }
 
-    private function createRequest(string $method, string $uri, array $headers, StreamInterface $stream)
+    private function createRequest(
+        string $method,
+        string $uri,
+        array $headers,
+        StreamInterface $stream
+    ): RequestInterface
     {
         $request = $this->getRequestFactory()->createRequest($method, $uri);
         $request = $request->withBody($stream);

src/Hydrator/ArrayHydrator.php

@@ -24,9 +24,9 @@ final class ArrayHydrator implements Hydrator
     /**
      * @param class-string $class
      *
-     * @return array
+     * @throws HydrationException
      */
-    public function hydrate(ResponseInterface $response, string $class)
+    public function hydrate(ResponseInterface $response, string $class): array
     {
         $body = $response->getBody()->__toString();
         if (0 !== strpos($response->getHeaderLine('Content-Type'), 'application/json')) {

src/Hydrator/ModelHydrator.php

@@ -25,6 +25,7 @@ final class ModelHydrator implements Hydrator
     /**
      * @param class-string $class
      *
+     * @throws HydrationException
      * @return ResponseInterface
      */
     public function hydrate(ResponseInterface $response, string $class)

src/Hydrator/NoopHydrator.php

@@ -24,6 +24,7 @@ final class NoopHydrator implements Hydrator
      * @param class-string $class
      *
      * @throws \LogicException
+     * @return never
      */
     public function hydrate(ResponseInterface $response, string $class)
     {

src/Message/Exceptions/LimitExceeded.php

@@ -15,7 +15,7 @@
 
 class LimitExceeded extends \Exception implements Exception
 {
-    public static function create(string $field, int $limit)
+    public static function create(string $field, int $limit): self
     {
         return new self(sprintf('You\'ve exceeded the maximum (%d) %s for a single message.', $limit, $field));
     }

src/Message/Exceptions/MissingRequiredParameter.php

@@ -15,7 +15,7 @@
 
 class MissingRequiredParameter extends \Exception implements Exception
 {
-    public static function create(string $parameter, string $message = null)
+    public static function create(string $parameter, string $message = null): self
     {
         if (null === $message) {
             $message = 'The parameters passed to the API were invalid. Please specify "%s".';

src/Message/Exceptions/TooManyRecipients.php

@@ -16,12 +16,12 @@
 
 class TooManyRecipients extends LimitExceeded implements Exception
 {
-    public static function create(string $field, int $limit = MessageBuilder::RECIPIENT_COUNT_LIMIT)
+    public static function create(string $field, int $limit = MessageBuilder::RECIPIENT_COUNT_LIMIT): self
     {
         return new self(sprintf('You\'ve exceeded the maximum recipient count (%s) for filed "%s".', $limit, $field));
     }
 
-    public static function whenAutoSendDisabled(int $limit = MessageBuilder::RECIPIENT_COUNT_LIMIT)
+    public static function whenAutoSendDisabled(int $limit = MessageBuilder::RECIPIENT_COUNT_LIMIT): self
     {
         return new self(sprintf('You\'ve exceeded the maximum recipient count (%s) with autosend disabled.', $limit));
     }

src/Model/EmailValidation/Parts.php

@@ -35,10 +35,7 @@ private function __construct()
     {
     }
 
-    /**
-     * @return Parts
-     */
-    public static function create(array $data)
+    public static function create(array $data): self
     {
         $model = new self();
         $model->displayName = $data['display_name'] ?? null;

src/Model/Event/EventResponse.php

@@ -27,7 +27,7 @@ private function __construct()
     {
     }
 
-    public static function create(array $data)
+    public static function create(array $data): self
     {
         $events = [];
         if (isset($data['items'])) {

src/Model/Ip/IndexResponse.php

@@ -37,7 +37,7 @@ private function __construct()
     {
     }
 
-    public static function create(array $data)
+    public static function create(array $data): self
     {
         $model = new self();
         $model->items = $data['items'];

src/Model/Ip/ShowResponse.php

@@ -26,7 +26,7 @@ private function __construct()
     {
     }
 
-    public static function create(array $data)
+    public static function create(array $data): self
     {
         $model = new self();
         $model->ip = $data['ip'];

src/Model/Ip/UpdateResponse.php

@@ -24,7 +24,7 @@ private function __construct()
     {
     }
 
-    public static function create(array $data)
+    public static function create(array $data): self
     {
         $model = new self();
         $model->message = $data['message'];

src/Model/MailingList/PagesResponse.php

@@ -21,10 +21,7 @@ final class PagesResponse implements ApiResponse, PagingProvider
 
     private $items;
 
-    /**
-     * @return self
-     */
-    public static function create(array $data)
+    public static function create(array $data): self
     {
         $items = [];
 

src/Model/Route/Action.php

@@ -21,9 +21,9 @@ final class Action
     /**
      * Action Named Constructor to build several Action DTOs provided by an Array.
      *
-     * @return Action[]
+     * @return self[]
      */
-    public static function createMultiple(array $data)
+    public static function createMultiple(array $data): array
     {
         $items = [];