From 276ad242eeabc7be07b31ee90c75f3de4183f862 Mon Sep 17 00:00:00 2001 From: Zebulan Stanphill Date: Wed, 13 Oct 2021 00:31:51 -0500 Subject: [PATCH 1/2] Fix some missing or inaccurate return/throw types. --- src/Api/Attachment.php | 9 +++++++-- src/Api/EmailValidationV4.php | 4 +--- src/Api/HttpApi.php | 5 +++-- src/Assert.php | 6 +++++- src/Exception/HttpClientException.php | 16 ++++++++-------- src/Exception/HttpServerException.php | 6 +++--- src/HttpClient/Plugin/History.php | 7 ++----- src/HttpClient/RequestBuilder.php | 7 ++++++- src/Hydrator/ArrayHydrator.php | 4 ++-- src/Hydrator/ModelHydrator.php | 1 + src/Hydrator/NoopHydrator.php | 1 + src/Message/Exceptions/LimitExceeded.php | 2 +- .../Exceptions/MissingRequiredParameter.php | 2 +- src/Message/Exceptions/TooManyRecipients.php | 4 ++-- src/Model/EmailValidation/Parts.php | 5 +---- src/Model/Event/EventResponse.php | 2 +- src/Model/Ip/IndexResponse.php | 2 +- src/Model/Ip/ShowResponse.php | 2 +- src/Model/Ip/UpdateResponse.php | 2 +- src/Model/MailingList/PagesResponse.php | 5 +---- src/Model/Route/Action.php | 4 ++-- 21 files changed, 51 insertions(+), 45 deletions(-) diff --git a/src/Api/Attachment.php b/src/Api/Attachment.php index 09bc10f8..bedee5eb 100644 --- a/src/Api/Attachment.php +++ b/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.+@'); diff --git a/src/Api/EmailValidationV4.php b/src/Api/EmailValidationV4.php index 01c8d9ad..e22b09c2 100755 --- a/src/Api/EmailValidationV4.php +++ b/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); diff --git a/src/Api/HttpApi.php b/src/Api/HttpApi.php index 884deb7e..145f7e4f 100644 --- a/src/Api/HttpApi.php +++ b/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) { diff --git a/src/Assert.php b/src/Assert.php index 19c1b7fa..984fa28b 100644 --- a/src/Assert.php +++ b/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); } diff --git a/src/Exception/HttpClientException.php b/src/Exception/HttpClientException.php index f073f7ba..506d2af1 100644 --- a/src/Exception/HttpClientException.php +++ b/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')) { diff --git a/src/Exception/HttpServerException.php b/src/Exception/HttpServerException.php index b0d7c225..d2049120 100644 --- a/src/Exception/HttpServerException.php +++ b/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)); } diff --git a/src/HttpClient/Plugin/History.php b/src/HttpClient/Plugin/History.php index 4ef27dd4..47be983b 100644 --- a/src/HttpClient/Plugin/History.php +++ b/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; } diff --git a/src/HttpClient/RequestBuilder.php b/src/HttpClient/RequestBuilder.php index 827ad5fc..d180ff01 100644 --- a/src/HttpClient/RequestBuilder.php +++ b/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); diff --git a/src/Hydrator/ArrayHydrator.php b/src/Hydrator/ArrayHydrator.php index 806b7d9c..b73e83fa 100644 --- a/src/Hydrator/ArrayHydrator.php +++ b/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')) { diff --git a/src/Hydrator/ModelHydrator.php b/src/Hydrator/ModelHydrator.php index d58cca05..a51e9f2b 100644 --- a/src/Hydrator/ModelHydrator.php +++ b/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) diff --git a/src/Hydrator/NoopHydrator.php b/src/Hydrator/NoopHydrator.php index 869ef6fa..76a39e32 100644 --- a/src/Hydrator/NoopHydrator.php +++ b/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) { diff --git a/src/Message/Exceptions/LimitExceeded.php b/src/Message/Exceptions/LimitExceeded.php index fae151dc..c0fd0b4d 100644 --- a/src/Message/Exceptions/LimitExceeded.php +++ b/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)); } diff --git a/src/Message/Exceptions/MissingRequiredParameter.php b/src/Message/Exceptions/MissingRequiredParameter.php index a4925f1c..79eb8ef9 100644 --- a/src/Message/Exceptions/MissingRequiredParameter.php +++ b/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".'; diff --git a/src/Message/Exceptions/TooManyRecipients.php b/src/Message/Exceptions/TooManyRecipients.php index 29f47a3f..4cf1f55f 100644 --- a/src/Message/Exceptions/TooManyRecipients.php +++ b/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)); } diff --git a/src/Model/EmailValidation/Parts.php b/src/Model/EmailValidation/Parts.php index 97146dd1..72958789 100644 --- a/src/Model/EmailValidation/Parts.php +++ b/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; diff --git a/src/Model/Event/EventResponse.php b/src/Model/Event/EventResponse.php index 66ddab34..05ed9520 100644 --- a/src/Model/Event/EventResponse.php +++ b/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'])) { diff --git a/src/Model/Ip/IndexResponse.php b/src/Model/Ip/IndexResponse.php index 104f7e93..2cb4ed39 100644 --- a/src/Model/Ip/IndexResponse.php +++ b/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']; diff --git a/src/Model/Ip/ShowResponse.php b/src/Model/Ip/ShowResponse.php index 46b4de4e..1d85090a 100644 --- a/src/Model/Ip/ShowResponse.php +++ b/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']; diff --git a/src/Model/Ip/UpdateResponse.php b/src/Model/Ip/UpdateResponse.php index 2258f270..8b348883 100644 --- a/src/Model/Ip/UpdateResponse.php +++ b/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']; diff --git a/src/Model/MailingList/PagesResponse.php b/src/Model/MailingList/PagesResponse.php index 8cee9d6c..52476b33 100644 --- a/src/Model/MailingList/PagesResponse.php +++ b/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 = []; diff --git a/src/Model/Route/Action.php b/src/Model/Route/Action.php index 3cced6ae..b764f6c7 100644 --- a/src/Model/Route/Action.php +++ b/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 = []; From 054994cdb5cb5f8d5bac286cb6d35019be06091c Mon Sep 17 00:00:00 2001 From: Zebulan Stanphill Date: Wed, 13 Oct 2021 09:20:36 -0500 Subject: [PATCH 2/2] Fix issues caught by static analysis tests. --- src/Api/Attachment.php | 8 +++----- src/Api/HttpApi.php | 1 + src/Assert.php | 3 +++ src/HttpClient/RequestBuilder.php | 3 +-- src/Hydrator/ModelHydrator.php | 1 + src/Hydrator/NoopHydrator.php | 1 + src/Message/Exceptions/LimitExceeded.php | 2 +- src/Message/Exceptions/TooManyRecipients.php | 4 ++-- 8 files changed, 13 insertions(+), 10 deletions(-) diff --git a/src/Api/Attachment.php b/src/Api/Attachment.php index bedee5eb..5bc8ec1a 100644 --- a/src/Api/Attachment.php +++ b/src/Api/Attachment.php @@ -12,11 +12,9 @@ namespace Mailgun\Api; use Mailgun\Assert; -use Mailgun\Exception\{ - HttpClientException, - HttpServerException, - UnknownErrorException -}; +use Mailgun\Exception\HttpClientException; +use Mailgun\Exception\HttpServerException; +use Mailgun\Exception\UnknownErrorException; use Psr\Http\Message\ResponseInterface; /** diff --git a/src/Api/HttpApi.php b/src/Api/HttpApi.php index 145f7e4f..9b489579 100644 --- a/src/Api/HttpApi.php +++ b/src/Api/HttpApi.php @@ -82,6 +82,7 @@ protected function hydrateResponse(ResponseInterface $response, string $class) * Throw the correct exception for this error. * * @throws HttpClientException|HttpServerException|UnknownErrorException + * * @return never */ protected function handleErrors(ResponseInterface $response): void diff --git a/src/Assert.php b/src/Assert.php index 984fa28b..c37c0a37 100644 --- a/src/Assert.php +++ b/src/Assert.php @@ -21,7 +21,10 @@ final class Assert extends \Webmozart\Assert\Assert { /** + * @psalm-pure + * * @throws InvalidArgumentException + * * @return never */ protected static function reportInvalidArgument($message): void diff --git a/src/HttpClient/RequestBuilder.php b/src/HttpClient/RequestBuilder.php index d180ff01..924d1651 100644 --- a/src/HttpClient/RequestBuilder.php +++ b/src/HttpClient/RequestBuilder.php @@ -130,8 +130,7 @@ private function createRequest( string $uri, array $headers, StreamInterface $stream - ): RequestInterface - { + ): RequestInterface { $request = $this->getRequestFactory()->createRequest($method, $uri); $request = $request->withBody($stream); foreach ($headers as $name => $value) { diff --git a/src/Hydrator/ModelHydrator.php b/src/Hydrator/ModelHydrator.php index a51e9f2b..fd0c2d66 100644 --- a/src/Hydrator/ModelHydrator.php +++ b/src/Hydrator/ModelHydrator.php @@ -26,6 +26,7 @@ final class ModelHydrator implements Hydrator * @param class-string $class * * @throws HydrationException + * * @return ResponseInterface */ public function hydrate(ResponseInterface $response, string $class) diff --git a/src/Hydrator/NoopHydrator.php b/src/Hydrator/NoopHydrator.php index 76a39e32..6b8a0467 100644 --- a/src/Hydrator/NoopHydrator.php +++ b/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) diff --git a/src/Message/Exceptions/LimitExceeded.php b/src/Message/Exceptions/LimitExceeded.php index c0fd0b4d..fae151dc 100644 --- a/src/Message/Exceptions/LimitExceeded.php +++ b/src/Message/Exceptions/LimitExceeded.php @@ -15,7 +15,7 @@ class LimitExceeded extends \Exception implements Exception { - public static function create(string $field, int $limit): self + public static function create(string $field, int $limit) { return new self(sprintf('You\'ve exceeded the maximum (%d) %s for a single message.', $limit, $field)); } diff --git a/src/Message/Exceptions/TooManyRecipients.php b/src/Message/Exceptions/TooManyRecipients.php index 4cf1f55f..29f47a3f 100644 --- a/src/Message/Exceptions/TooManyRecipients.php +++ b/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): self + public static function create(string $field, int $limit = MessageBuilder::RECIPIENT_COUNT_LIMIT) { 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): self + public static function whenAutoSendDisabled(int $limit = MessageBuilder::RECIPIENT_COUNT_LIMIT) { return new self(sprintf('You\'ve exceeded the maximum recipient count (%s) with autosend disabled.', $limit)); }