Merge pull request #27 from railsware/feature/v.2.0.0

Upgrade SDK v.2.0 [BC BREAK]
railsware · Jul 16, 2024 · 8021b0b · 8021b0b
2 parents a4e20f0 + b159619
commit 8021b0b
Show file tree

Hide file tree

Showing 69 changed files with 1,162 additions and 593 deletions.
diff --git a/.github/workflows/ci-phpunit.yml b/.github/workflows/ci-phpunit.yml
@@ -8,6 +8,8 @@ on:
       - 'release/**'
       - 'feature/**'
       - 'main'
+  schedule:
+    - cron: '0 0 * * *'  # Runs every day at midnight UTC
 
 jobs:
   phpunit-tests:
@@ -16,7 +18,7 @@ jobs:
     strategy:
       matrix:
         os: [ ubuntu-latest ]
-        php-version: [ '7.4','8.0','8.1','8.2','8.3' ]
+        php-version: [ '8.0','8.1','8.2','8.3' ]
 
     steps:
       - name: Checkout
@@ -58,8 +60,6 @@ jobs:
     strategy:
       matrix:
         include:
-          - symfony: '5'
-            php-version: '7.4'
           - symfony: '6'
             php-version: '8.2'
           - symfony: '7'

diff --git a/.github/workflows/ci-psalm.yaml b/.github/workflows/ci-psalm.yaml
@@ -15,7 +15,7 @@ jobs:
     strategy:
       matrix:
         os: [ ubuntu-latest ]
-        php-versions: [ '7.4','8.0','8.1','8.2','8.3' ]
+        php-versions: [ '8.0','8.1','8.2','8.3' ]
 
     steps:
       - name: Checkout

diff --git a/.gitignore b/.gitignore
@@ -11,7 +11,7 @@ phpunit.xml
 ###> files for local testing ###
 test.php
 docker-compose.yaml
-Dockerfile
+Dockerfile*
 ###> files for local testing ###
 
 ###> other ###

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,11 @@
+## [2.0.0] - 2024-06-12
+- [BC BREAK] PHP 7.4 will no longer be supported (PHP 8.0+).
+- [BC BREAK] Rebuild `Emails` layers to use the `inboxId` at the client level ([examples](examples/testing/emails.php))
+- [BC BREAK] Rebuild SANDBOX `Projects` & `Messages` & `Attachments` & `Inboxes`  layers ([examples](examples/testing))
+- [BC BREAK] Rebuild GENERAL `Accounts` & `Permissions` & `Users` layers ([examples](examples/general))
+- Added a short method to get the Email layer depending on config params `MailtrapClient::initSendingEmails()`
+- Added MailtrapEmail wrapper (MIME) for easy add category, custom variables, template uuid, etc.
+
 ## [1.9.0] - 2024-05-06
 
 - Support templates in testing

diff --git a/README.md b/README.md
@@ -33,22 +33,21 @@ Here's how to send a message using the SDK:
 ```php
 <?php
 
-use Mailtrap\Config;
-use Mailtrap\EmailHeader\CategoryHeader;
-use Mailtrap\EmailHeader\CustomVariableHeader;
 use Mailtrap\Helper\ResponseHelper;
 use Mailtrap\MailtrapClient;
+use Mailtrap\Mime\MailtrapEmail;
 use Symfony\Component\Mime\Address;
 use Symfony\Component\Mime\Email;
 use Symfony\Component\Mime\Header\UnstructuredHeader;
 
 require __DIR__ . '/vendor/autoload.php';
 
-// your API token from here https://mailtrap.io/api-tokens
-$apiKey = getenv('MAILTRAP_API_KEY');
-$mailtrap = new MailtrapClient(new Config($apiKey));
+// Mailtrap SENDING client (real) for transactional emails
+$mailtrap = MailtrapClient::initSendingEmails(
+    apiKey: getenv('MAILTRAP_API_KEY') # your API token from here https://mailtrap.io/api-tokens
+);
 
-$email = (new Email())
+$email = (new MailtrapEmail())
     ->from(new Address('example@your-domain-here.com', 'Mailtrap Test'))
     ->replyTo(new Address('reply@your-domain-here.com'))
     ->to(new Address('email@example.com', 'Jon'))
@@ -69,42 +68,57 @@ $email = (new Email())
     </html>'
     )
     ->embed(fopen('https://mailtrap.io/wp-content/uploads/2021/04/mailtrap-new-logo.svg', 'r'), 'logo', 'image/svg+xml')
-    ;
-
-    // Headers
-    $email->getHeaders()
+    ->category('Integration Test')
+    ->customVariables([
+        'user_id' => '45982',
+        'batch_id' => 'PSJ-12'
+    ])
+;
+
+// Custom email headers (optional)
+$email->getHeaders()
     ->addTextHeader('X-Message-Source', 'domain.com')
     ->add(new UnstructuredHeader('X-Mailer', 'Mailtrap PHP Client')) // the same as addTextHeader
-    ;
-
-    // Custom Variables
-    $email->getHeaders()
-    ->add(new CustomVariableHeader('user_id', '45982'))
-    ->add(new CustomVariableHeader('batch_id', 'PSJ-12'))
-    ;
-
-    // Category (should be only one)
-    $email->getHeaders()
-    ->add(new CategoryHeader('Integration Test'))
-    ;
-
+;
+
 try {
-    $response = $mailtrap->sending()->emails()->send($email); // Email sending API (real)
-    
+    $response = $mailtrap->send($email);
+
     var_dump(ResponseHelper::toArray($response)); // body (array)
 } catch (Exception $e) {
     echo 'Caught exception: ',  $e->getMessage(), "\n";
 }
 
-// OR send email to the Mailtrap SANDBOX
 
+// OR -> Mailtrap BULK SENDING client (real)
+try {
+    $mailtrapBulkSending = MailtrapClient::initSendingEmails(
+        apiKey: getenv('MAILTRAP_API_KEY'), # your API token from here https://mailtrap.io/api-tokens
+        isBulk: true # Bulk sending (@see https://help.mailtrap.io/article/113-sending-streams)
+    );
+
+    $response = $mailtrapBulkSending->send($email);
+
+    var_dump(ResponseHelper::toArray($response)); // body (array)
+} catch (Exception $e) {
+    echo 'Caught exception: ',  $e->getMessage(), "\n";
+}
+
+// OR -> Mailtrap Testing client (sandbox)
 try {
-    $response = $mailtrap->sandbox()->emails()->send($email, 1000001); // Required second param -> inbox_id
+    $mailtrapTesting = MailtrapClient::initSendingEmails(
+        apiKey: getenv('MAILTRAP_API_KEY'), # your API token from here https://mailtrap.io/api-tokens
+        isSandbox: true, # Sandbox sending (@see https://help.mailtrap.io/article/109-getting-started-with-mailtrap-email-testing)
+        inboxId: getenv('MAILTRAP_INBOX_ID') # required param for sandbox sending
+    );
+
+    $response = $mailtrapTesting->send($email);
 
     var_dump(ResponseHelper::toArray($response)); // body (array)
 } catch (Exception $e) {
     echo 'Caught exception: ',  $e->getMessage(), "\n";
 }
+
 ```
 
 ### All usage examples

diff --git a/UPGRADE-2.0.md b/UPGRADE-2.0.md
@@ -0,0 +1,128 @@
+UPGRADE FROM 1.x to 2.0
+=======================
+
+### Email Layers
+* Added a short method to get one of the Email layers (Sending/Bulk/Sandbox) depending on config params `MailtrapClient::initSendingEmails()`
+  *  string $apiKey
+  *  bool $isBulk = false
+  *  bool $isSandbox = false
+  *  int $inboxId = null
+* **BC BREAK**: In Sandbox layer `inboxId` should be passed at the client level.
+
+  __Before__: 
+  ```php
+  $mailtrap = new MailtrapClient(new Config(getenv('MAILTRAP_API_KEY')));
+
+  $response = $mailtrap
+    ->sandbox()
+    ->emails()
+    ->send($email, 1000001); # <--- inboxId here
+  ```
+  __After__:
+  ```php
+  # short method using `initSendingEmails`
+  $mailtrap = MailtrapClient::initSendingEmails(
+    apiKey: getenv('MAILTRAP_API_KEY'), #your API token from here https://mailtrap.io/api-tokens
+    isSandbox: true, # required param for sandbox sending
+    inboxId: getenv('MAILTRAP_INBOX_ID') # <--- inboxId here
+  );
+
+  # or using the client directly (old variant)
+  $mailtrap = (new MailtrapClient(new Config(getenv('MAILTRAP_API_KEY'))))
+    ->sandbox()
+    ->emails(getenv('MAILTRAP_INBOX_ID')); # <--- inboxId here
+
+  $response = $mailtrap->send($email);
+  ```
+
+### General API
+* **BC BREAK**: Rebuild `Accounts` & `Permissions` & `Users` layers ([examples](examples/general))
+
+  __Before__: 
+  ```php
+  $mailtrap = new MailtrapClient(new Config(getenv('MAILTRAP_API_KEY'))); # no changes here
+
+  $response = $mailtrap
+    ->general()
+    ->permissions()
+    ->getResources(getenv('MAILTRAP_ACCOUNT_ID')); # <--- accountId here
+
+  $response = $mailtrap
+    ->general()
+    ->users()
+    ->getList(getenv('MAILTRAP_ACCOUNT_ID'));  # <--- accountId here
+  ```
+  __After__:
+  ```php
+  // all permissions endpoints
+  $response = $mailtrap
+    ->general()
+    ->permissions(getenv('MAILTRAP_ACCOUNT_ID')) # <--- accountId here
+    ->getResources();
+
+  // all users endpoints
+  $response = $mailtrap
+    ->general()
+    ->users(getenv('MAILTRAP_ACCOUNT_ID')) # <--- accountId here
+    ->getList();
+  ```
+
+### Sandbox API
+* **BC BREAK**: Rebuild `Projects` & `Messages` & `Attachments` & `Inboxes` layers ([examples](examples/testing))
+
+  __Before__:
+  ```php
+  $mailtrap = new MailtrapClient(new Config(getenv('MAILTRAP_API_KEY'))); # no changes here
+
+  $response = $mailtrap
+    ->sandbox()
+    ->inboxes()
+    ->getList(getenv('MAILTRAP_ACCOUNT_ID')); # <--- accountId here
+  ```
+  __After__:
+  ```php
+  // all sandbox(testing) endpoints: projects, messages, attachments, inboxes
+  $response = $mailtrap
+    ->sandbox()
+    ->inboxes(getenv('MAILTRAP_ACCOUNT_ID')) # <--- accountId here
+    ->getList();
+  ```
+
+### Email Template class
+* Added `MailtrapEmail` wrapper (MIME) for easy use category, custom variables, template uuid, etc.
+
+  __Before__:
+  ```php
+  $email = (new Email())
+      ->from(new Address('example@YOUR-DOMAIN-HERE.com', 'Mailtrap Test')) // <--- you should use your domain here that you installed in the mailtrap.io admin area (otherwise you will get 401)
+      ->replyTo(new Address('reply@YOUR-DOMAIN-HERE.com'))
+      ->to(new Address('example@gmail.com', 'Jon'))
+  ;
+
+  // Template UUID and Variables
+  $email->getHeaders()
+      ->add(new TemplateUuidHeader('bfa432fd-0000-0000-0000-8493da283a69'))
+      ->add(new TemplateVariableHeader('user_name', 'Jon Bush'))
+      ->add(new TemplateVariableHeader('next_step_link', 'https://mailtrap.io/'))
+      ->add(new TemplateVariableHeader('get_started_link', 'https://mailtrap.io/'))
+      ->add(new TemplateVariableHeader('onboarding_video_link', 'some_video_link'))
+  ;
+  ```
+
+  __After__:
+  ```php
+  use Mailtrap\Mime\MailtrapEmail;
+
+  $email = (new MailtrapEmail()) # <--- new MIME class with template support
+      ->from(new Address('example@YOUR-DOMAIN-HERE.com', 'Mailtrap Test')) // <--- you should use your domain here that you installed in the mailtrap.io admin area (otherwise you will get 401)
+      ->replyTo(new Address('reply@YOUR-DOMAIN-HERE.com'))
+      ->to(new Address('example@gmail.com', 'Jon'))
+      ->templateUuid('bfa432fd-0000-0000-0000-8493da283a69') 
+      ->templateVariables([
+          'user_name' => 'Jon Bush',
+          'next_step_link' => 'https://mailtrap.io/',
+          'get_started_link' => 'https://mailtrap.io/',
+          'onboarding_video_link' => 'some_video_link'
+      ])
+  ;
+  ```
diff --git a/composer.json b/composer.json
@@ -5,7 +5,7 @@
   "homepage": "https://github.com/railsware/mailtrap-php",
   "license": "MIT",
   "require": {
-    "php": "^7.4 || ^8.0",
+    "php": "^8.0",
     "ext-curl": "*",
     "ext-json": "*",
     "psr/http-message": "^1.0 || ^2.0",
@@ -14,15 +14,15 @@
     "php-http/httplug": "^2.0",
     "php-http/discovery": "^1.0",
     "php-http/message-factory": "^1.0",
-    "symfony/mime": "^5.4|^6.0|^7.0",
+    "symfony/mime": "^6.0|^7.0",
     "egulias/email-validator": "^2.1.10|^3.1|^4"
   },
   "require-dev": {
-    "symfony/http-client": "^5.4|^6.0|^7.0",
-    "symfony/mailer": "^5.4|^6.0|^7.0",
+    "symfony/http-client": "^6.0|^7.0",
+    "symfony/mailer": "^6.0|^7.0",
     "phpunit/phpunit": "^9",
     "nyholm/psr7": "^1.5",
-    "vimeo/psalm": "^4.0 || ^5.0"
+    "vimeo/psalm": "^5.0"
   },
   "suggest": {
     "nyholm/psr7": "PSR-7 message implementation",

diff --git a/examples/general/accounts.php b/examples/general/accounts.php
@@ -2,21 +2,20 @@
 
 use Mailtrap\Config;
 use Mailtrap\Helper\ResponseHelper;
-use Mailtrap\MailtrapClient;
+use Mailtrap\MailtrapGeneralClient;
 
 require __DIR__ . '/../vendor/autoload.php';
 
-// your API token from here https://mailtrap.io/api-tokens
-$apiKey = getenv('MAILTRAP_API_KEY');
-$mailtrap = new MailtrapClient(new Config($apiKey));
+$config = new Config(getenv('MAILTRAP_API_KEY')); #your API token from here https://mailtrap.io/api-tokens
+$generalAccounts = (new MailtrapGeneralClient($config))->accounts();
 
 /**
  * Get a list of your Mailtrap accounts.
  *
  * GET https://mailtrap.io/api/accounts
  */
 try {
-    $response = $mailtrap->general()->accounts()->getList();
+    $response = $generalAccounts->getList();
 
     var_dump(ResponseHelper::toArray($response)); // body (array)
 } catch (Exception $e) {

diff --git a/examples/general/permissions.php b/examples/general/permissions.php
@@ -6,22 +6,21 @@
 use Mailtrap\DTO\Request\Permission\PermissionInterface;
 use Mailtrap\DTO\Request\Permission\Permissions;
 use Mailtrap\Helper\ResponseHelper;
-use Mailtrap\MailtrapClient;
+use Mailtrap\MailtrapGeneralClient;
 
 require __DIR__ . '/../vendor/autoload.php';
 
-// your API token from here https://mailtrap.io/api-tokens
-$apiKey = getenv('MAILTRAP_API_KEY');
-$mailtrap = new MailtrapClient(new Config($apiKey));
+$accountId = getenv('MAILTRAP_ACCOUNT_ID');
+$config = new Config(getenv('MAILTRAP_API_KEY')); #your API token from here https://mailtrap.io/api-tokens
+$generalPermissions = (new MailtrapGeneralClient($config))->permissions($accountId);
 
 /**
  * Get resources
  *
  * GET https://mailtrap.io/api/accounts/{account_id}/permissions/resources
  */
 try {
-    $accountId = getenv('MAILTRAP_ACCOUNT_ID');
-    $response = $mailtrap->general()->permissions()->getResources($accountId);
+    $response = $generalPermissions->getResources();
 
     // print the response body (array)
     var_dump(ResponseHelper::toArray($response));
@@ -39,7 +38,6 @@
  * PUT https://mailtrap.io/api/accounts/{account_id}/account_accesses/{account_access_id}/permissions/bulk
  */
 try {
-    $accountId = getenv('MAILTRAP_ACCOUNT_ID');
     $accountAccessId = getenv('MAILTRAP_ACCOUNT_ACCESS_ID');
 
     // resource IDs
@@ -53,7 +51,7 @@
         new DestroyPermission($destroyProjectResourceId, PermissionInterface::TYPE_PROJECT),
     );
 
-    $response = $mailtrap->general()->permissions()->update($accountId, $accountAccessId, $permissions);
+    $response = $generalPermissions->update($accountAccessId, $permissions);
 
     // print the response body (array)
     var_dump(ResponseHelper::toArray($response));