Initial Commit

Author: mheap

.gitignore

@@ -0,0 +1 @@
+vendor

README.md

@@ -0,0 +1,103 @@
+# Nexmo / Laravel Notifications
+
+Although Nexmo is [built in to Laravel](https://laravel.com/docs/5.7/notifications#sms-notifications) as the default SMS provider, that is only a small portion of the available communication channels we offer.
+
+This package adds the ability to send notifications to WhatsApp, Facebook Messenger and Viber via Nexmo.
+
+## Usage
+
+To use this package, run `composer require nexmo/laravel-notifications`. Once it completes, you can implement the following methods on your notification:
+
+* `toNexmoWhatsApp`
+* `toNexmoFacebook`
+* `toNexmoViberServiceMessage`
+* `toNexmoSms`
+
+See [examples/Notification/MerryChristmas.php](examples/Notificatoin/MerryChristmas.php) for a complete example.
+
+To send a notification, specify the class name you'd like to use:
+
+```php
+// To a user
+$user->notify(new \App\Notifications\MerryChristmas());
+
+// To any person
+Notification::route(
+    \Nexmo\Notifications\WhatsApp::class,
+    'YOUR_NUMBER'
+)->notify(new \App\Notifications\MerryChristmas());
+```
+
+As each notification receives a `$notifiable` (usually a user) it can decide how best to route the information. In this case, it checks the `via_whatsapp` property on the user and sends via WhatsApp if it's true. Otherwise it falls back to email
+
+```
+public function via($notifiable)
+{
+    return $notifiable->via_whatsapp ? [\Nexmo\Notifications\WhatsApp::class] : ['mail'];
+}
+```
+
+### Message Types
+
+Nexmo supports multiple message types, depending on the channel that you're sending to. The `Text` type is the safest if you want to deliver to all channels:
+
+```
+public function toNexmoWhatsApp($notifiable)
+{
+    return (new \Nexmo\Notifications\Message\Text)
+        ->content('This is a message being sent to WhatsApp');
+}
+```
+
+### Caveats
+
+For some channels you need to send a templated message before you can send a free text message due to spam control rules. Here's an example of how to use a preapproved template intended for two-factor authentication purposes:
+
+```
+public function toNexmoWhatsApp($notifiable)
+{
+    return (new \Nexmo\Notifications\Message\Template)
+        ->name("whatsapp:hsm:technology:nexmo:verify")
+        ->parameters([
+            ["default" => "Your Brand"],
+            ["default" => "64873"],
+            ["default" => "10"],
+        ]);
+}
+```
+
+If the recipient replies to your message, you can send them `Text` type messages without any issues
+
+## Configuration
+
+### Authentication
+
+This notifications package is built on top of [nexmo/laravel](https://github.com/Nexmo/nexmo-laravel) and uses the Nexmo client from there.
+
+For this to work, you need to set your application ID and path to your private key in the `.env` file:
+
+```
+NEXMO_APPLICATION_ID=my_application_id
+NEXMO_PRIVATE_KEY=./private.key
+```
+
+### Setting the `from` address
+
+You can set a `from `address via the `.env` file. This package will look for provider specific entries before falling back to `NEXMO_FROM`.
+
+```
+NEXMO_FROM_SMS=""
+NEXMO_FROM_WHATSAPP=""
+NEXMO_FROM_MESSENGER=""
+NEXMO_FROM_VIBER_SERVICE_MSG=""
+NEXMO_FROM="" # This is the default if any of the above aren't set
+```
+
+Alternatively, you can set a `from` address for a single notification by calling the `->from()` method on a message:
+
+```php
+public function toNexmoViberServiceMessage($notifiable)
+{
+    return (new Text)->content('Merry Christmas Viber!')->from("YOUR_ID");
+}
+```

composer.json

@@ -0,0 +1,21 @@
+{
+    "name": "nexmo/laravel-notification",
+    "description": "Send SMS, WhatsApp, Viber and Facebook Messenger messages via Nexmo",
+    "type": "library",
+    "license": "MIT",
+    "authors": [
+        {
+            "name": "Michael Heap",
+            "email": "michael.heap@vonage.com"
+        }
+    ],
+    "require": {
+        "guzzlehttp/guzzle": "^6.3",
+        "nexmo/laravel": "^1.1"
+    },
+    "autoload": {
+        "psr-4": {
+            "Nexmo\\": "src"
+        }
+    }
+}

examples/Notification/MerryChristmas.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace App\Notifications;
+
+use Illuminate\Bus\Queueable;
+use Illuminate\Notifications\Notification;
+
+use Nexmo\Notifications\Sms;
+use Nexmo\Notifications\WhatsApp;
+use Nexmo\Notifications\Facebook;
+use Nexmo\Notifications\ViberServiceMessage;
+
+use Nexmo\Notifications\Message\Text;
+
+class MerryChristmas extends Notification
+{
+    use Queueable;
+
+    public function via($notifiable)
+    {
+        return [
+            Sms::class,
+            WhatsApp::class,
+            Facebook::class,
+            ViberServiceMessage::class,
+        ];
+    }
+
+    public function toNexmoWhatsApp($notifiable)
+    {
+        return (new Text)->content('Merry Christmas WhatsApp!');
+    }
+
+    public function toNexmoFacebook($notifiable)
+    {
+        return (new Text)->content('Merry Christmas Facebook!');
+    }
+
+    public function toNexmoViberServiceMessage($notifiable)
+    {
+        return (new Text)->content('Merry Christmas Viber!');
+    }
+
+    public function toNexmoSms($notifiable)
+    {
+        return (new Text)->content('Merry Christmas SMS!');
+    }
+}
+

src/Notifications/Facebook.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Nexmo\Notifications;
+
+class Facebook extends MessageChannel {
+    protected $channelName = 'messenger';
+    protected $channelIdField = 'id';
+    protected $notificationMappingMethod = 'toNexmoFacebook';
+}
+

src/Notifications/Message/Template.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace Nexmo\Notifications\Message;
+
+class Template extends Base {
+
+    protected $name;
+    protected $parameters;
+
+    public function name($name) {
+        $this->name = $name;
+        return $this;
+    }
+
+    public function parameters($parameters) {
+        $this->parameters = $parameters;
+        return $this;
+    }
+
+    public function toNexmoApi($from, $to) {
+        return [
+            'from' => $from,
+            'to' => $to,
+            'message' => [
+                'content' => [
+                    'type' => 'template',
+                    "template" => [
+                        "name" => $this->name,
+                        "parameters" => $this->parameters
+                    ]
+                ]
+            ]
+        ];
+    }
+
+}

src/Notifications/Message/Text.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Nexmo\Notifications\Message;
+
+class Text extends Base {
+    protected $content;
+
+    public function content($content) {
+        $this->content = $content;
+        return $this;
+    }
+
+    public function toNexmoApi($from, $to) {
+        return [
+            'from' => $from,
+            'to' => $to,
+            'message' => [
+                'content' => [
+                    'type' => 'text',
+                    'text' => $this->content
+                ]
+            ]
+        ];
+    }
+}

src/Notifications/Message/base.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace Nexmo\Notifications\Message;
+
+abstract class Base {
+    protected $from;
+
+    public function from($from) {
+        $this->from = $from;
+        return $this;
+    }
+
+    public function getFrom($channelName){
+        $defaultEnv = env('NEXMO_FROM');
+        $specificEnv = env('NEXMO_FROM_'. strtoupper($channelName));
+
+        if (!$this->from) {
+            if ($specificEnv) {
+                return $specificEnv;
+            }
+            return $defaultEnv;
+        }
+
+        return $this->from;
+    }
+}

src/Notifications/MessageChannel.php

@@ -0,0 +1,59 @@
+<?php
+
+namespace Nexmo\Notifications;
+
+use Nexmo;
+use Illuminate\Notifications\Notification;
+
+abstract class MessageChannel {
+
+    protected $channelName;
+    protected $channelIdField;
+    protected $channelFromField;
+    protected $notificationMappingMethod;
+
+    public function send($notifiable, Notification $notification)
+    {
+        if (! $to = $notifiable->routeNotificationFor(static::class)) {
+            return;
+        }
+
+        $message = $notification->{$this->notificationMappingMethod}($notifiable);
+
+        $response = $this->sendMessage(
+            $message->toNexmoApi(
+                $this->from($message->getFrom($this->channelName)),
+                $this->to($to)
+            )
+        );
+    }
+
+    protected function toEndpoint($id, $field) {
+        return ['type' => $this->channelName, $field => $id];
+    }
+
+    protected function to($id) {
+        return $this->toEndpoint($id, $this->channelIdField);
+    }
+
+    protected function from($id) {
+        $field = $this->channelIdField;
+        if ($this->channelFromField) {
+            $field = $this->channelFromField;
+        }
+        return $this->toEndpoint($id, $field);
+    }
+
+    protected function sendMessage($body) {
+        $client = new \GuzzleHttp\Client();
+        return $client->request('POST', 'https://api.nexmo.com/v0.1/messages', [
+            'headers' => [
+                'Authorization' => 'Bearer '. Nexmo::generateJwt(),
+                'Content-Type' => 'application/json', 
+                'Accept' => 'application/json'
+            ],
+            'body' => json_encode($body)
+        ]);
+    }
+}
+

src/Notifications/Sms.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Nexmo\Notifications;
+
+class Sms extends MessageChannel {
+    protected $channelName = 'sms';
+    protected $channelIdField = 'number';
+    protected $notificationMappingMethod = 'toNexmoSms';
+}
+

src/Notifications/ViberServiceMessage.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Nexmo\Notifications;
+
+class ViberServiceMessage extends MessageChannel {
+    protected $channelName = 'viber_service_msg';
+    protected $channelFromField = 'id';
+    protected $channelIdField = 'number';
+    protected $notificationMappingMethod = 'toNexmoViberServiceMessage';
+}
+

src/Notifications/WhatsApp.php

@@ -0,0 +1,9 @@
+<?php
+
+namespace Nexmo\Notifications;
+
+class WhatsApp extends MessageChannel {
+    protected $channelName = 'whatsapp';
+    protected $channelIdField = 'number';
+    protected $notificationMappingMethod = 'toNexmoWhatsApp';
+}