Explicit creation and deletion of a temporary file

Method `::configure` replaced by a constructor

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 The change log describes what is "Added", "Removed", "Changed" or "Fixed" between each release.
 
-## 3.0.0 - UNRELEASED
+## 3.0.0
 
 ### Added
 
@@ -18,7 +18,13 @@ The change log describes what is "Added", "Removed", "Changed" or "Fixed" betwee
 
 ### Removed
 
-- Dependency on `php-http/message`.
+- Dependency on `php-http/message`. 
+
+### [Unreleased]
+
+- API v4 Email Validation; please use US Servers with your public key instead
+(please check the Issues [617](https://github.com/mailgun/mailgun-php/issues/617)
+and [619](https://github.com/mailgun/mailgun-php/issues/619) for further details)
 
 ## 2.8.1
 

README.md

@@ -1,10 +1,8 @@
 # Mailgun PHP client
 
-This is the Mailgun PHP SDK. This SDK contains methods for easily interacting 
-with the Mailgun API. 
-Below are examples to get you started. For additional examples, please see our 
-official documentation 
-at http://documentation.mailgun.com
+This is the Mailgun PHP SDK. This SDK contains methods for easily interacting
+with the Mailgun API. Below are examples to get you started. For additional
+examples, please see our official documentation at http://documentation.mailgun.com
 
 [![Latest Version](https://img.shields.io/github/release/mailgun/mailgun-php.svg?style=flat-square)](https://github.com/mailgun/mailgun-php/releases)
 [![Build Status](https://img.shields.io/travis/mailgun/mailgun-php/master.svg?style=flat-square)](https://travis-ci.org/mailgun/mailgun-php)
@@ -24,9 +22,11 @@ composer:
 curl -sS https://getcomposer.org/installer | php
 ```
 
-The Mailgun api client is not hard coupled to Guzzle or any other library that sends
-HTTP messages. It uses the [PSR-18](https://www.php-fig.org/psr/psr-18/) client abstraction.
-This will give you the flexibilty to choose what PSR-7 implementation and HTTP client to use. 
+The Mailgun API Client is not hard coupled to Guzzle, Buzz or any other library that sends
+HTTP messages. Instead, it uses the [PSR-18](https://www.php-fig.org/psr/psr-18/) client abstraction.
+This will give you the flexibility to choose what
+[PSR-7 implementation and HTTP client](https://packagist.org/providers/php-http/client-implementation)
+you want to use. 
 
 If you just want to get started quickly you should run the following command: 
 
@@ -36,7 +36,7 @@ composer require mailgun/mailgun-php kriswallsmith/buzz nyholm/psr7
 
 ## Usage
 
-You should always use Composer's autoloader in your application to automatically load
+You should always use Composer autoloader in your application to automatically load
 your dependencies. All the examples below assume you've already included this in your
 file:
 
@@ -66,7 +66,7 @@ Attention: `$domain` must match to the domain you have configured on [app.mailgu
 
 ### All usage examples
 
-You find more detailed documentation at [/doc](doc/index.md) and on 
+You will find more detailed documentation at [/doc](doc/index.md) and on 
 [https://documentation.mailgun.com](https://documentation.mailgun.com/api_reference.html).
 
 ### Response
@@ -93,7 +93,7 @@ use Mailgun\Hydrator\ArrayHydrator;
 $configurator = new HttpClientConfigurator();
 $configurator->setApiKey('key-example');
 
-$mg = Mailgun::configure($configurator, new ArrayHydrator());
+$mg = new Mailgun($configurator, new ArrayHydrator());
 $data = $mg->domains()->show('example.com');
 
 foreach ($data['receiving_dns_records'] as $record) {
@@ -108,12 +108,12 @@ the API calls.
 
 ### Debugging
 
-Debugging the PHP SDK can be really helpful when things aren't working quite right. 
+Debugging the PHP SDK can be helpful when things aren't working quite right. 
 To debug the SDK, here are some suggestions: 
 
-Set the endpoint to Mailgun's Postbin. A Postbin is a web service that allows you to 
-post data, which is then displayed through a browser. This allows you to quickly determine
-what is actually being transmitted to Mailgun's API. 
+Set the endpoint to Mailgun's Postbin. A Postbin is a web service that allows you to
+post data, which then you can display it through a browser. Using Postbin is an easy way
+to quickly determine what data you're transmitting to Mailgun's API.
 
 **Step 1 - Create a new Postbin.**  
 Go to http://bin.mailgun.net. The Postbin will generate a special URL. Save that URL. 
@@ -121,13 +121,13 @@ Go to http://bin.mailgun.net. The Postbin will generate a special URL. Save that
 **Step 2 - Instantiate the Mailgun client using Postbin.**  
 
 *Tip: The bin id will be the URL part after bin.mailgun.net. It will be random generated letters and numbers. 
-For example, the bin id in this URL, http://bin.mailgun.net/aecf68de, is "aecf68de".*
+For example, the bin id in this URL (http://bin.mailgun.net/aecf68de) is `aecf68de`.*
 
 ```php
 $configurator = new HttpClientConfigurator();
 $configurator->setEndpoint('http://bin.mailgun.net/aecf68de');
 $configurator->setDebug(true);
-$mg = Mailgun::configure($configurator);
+$mg = new Mailgun($configurator);
 
 # Now, compose and send your message.
 $mg->messages()->send('example.com', [
@@ -163,8 +163,10 @@ If you are using a framework you might consider these composer packages to make
 
 ## Contribute
 
-We are currently building a new object oriented API client. Feel free to contribute in any way. As an example you may: 
-* Trying out dev-master the code
+This SDK is an Open Source under the MIT license. It is, thus, maintained by collaborators and contributors.
+
+Feel free to contribute in any way. As an example you may: 
+* Trying out the `dev-master` code
 * Create issues if you find problems
 * Reply to other people's issues
 * Review PRs

src/Api/Domain.php

@@ -88,16 +88,25 @@ class Domain extends HttpApi
 
         $params['name'] = $domain;
 
-        // If at least smtpPass available, check for the fields spamAction wildcard
         if (!empty($smtpPass)) {
-            // TODO(sean.johnson): Extended spam filter input validation.
-            Assert::stringNotEmpty($spamAction);
-            Assert::boolean($wildcard);
+            Assert::stringNotEmpty($smtpPass);
 
             $params['smtp_password'] = $smtpPass;
+        }
+
+        if (!empty($spamAction)) {
+            // TODO(sean.johnson): Extended spam filter input validation.
+            Assert::stringNotEmpty($spamAction);
+
             $params['spam_action'] = $spamAction;
         }
 
+        if (null !== $wildcard) {
+            Assert::boolean($wildcard);
+
+            $params['wildcard'] = $wildcard ? 'true' : 'false';
+        }
+
         $response = $this->httpPost('/v3/domains', $params);
 
         return $this->hydrateResponse($response, CreateResponse::class);

src/Api/HttpApi.php

@@ -85,6 +85,8 @@ abstract class HttpApi
                 throw HttpClientException::unauthorized($response);
             case 402:
                 throw HttpClientException::requestFailed($response);
+            case 403:
+                throw  HttpClientException::forbidden($response);
             case 404:
                 throw HttpClientException::notFound($response);
             case 413:

src/Api/Message.php

@@ -57,8 +57,11 @@ class Message extends HttpApi
         }
 
         $postDataMultipart = array_merge($this->prepareMultipartParameters($params), $postDataMultipart);
-        $response = $this->httpPostRaw(sprintf('/v3/%s/messages', $domain), $postDataMultipart);
-        $this->closeResources($postDataMultipart);
+        try {
+            $response = $this->httpPostRaw(sprintf('/v3/%s/messages', $domain), $postDataMultipart);
+        } finally {
+            $this->closeResources($postDataMultipart);
+        }
 
         return $this->hydrateResponse($response, SendResponse::class);
     }
@@ -91,8 +94,11 @@ class Message extends HttpApi
             ];
         }
         $postDataMultipart[] = $this->prepareFile('message', $fileData);
-        $response = $this->httpPostRaw(sprintf('/v3/%s/messages.mime', $domain), $postDataMultipart);
-        $this->closeResources($postDataMultipart);
+        try {
+            $response = $this->httpPostRaw(sprintf('/v3/%s/messages.mime', $domain), $postDataMultipart);
+        } finally {
+            $this->closeResources($postDataMultipart);
+        }
 
         return $this->hydrateResponse($response, SendResponse::class);
     }
@@ -128,12 +134,15 @@ class Message extends HttpApi
     private function prepareFile(string $fieldName, array $filePath): array
     {
         $filename = isset($filePath['filename']) ? $filePath['filename'] : null;
+        $deleteRequired = false;
 
         if (isset($filePath['fileContent'])) {
             // File from memory
-            $resource = fopen('php://temp', 'r+');
+            $filename = tempnam(sys_get_temp_dir(), "MAILGUN_TMP");
+            $resource = fopen($filename, 'r+');
             fwrite($resource, $filePath['fileContent']);
             rewind($resource);
+            $deleteRequired = true;
         } elseif (isset($filePath['filePath'])) {
             // File form path
             $path = $filePath['filePath'];
@@ -152,6 +161,7 @@ class Message extends HttpApi
             'name' => $fieldName,
             'content' => $resource,
             'filename' => $filename,
+            'deleteRequired' => $deleteRequired,
         ];
     }
 
@@ -183,6 +193,13 @@ class Message extends HttpApi
             if (is_array($param) && array_key_exists('content', $param) && is_resource($param['content'])) {
                 fclose($param['content']);
             }
+            if (is_array($param)) {
+                $isFile = array_key_exists('filename', $param) && is_file($param['filename']);
+                $deleteRequired = $param['deleteRequired'] ?? false;
+                if ($isFile && $deleteRequired) {
+                    unlink($param['filename']);
+                }
+            }
         }
     }
 }

src/Api/Suppression/Unsubscribe.php

@@ -84,17 +84,24 @@ class Unsubscribe extends HttpApi
     }
 
     /**
-     * @param string $domain  Domain to delete unsubscribe for
-     * @param string $address Unsubscribe address
+     * @param string      $domain  Domain to delete unsubscribe for
+     * @param string      $address Unsubscribe address
+     * @param string|null $tag     Unsubscribe tag
      *
      * @return DeleteResponse
      */
-    public function delete(string $domain, string $address)
+    public function delete(string $domain, string $address, string $tag = null)
     {
         Assert::stringNotEmpty($domain);
         Assert::stringNotEmpty($address);
+        Assert::nullOrStringNotEmpty($tag);
 
-        $response = $this->httpDelete(sprintf('/v3/%s/unsubscribes/%s', $domain, $address));
+        $params = [];
+        if (!is_null($tag)) {
+            $params['tag'] = $tag;
+        }
+
+        $response = $this->httpDelete(sprintf('/v3/%s/unsubscribes/%s', $domain, $address), $params);
 
         return $this->hydrateResponse($response, DeleteResponse::class);
     }

src/Exception/HttpClientException.php

@@ -83,6 +83,21 @@ final class HttpClientException extends \RuntimeException implements Exception
         return new self('Payload too large, your total attachment size is too big.', 413, $response);
     }
 
+    public static function forbidden(ResponseInterface $response)
+    {
+        $body = $response->getBody()->__toString();
+        if (0 !== strpos($response->getHeaderLine('Content-Type'), 'application/json')) {
+            $validationMessage = $body;
+        } else {
+            $jsonDecoded = json_decode($body, true);
+            $validationMessage = isset($jsonDecoded['Error']) ? $jsonDecoded['Error'] : $body;
+        }
+
+        $message = sprintf("Forbidden!\n\n%s", $validationMessage);
+
+        return new self($message, 403, $response);
+    }
+
     public function getResponse(): ?ResponseInterface
     {
         return $this->response;

src/Mailgun.php

@@ -74,19 +74,11 @@ class Mailgun
         return new self($httpClientConfigurator);
     }
 
-    /**
-     * @return ResponseInterface|null
-     */
-    public function getLastResponse()
+    public function getLastResponse(): ?ResponseInterface
     {
         return $this->responseHistory->getLastResponse();
     }
 
-    public function stats(): Api\Stats
-    {
-        return new Api\Stats($this->httpClient, $this->requestBuilder, $this->hydrator);
-    }
-
     public function attachment(): Api\Attachment
     {
         return new Api\Attachment($this->httpClient, $this->requestBuilder, $this->hydrator);
@@ -97,9 +89,9 @@ class Mailgun
         return new Api\Domain($this->httpClient, $this->requestBuilder, $this->hydrator);
     }
 
-    public function tags(): Api\Tag
+    public function emailValidation(): Api\EmailValidation
     {
-        return new Api\Tag($this->httpClient, $this->requestBuilder, $this->hydrator);
+        return new Api\EmailValidation($this->httpClient, $this->requestBuilder, $this->hydrator);
     }
 
     public function events(): Api\Event
@@ -107,14 +99,14 @@ class Mailgun
         return new Api\Event($this->httpClient, $this->requestBuilder, $this->hydrator);
     }
 
-    public function routes(): Api\Route
+    public function ips(): Api\Ip
     {
-        return new Api\Route($this->httpClient, $this->requestBuilder, $this->hydrator);
+        return new Api\Ip($this->httpClient, $this->requestBuilder, $this->hydrator);
     }
 
-    public function webhooks(): Api\Webhook
+    public function mailingList(): Api\MailingList
     {
-        return new Api\Webhook($this->httpClient, $this->requestBuilder, $this->hydrator, $this->apiKey);
+        return new Api\MailingList($this->httpClient, $this->requestBuilder, $this->hydrator);
     }
 
     public function messages(): Api\Message
@@ -122,9 +114,9 @@ class Mailgun
         return new Api\Message($this->httpClient, $this->requestBuilder, $this->hydrator);
     }
 
-    public function ips(): Api\Ip
+    public function routes(): Api\Route
     {
-        return new Api\Ip($this->httpClient, $this->requestBuilder, $this->hydrator);
+        return new Api\Route($this->httpClient, $this->requestBuilder, $this->hydrator);
     }
 
     public function suppressions(): Api\Suppression
@@ -132,8 +124,18 @@ class Mailgun
         return new Api\Suppression($this->httpClient, $this->requestBuilder, $this->hydrator);
     }
 
-    public function emailValidation(): Api\EmailValidation
+    public function stats(): Api\Stats
     {
-        return new Api\EmailValidation($this->httpClient, $this->requestBuilder, $this->hydrator);
+        return new Api\Stats($this->httpClient, $this->requestBuilder, $this->hydrator);
+    }
+
+    public function tags(): Api\Tag
+    {
+        return new Api\Tag($this->httpClient, $this->requestBuilder, $this->hydrator);
+    }
+
+    public function webhooks(): Api\Webhook
+    {
+        return new Api\Webhook($this->httpClient, $this->requestBuilder, $this->hydrator, $this->apiKey);
     }
 }

tests/Api/DomainTest.php

@@ -85,6 +85,20 @@ JSON
     }
 
     public function testCreateWithPassword()
+    {
+        $this->setRequestMethod('POST');
+        $this->setRequestUri('/v3/domains');
+        $this->setRequestBody([
+            'name' => 'example.com',
+            'smtp_password' => 'foo',
+        ]);
+        $this->setHydrateClass(CreateResponse::class);
+
+        $api = $this->getApiInstance();
+        $api->create('example.com', 'foo');
+    }
+
+    public function testCreateWithPasswordSpamAction()
     {
         $this->setRequestMethod('POST');
         $this->setRequestUri('/v3/domains');
@@ -95,6 +109,22 @@ JSON
         ]);
         $this->setHydrateClass(CreateResponse::class);
 
+        $api = $this->getApiInstance();
+        $api->create('example.com', 'foo', 'bar');
+    }
+
+    public function testCreateWithPasswordSpamActionWildcard()
+    {
+        $this->setRequestMethod('POST');
+        $this->setRequestUri('/v3/domains');
+        $this->setRequestBody([
+            'name' => 'example.com',
+            'smtp_password' => 'foo',
+            'spam_action' => 'bar',
+            'wildcard' => 'true',
+        ]);
+        $this->setHydrateClass(CreateResponse::class);
+
         $api = $this->getApiInstance();
         $api->create('example.com', 'foo', 'bar', true);
     }

tests/Api/MessageTest.php

@@ -124,6 +124,52 @@ class MessageTest extends TestCase
         $api->sendMime('foo', ['mailbox@myapp.com'], $message, []);
     }
 
+    public function testCloseResourcesOnSendRequestException()
+    {
+        $api = $this->getApiMock();
+
+        $api->expects($this->once())
+            ->method('httpPostRaw')
+            ->willThrowException(new \Exception('Something went wrong'));
+
+        $streamsCount = count(get_resources('stream'));
+
+        try {
+            $api->send('example.com', [
+                'from' => 'bob@example.com',
+                'to' => 'sally@example.com',
+                'subject' => 'Test file path attachments',
+                'text' => 'Test',
+                'attachment' => [
+                    ['filePath' => __DIR__.'/../TestAssets/mailgun_icon1.png', 'filename' => 'mailgun_icon1.png'],
+                ],
+            ]);
+        } catch (\Exception $e) {
+            $this->assertEquals('Something went wrong', $e->getMessage());
+        }
+
+        $this->assertCount($streamsCount, get_resources('stream'));
+    }
+
+    public function testCloseResourcesOnSendMimeRequestException()
+    {
+        $api = $this->getApiMock();
+
+        $api->expects($this->once())
+            ->method('httpPostRaw')
+            ->willThrowException(new \Exception('Something went wrong'));
+
+        $streamsCount = count(get_resources('stream'));
+
+        try {
+            $api->sendMime('foo', ['mailbox@myapp.com'], 'mime message', ['o:Foo' => 'bar']);
+        } catch (\Exception $e) {
+            $this->assertEquals('Something went wrong', $e->getMessage());
+        }
+
+        $this->assertCount($streamsCount, get_resources('stream'));
+    }
+
     /**
      * {@inheritdoc}
      */

tests/Api/Suppression/UnsubscribeTest.php

@@ -65,6 +65,17 @@ class UnsubscribeTest extends TestCase
         $api->delete('example.com', 'foo@bar.com');
     }
 
+    public function testDeleteWithTag()
+    {
+        $this->setRequestMethod('DELETE');
+        $this->setRequestUri('/v3/example.com/unsubscribes/foo@bar.com');
+        $this->setRequestBody(['tag' => 'tag1']);
+        $this->setHydrateClass(DeleteResponse::class);
+
+        $api = $this->getApiInstance();
+        $api->delete('example.com', 'foo@bar.com', 'tag1');
+    }
+
     public function testDeleteAll()
     {
         $this->setRequestMethod('DELETE');

tests/Exception/HttpClientExceptionTest.php

@@ -34,4 +34,30 @@ class HttpClientExceptionTest extends MailgunTestCase
         $exception = HttpClientException::badRequest($response);
         $this->assertStringEndsWith('<html><body>Server HTML</body></html>', $exception->getMessage());
     }
+
+    public function testForbiddenRequestThrowException()
+    {
+        $response = new Response(403, ['Content-Type' => 'application/json'], '{"Error":"Business Verification"}');
+        $exception = HttpClientException::forbidden($response);
+        $this->assertInstanceOf(HttpClientException::class, $exception);
+        $this->assertSame(403, $exception->getCode());
+    }
+
+    public function testForbiddenRequestGetMessageJson()
+    {
+        $response = new Response(403, ['Content-Type' => 'application/json'], '{"Error":"Business Verification"}');
+        $exception = HttpClientException::forbidden($response);
+        $this->assertStringEndsWith('Business Verification', $exception->getMessage());
+
+        $response = new Response(403, ['Content-Type' => 'application/json'], '{"Message":"Business Verification"}');
+        $exception = HttpClientException::forbidden($response);
+        $this->assertStringEndsWith('{"Message":"Business Verification"}', $exception->getMessage());
+    }
+
+    public function testForbiddenRequestGetMessage()
+    {
+        $response = new Response(403, ['Content-Type' => 'text/html'], '<html><body>Forbidden</body></html>');
+        $exception = HttpClientException::forbidden($response);
+        $this->assertStringEndsWith('<html><body>Forbidden</body></html>', $exception->getMessage());
+    }
 }