De 1004 review and test pr mailinglist members pagination

src/Api/Attachment.php

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

src/Api/Domain.php

@@ -43,11 +43,13 @@ class Domain extends HttpApi
 
     /**
      * Returns a list of domains on the account.
-     *
+     * @param  int                      $limit
+     * @param  int                      $skip
      * @return IndexResponse
      * @throws ClientExceptionInterface
+     * @throws Exception
      */
-    public function index(int $limit = 100, int $skip = 0)
+    public function index(int $limit = 100, int $skip = 0): IndexResponse
     {
         Assert::range($limit, 1, 1000);
 
@@ -82,19 +84,16 @@ public function show(string $domain)
      * Creates a new domain for the account.
      * See below for spam filtering parameter information.
      * {@link https://documentation.mailgun.com/user_manual.html#um-spam-filter}.
-     *
      * @see https://documentation.mailgun.com/en/latest/api-domains.html#domains
-     *
-     * @param string   $domain             name of the domain
-     * @param string   $smtpPass           password for SMTP authentication
-     * @param string   $spamAction         `disable` or `tag` - inbound spam filtering
-     * @param bool     $wildcard           domain will accept email for subdomains
-     * @param bool     $forceDkimAuthority force DKIM authority
-     * @param string[] $ips                an array of ips to be assigned to the domain
-     * @param ?string  $pool_id            pool id to assign to the domain
-     * @param string   $webScheme          `http` or `https` - set your open, click and unsubscribe URLs to use http or https. The default is http
-     * @param string   $dkimKeySize        Set length of your domain’s generated DKIM key
-     *
+     * @param  string                                 $domain             name of the domain
+     * @param  string|null                            $smtpPass           password for SMTP authentication
+     * @param  string|null                            $spamAction         `disable` or `tag` - inbound spam filtering
+     * @param  bool                                   $wildcard           domain will accept email for subdomains
+     * @param  bool                                   $forceDkimAuthority force DKIM authority
+     * @param  string[]                               $ips                an array of ips to be assigned to the domain
+     * @param  ?string                                $pool_id            pool id to assign to the domain
+     * @param  string                                 $webScheme          `http` or `https` - set your open, click and unsubscribe URLs to use http or https. The default is http
+     * @param  string                                 $dkimKeySize        Set length of your domain’s generated DKIM key
      * @return CreateResponse|array|ResponseInterface
      * @throws Exception
      */

src/Api/EmailValidation.php

@@ -17,6 +17,7 @@
 use Mailgun\Exception\InvalidArgumentException;
 use Mailgun\Model\EmailValidation\ParseResponse;
 use Mailgun\Model\EmailValidation\ValidateResponse;
+use Psr\Http\Client\ClientExceptionInterface;
 use Psr\Http\Message\ResponseInterface;
 
 /**
@@ -28,18 +29,15 @@ class EmailValidation extends HttpApi
 {
     /**
      * Addresses are validated based off defined checks.
-     *
      * This operation is only accessible with the private API key and not subject to the daily usage limits.
-     *
-     * @param string $address             An email address to validate. Maximum: 512 characters.
-     * @param bool   $mailboxVerification If set to true, a mailbox verification check will be performed
-     *                                    against the address. The default is False.
-     *
+     * @param  string                              $address             An email address to validate. Maximum: 512 characters.
+     * @param  bool                                $mailboxVerification If set to true, a mailbox verification check will be performed
+     *                                                                  against the address. The default is False.
      * @return ValidateResponse|ResponseInterface
-     * @throws InvalidArgumentException           Thrown when local validation returns an error
-     * @throws HttpClientException                Thrown when there's an error on Client side
-     * @throws HttpServerException                Thrown when there's an error on Server side
-     * @throws \Exception                         Thrown when we don't catch a Client or Server side Exception
+     * @throws InvalidArgumentException            Thrown when local validation returns an error
+     * @throws HttpClientException                 Thrown when there's an error on Client side
+     * @throws HttpServerException                 Thrown when there's an error on Server side
+     * @throws \Exception|ClientExceptionInterface Thrown when we don't catch a Client or Server side Exception
      */
     public function validate(string $address, bool $mailboxVerification = false)
     {
@@ -73,10 +71,10 @@ public function validate(string $address, bool $mailboxVerification = false)
      *                           The default is True.
      *
      * @return ParseResponse|ResponseInterface
-     * @throws InvalidArgumentException        Thrown when local validation returns an error
-     * @throws HttpClientException             Thrown when there's an error on Client side
-     * @throws HttpServerException             Thrown when there's an error on Server side
-     * @throws \Exception                      Thrown when we don't catch a Client or Server side Exception
+     * @throws InvalidArgumentException            Thrown when local validation returns an error
+     * @throws HttpClientException                 Thrown when there's an error on Client side
+     * @throws HttpServerException                 Thrown when there's an error on Server side
+     * @throws \Exception|ClientExceptionInterface Thrown when we don't catch a Client or Server side Exception
      */
     public function parse(string $addresses, bool $syntaxOnly = true)
     {

src/Api/EmailValidationV4.php

@@ -22,6 +22,7 @@
 use Mailgun\Model\EmailValidationV4\GetBulkPreviewsResponse;
 use Mailgun\Model\EmailValidationV4\PromoteBulkPreviewResponse;
 use Mailgun\Model\EmailValidationV4\ValidateResponse;
+use Psr\Http\Client\ClientExceptionInterface;
 use Psr\Http\Message\ResponseInterface;
 
 /**
@@ -31,13 +32,10 @@ class EmailValidationV4 extends HttpApi
 {
     /**
      * Addresses are validated based off defined checks.
-     *
-     * @param string $address        An email address to validate. Maximum: 512 characters.
-     * @param bool   $providerLookup A provider lookup will be performed if Mailgun’s internal analysis is insufficient
-     *
+     * @param  string                             $address        An email address to validate. Maximum: 512 characters.
+     * @param  bool                               $providerLookup A provider lookup will be performed if Mailgun’s internal analysis is insufficient
      * @return ValidateResponse|ResponseInterface
-     *
-     * @throws Exception Thrown when we don't catch a Client or Server side Exception
+     * @throws Exception|ClientExceptionInterface Thrown when we don't catch a Client or Server side Exception
      */
     public function validate(string $address, bool $providerLookup = true)
     {
@@ -54,12 +52,10 @@ public function validate(string $address, bool $providerLookup = true)
     }
 
     /**
-     * @param string $listId   ID given when the list created
-     * @param mixed  $filePath File path or file content
-     *
+     * @param  string                             $listId   ID given when the list created
+     * @param  mixed                              $filePath File path or file content
      * @return mixed|ResponseInterface
-     *
-     * @throws Exception
+     * @throws Exception|ClientExceptionInterface
      */
     public function createBulkJob(string $listId, $filePath)
     {
@@ -84,11 +80,9 @@ public function createBulkJob(string $listId, $filePath)
     }
 
     /**
-     * @param string $listId ID given when the list created
-     *
+     * @param  string                                  $listId ID given when the list created
      * @return DeleteBulkJobResponse|ResponseInterface
-     *
-     * @throws Exception
+     * @throws Exception|ClientExceptionInterface
      */
     public function deleteBulkJob(string $listId)
     {
@@ -116,11 +110,9 @@ public function getBulkJob(string $listId)
     }
 
     /**
-     * @param int $limit Jobs limit
-     *
+     * @param  int                                   $limit Jobs limit
      * @return GetBulkJobsResponse|ResponseInterface
-     *
-     * @throws Exception
+     * @throws Exception|ClientExceptionInterface
      */
     public function getBulkJobs(int $limit = 500)
     {
@@ -134,11 +126,9 @@ public function getBulkJobs(int $limit = 500)
     }
 
     /**
-     * @param int $limit Previews Limit
-     *
+     * @param  int                                $limit Previews Limit
      * @return mixed|ResponseInterface
-     *
-     * @throws Exception
+     * @throws Exception|ClientExceptionInterface
      */
     public function getBulkPreviews(int $limit = 500)
     {
@@ -152,12 +142,10 @@ public function getBulkPreviews(int $limit = 500)
     }
 
     /**
-     * @param string $previewId ID given when the list created
-     * @param mixed  $filePath  File path or file content
-     *
+     * @param  string                             $previewId ID given when the list created
+     * @param  mixed                              $filePath  File path or file content
      * @return mixed|ResponseInterface
-     *
-     * @throws Exception
+     * @throws Exception|ClientExceptionInterface
      */
     public function createBulkPreview(string $previewId, $filePath)
     {
@@ -182,11 +170,9 @@ public function createBulkPreview(string $previewId, $filePath)
     }
 
     /**
-     * @param string $previewId ID given when the list created
-     *
+     * @param  string                             $previewId ID given when the list created
      * @return mixed|ResponseInterface
-     *
-     * @throws Exception
+     * @throws Exception|ClientExceptionInterface
      */
     public function getBulkPreview(string $previewId)
     {
@@ -198,11 +184,11 @@ public function getBulkPreview(string $previewId)
     }
 
     /**
-     * @param string $previewId ID given when the list created
-     *
+     * @param  string                   $previewId ID given when the list created
      * @return bool
+     * @throws ClientExceptionInterface
      */
-    public function deleteBulkPreview(string $previewId)
+    public function deleteBulkPreview(string $previewId): bool
     {
         Assert::stringNotEmpty($previewId);
 
@@ -212,11 +198,9 @@ public function deleteBulkPreview(string $previewId)
     }
 
     /**
-     * @param string $previewId ID given when the list created
-     *
+     * @param  string                             $previewId ID given when the list created
      * @return mixed|ResponseInterface
-     *
-     * @throws Exception
+     * @throws Exception|ClientExceptionInterface
      */
     public function promoteBulkPreview(string $previewId)
     {
@@ -235,19 +219,19 @@ public function promoteBulkPreview(string $previewId)
      */
     private function prepareFile(string $fieldName, array $filePath): array
     {
-        $filename = isset($filePath['filename']) ? $filePath['filename'] : null;
+        $filename = $filePath['filename'] ?? null;
 
         $resource = null;
 
         if (isset($filePath['fileContent'])) {
             // File from memory
-            $resource = fopen('php://temp', 'r+');
+            $resource = fopen('php://temp', 'rb+');
             fwrite($resource, $filePath['fileContent']);
             rewind($resource);
         } elseif (isset($filePath['filePath'])) {
             // File form path
             $path = $filePath['filePath'];
-            $resource = fopen($path, 'r');
+            $resource = fopen($path, 'rb');
         }
 
         return [

src/Api/Event.php

@@ -13,6 +13,7 @@
 
 use Mailgun\Assert;
 use Mailgun\Model\Event\EventResponse;
+use Psr\Http\Client\ClientExceptionInterface;
 
 /**
  * @see https://documentation.mailgun.com/en/latest/api-events.html
@@ -24,7 +25,10 @@ class Event extends HttpApi
     use Pagination;
 
     /**
+     * @param  string                   $domain
+     * @param  array                    $params
      * @return EventResponse
+     * @throws ClientExceptionInterface
      */
     public function get(string $domain, array $params = [])
     {

src/Api/HttpApi.php

@@ -11,6 +11,7 @@
 
 namespace Mailgun\Api;
 
+use Exception;
 use Mailgun\Exception\HttpClientException;
 use Mailgun\Exception\HttpServerException;
 use Mailgun\Exception\UnknownErrorException;
@@ -63,7 +64,7 @@ public function __construct($httpClient, RequestBuilder $requestBuilder, Hydrato
      *
      * @return mixed|ResponseInterface
      *
-     * @throws \Exception
+     * @throws Exception
      */
     protected function hydrateResponse(ResponseInterface $response, string $class)
     {
@@ -81,9 +82,9 @@ protected function hydrateResponse(ResponseInterface $response, string $class)
     /**
      * Throw the correct exception for this error.
      *
-     * @throws \Exception
+     * @throws Exception|UnknownErrorException
      */
-    protected function handleErrors(ResponseInterface $response)
+    protected function handleErrors(ResponseInterface $response): void
     {
         $statusCode = $response->getStatusCode();
         switch ($statusCode) {
@@ -137,10 +138,10 @@ protected function httpGet(string $path, array $parameters = [], array $requestH
 
     /**
      * Send a POST request with parameters.
-     *
-     * @param string $path           Request path
-     * @param array  $parameters     POST parameters
-     * @param array  $requestHeaders Request headers
+     * @param  string                   $path           Request path
+     * @param  array                    $parameters     POST parameters
+     * @param  array                    $requestHeaders Request headers
+     * @throws ClientExceptionInterface
      */
     protected function httpPost(string $path, array $parameters = [], array $requestHeaders = []): ResponseInterface
     {

src/Api/HttpClient.php

@@ -65,10 +65,11 @@ public function httpGet(string $path, array $parameters = [], array $requestHead
     }
 
     /**
-     * @param  string            $path
-     * @param  array             $parameters
-     * @param  array             $requestHeaders
+     * @param  string                   $path
+     * @param  array                    $parameters
+     * @param  array                    $requestHeaders
      * @return ResponseInterface
+     * @throws ClientExceptionInterface
      */
     public function httpPost(string $path, array $parameters = [], array $requestHeaders = []): ResponseInterface
     {