🎉 initial commit

Signed-off-by: Bruno Meilick <b@bnomei.com>

.gitignore

@@ -30,3 +30,4 @@
 /vendor/**/php4/*
 /vendor/getkirby/composer-installer
 coverage.xml
+/vendor/**/Dockerfile

README.md

@@ -10,12 +10,13 @@
 [![Demo](https://flat.badgen.net/badge/website/examples?color=f92672)](https://kirby3-plugins.bnomei.com/mailjet) 
 [![Gitter](https://flat.badgen.net/badge/gitter/chat?color=982ab3)](https://gitter.im/bnomei-kirby-3-plugins/community) 
 [![Twitter](https://flat.badgen.net/badge/twitter/bnomei?color=66d9ef)](https://twitter.com/bnomei)
-@@@TODO@@@
+
+Send transactional E-Mail and Campaigns with Mailjet
 
 ## Commercial Usage
 
 This plugin is free but if you use it in a commercial project please consider to 
-- [make a donation 🍻](https://www.paypal.me/bnomei/5) or
+- [make a donation 🍻](https://www.paypal.me/bnomei/1) or
 - [buy me ☕](https://buymeacoff.ee/bnomei) or
 - [buy a Kirby license using this affiliate link](https://a.paddle.com/v2/click/1129/35731?link=1170)
 
@@ -25,10 +26,80 @@ This plugin is free but if you use it in a commercial project please consider to
 - `git submodule add https://github.com/bnomei/kirby3-mailjet.git site/plugins/kirby3-mailjet` or
 - `composer require bnomei/kirby3-mailjet`
 
+## Setup
+
+You can set the apikey and apisecret in the config.
+
+**site/config/config.php**
+```php
+return [
+    // other config settings ...
+    'bnomei.mailjet.apikey' => 'YOUR-KEY-HERE',
+    'bnomei.mailjet.apisecret' => 'YOUR-SECRET-HERE',
+];
+```
+
+You can also set a callback if you use the [dotenv Plugin](https://github.com/bnomei/kirby3-dotenv).
+
+**site/config/config.php**
+```php
+return [
+    // other config settings ...
+    'bnomei.mailjet.apikey' => function() { return env('MAILJET_APIKEY'); },
+    'bnomei.mailjet.apisecret' => function() { return env('MAILJET_APISECRET'); },
+];
+```
+
 ## Usecase
 
-@@@TODO@@@
+This plugin is a wrapper around [Mailjet API v3 PHP](https://github.com/mailjet/mailjet-apiv3-php) while adding some Kirby 3 workflow specific helpers.
+
+### Get Mailjet Client
+
+Create a Mailjet Client instance and initialize it with the apikey and apisecret set in you config file.
+
+```php
+$mj = \Bnomei\Mailjet::singleton()->client();
+// or just
+$mj = mailjet()->client();
+```
+
+### Get SMTP Transport Options
+
+This plugin comes with [sensible defaults](https://github.com/bnomei/kirby3-mailjet/blob/master/index.php#L10) for your Mailjet SMTP configuration. If needed you can override them using your `site/config/config.php` File.
+
+```php
+$smtpTransportOptions = mailjet()->transport();
+```
+
+### Sending a SMTP E-Mail with Authentification
+
+```php
+$success = kirby()->email([
+    'from' => 'mailjet@example.com', // you verified mailjet sender
+    'to' => 'roger@rabbit.us', // regular or Mailjets "magic" Contactlist-E-Mail
+    'subject' => 'Subject Text',
+    'body' => [
+        'html' => '<h1>Headline</h1><p>Text</p>',
+        'text' => "Headline\n\nText",
+    ],
+    'transport' => mailjet()->transport(),
+])->isSent();
+```
+
+> TIP: Read more about [sending E-Mails with Kirby 3](https://getkirby.com/docs/guide/emails) in the docs.
+
+### Sending Campaigns
+
+Sending campaigns consists of creating and/or updating a campaign object using the Mailjet API identified by an unique ID, adding optional schedules and later issuing the publication. This plugin provides no specific helpers in that regard so please read the official docs on how to accomplish that.
+
+## Roadmap
 
+- [ ] Explanation on how to use [Janitor Plugin](https://github.com/bnomei/kirby3-janitor) buttons to test and send E-Mails
+- [ ] Getter for verified Sender-E-Mail-Adresses (to use in Panel Dropdowns)
+- [ ] Getter for Contact-Lists (to use in Panel Dropdowns)
+- [ ] Getter for Segments (to use in Panel Dropdowns)
+- [ ] Add/Add-Force/Unsub Contact from Contact-List
 
 ## Dependencies
 

classes/Mailjet.php

@@ -4,7 +4,78 @@
 
 namespace Bnomei;
 
+use Mailjet\Client;
+
 final class Mailjet
 {
+    /** @var \Mailjet\Client */
+    private $client;
+
+    /** @var array */
+    private $options;
+
+    /**
+     * Mailjet constructor.
+     *
+     * @param array $options
+     */
+    public function __construct(array $options = [])
+    {
+        $defaults = [
+            'debug' => option('debug'),
+            'apikey' => option('bnomei.mailjet.apikey'),
+            'apisecret' => option('bnomei.mailjet.apisecret'),
+        ];
+        $this->options = array_merge($defaults, $options);
+
+        foreach ($options as $key => $callable) {
+            if (is_callable($callable) && in_array($key, ['apikey', 'apisecret'])) {
+                $this->options[$key] = $callable();
+            }
+        }
+
+        $this->client = new Client($this->options['apikey'], $this->options['apisecret']);
+    }
+
+    /**
+     * Get Mailjet Client Instance
+     *
+     * @return \Mailjet\Client
+     */
+    public function client(): Client
+    {
+        return $this->client;
+    }
+
+    /**
+     * Get SMTP Email Transport Options Array
+     *
+     * @return array
+     */
+    public function transport(): array
+    {
+        return array_merge(
+            [
+                'username' => $this->options['apikey'],
+                'password' => $this->options['apisecret'],
+            ],
+            option('bnomei.mailjet.email.transport')
+        );
+    }
+
+    /** @var \Bnomei\Mailjet */
+    private static $singleton;
+
+    /**
+     * @param array $options
+     * @return \Bnomei\Mailjet
+     */
+    public static function singleton(array $options = [])
+    {
+        if (! self::$singleton) {
+            self::$singleton = new self($options);
+        }
 
+        return self::$singleton;
+    }
 }

composer.json

@@ -22,8 +22,11 @@
     "newsletter",
     "campaign",
     "transactional",
+    "segment",
     "smtp",
-    "mjml"
+    "mjml",
+    "html",
+    "responsive"
   ],
   "autoload": {
     "psr-4": {
@@ -56,11 +59,18 @@
     "dist": [
       "composer install --no-dev --optimize-autoloader",
       "git rm -rf --cached .; git add .;"
+    ],
+    "kirby": [
+      "composer install",
+      "composer update",
+      "composer install --working-dir=tests/kirby --no-dev --optimize-autoloader",
+      "composer update --working-dir=tests/kirby"
     ]
   },
   "extra": {
     "kirby-cms-path": "tests/kirby"
   },
   "suggest": {
+    "bnomei/kirby3-dotenv": "To load the api secret from an .env file"
   }
 }