feat: v3 (#90)

* feat: v3

- throw exceptions (with ability to ignore specific codes)
- deferrable provider
- dedicated config file
- strict types
- fix bad tests

* feat: bump sdk verson to v6, add github actions CI

* feat: publish config + update readme

* fix: scrutinizer bugs

* feat: add support for debug to

* feat: docs + rethrow errors tests

* fix: switch to singleton

Author: atymic

README.md

@@ -33,21 +33,33 @@ composer require laravel-notification-channels/twilio
 
 ### Setting up your Twilio account
 
-Add your Twilio Account SID, Auth Token, and From Number (optional) to your `config/services.php`:
+Add your Twilio Account SID, Auth Token, and From Number (optional) to your `.env`:
+
+```dotenv
+TWILIO_USERNAME=XYZ # optional when using auth token
+TWILIO_PASSWORD=ZYX # optional when using auth token
+TWILIO_AUTH_TOKEN=ABCD # optional when using username and password
+TWILIO_ACCOUNT_SID=1234 # always required
+TWILIO_FROM=100000000 # otional default from
+TWILIO_ALPHA_SENDER=HELLO # optional
+TWILIO_DEBUG_TO=23423423423 # Set a number that call calls/messages should be routed to for debugging
+```
 
-```php
-// config/services.php
-...
-'twilio' => [
-    'username' => env('TWILIO_USERNAME'), // optional when using auth token
-    'password' => env('TWILIO_PASSWORD'), // optional when using auth token
-    'auth_token' => env('TWILIO_AUTH_TOKEN'), // optional when using username and password
-    'account_sid' => env('TWILIO_ACCOUNT_SID'),
-    'from' => env('TWILIO_FROM'), // optional
-],
-...
+### Advanced configuration
+
+Run `php artisan vendor:publish --provider="NotificationChannels\Twilio\TwilioProvider"`
+```
+/config/twilio-notification-channel.php
 ```
 
+#### Suppressing specific errors or all errors
+
+Publish the config using the above command, and edit the `ignored_error_codes` array. You can get the list of
+exception codes from [the documentation](https://www.twilio.com/docs/api/errors). 
+
+If you want to suppress all errors, you can set the option to `['*']`. The errors will not be logged but notification
+failed events will still be emitted.
+
 ## Usage
 
 Now you can use the channel in your `via()` method inside the notification:

composer.json

@@ -1,6 +1,6 @@
 {
     "name": "laravel-notification-channels/twilio",
-    "description": "Provides Twilio notification channel for Laravel.",
+    "description": "Provides Twilio notification channel for Laravel",
     "keywords": ["laravel", "twilio", "notification", "sms", "call", "mms"],
     "license": "MIT",
     "support": {
@@ -13,15 +13,21 @@
             "email": "[email protected]",
             "homepage": "https://github.com/gregoriohc",
             "role": "Developer"
+        },
+        {
+            "name": "atymic",
+            "email": "[email protected]",
+            "homepage": "https://atymic.dev",
+            "role": "Developer"
         }
     ],
     "require": {
         "php": ">=7.2",
-        "twilio/sdk": "~5.16",
-        "illuminate/notifications": "^5.5 || ^6.0 || ^7.0",
-        "illuminate/support": "^5.5 || ^6.0 || ^7.0",
-        "illuminate/events": "^5.5 || ^6.0 || ^7.0",
-        "illuminate/queue": "^5.5 || ^6.0 || ^7.0"
+        "twilio/sdk": "~6.0",
+        "illuminate/notifications": "^5.8 || ^6.0 || ^7.0",
+        "illuminate/support": "^5.8 || ^6.0 || ^7.0",
+        "illuminate/events": "^5.8 || ^6.0 || ^7.0",
+        "illuminate/queue": "^5.8 || ^6.0 || ^7.0"
     },
     "require-dev": {
         "mockery/mockery": "^1.3",

config/twilio-notification-channel.php

@@ -0,0 +1,31 @@
+<?php
+
+return [
+    'username' => env('TWILIO_USERNAME'), // optional when using auth token
+    'password' => env('TWILIO_PASSWORD'), // optional when using auth token
+    'auth_token' => env('TWILIO_AUTH_TOKEN'), // optional when using username and password
+    'account_sid' => env('TWILIO_ACCOUNT_SID'),
+
+    'from' => env('TWILIO_FROM'), // optional
+    'alphanumeric_sender' => env('TWILIO_ALPHA_SENDER'),
+
+    /**
+     * Specify a number where all calls/messages should be routed. This can be used in development/staging environments
+     * for testing.
+     */
+    'debug_to' => env('TWILIO_DEBUG_TO'),
+
+    /**
+     * If an exception is thrown with one of these error codes, it will be caught & suppressed.
+     * To replicate the 2.x behaviour, specify '*' in the array, which will cause all exceptions to be suppressed.
+     * Suppressed errors will not be logged or reported, but the `NotificationFailed` event will be emitted.
+     *
+     * @see https://www.twilio.com/docs/api/errors
+     */
+    'ignored_error_codes' => [
+        21608, // The 'to' phone number provided is not yet verified for this account.
+        21211, // Invalid 'To' Phone Number
+        21614, // 'To' number is not a valid mobile number
+        21408, // Permission to send an SMS has not been enabled for the region indicated by the 'To' number
+    ],
+];

src/Exceptions/CouldNotSendNotification.php

@@ -1,46 +1,37 @@
 <?php
 
+declare(strict_types=1);
+
 namespace NotificationChannels\Twilio\Exceptions;
 
-use NotificationChannels\Twilio\CallMessage;
-use NotificationChannels\Twilio\SmsMessage;
+use NotificationChannels\Twilio\TwilioCallMessage;
+use NotificationChannels\Twilio\TwilioSmsMessage;
 
 class CouldNotSendNotification extends \Exception
 {
-    /**
-     * @param mixed $message
-     *
-     * @return static
-     */
-    public static function invalidMessageObject($message)
+    public static function invalidMessageObject($message): self
     {
-        $className = get_class($message) ?: 'Unknown';
+        $className = is_object($message) ? get_class($message) : 'Unknown';
 
         return new static(
             "Notification was not sent. Message object class `{$className}` is invalid. It should
-            be either `".SmsMessage::class.'` or `'.CallMessage::class.'`');
+            be either `".TwilioSmsMessage::class.'` or `'.TwilioCallMessage::class.'`');
     }
 
-    /**
-     * @return static
-     */
-    public static function missingFrom()
+    public static function missingFrom(): self
     {
         return new static('Notification was not sent. Missing `from` number.');
     }
 
-    /**
-     * @return static
-     */
-    public static function invalidReceiver()
+    public static function invalidReceiver(): self
     {
         return new static(
             'The notifiable did not have a receiving phone number. Add a routeNotificationForTwilio
             method or a phone_number attribute to your notifiable.'
         );
     }
 
-    public static function missingAlphaNumericSender()
+    public static function missingAlphaNumericSender(): self
     {
         return new static(
             'Notification was not sent. Missing `alphanumeric_sender` in config'

src/Exceptions/InvalidConfigException.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace NotificationChannels\Twilio\Exceptions;
+
+class InvalidConfigException extends \Exception
+{
+    public static function missingConfig(): self
+    {
+        return new self('Missing config. You must set either the username & password or SID and auth token');
+    }
+}

src/Twilio.php

@@ -3,26 +3,19 @@
 namespace NotificationChannels\Twilio;
 
 use NotificationChannels\Twilio\Exceptions\CouldNotSendNotification;
+use Twilio\Exceptions\TwilioException;
+use Twilio\Rest\Api\V2010\Account\CallInstance;
+use Twilio\Rest\Api\V2010\Account\MessageInstance;
 use Twilio\Rest\Client as TwilioService;
 
 class Twilio
 {
-    /**
-     * @var TwilioService
-     */
+    /** @var TwilioService */
     protected $twilioService;
 
-    /**
-     * @var TwilioConfig
-     */
-    private $config;
+    /** @var TwilioConfig */
+    public $config;
 
-    /**
-     * Twilio constructor.
-     *
-     * @param  TwilioService $twilioService
-     * @param TwilioConfig $config
-     */
     public function __construct(TwilioService $twilioService, TwilioConfig $config)
     {
         $this->twilioService = $twilioService;
@@ -32,13 +25,15 @@ public function __construct(TwilioService $twilioService, TwilioConfig $config)
     /**
      * Send a TwilioMessage to the a phone number.
      *
-     * @param  TwilioMessage $message
-     * @param  string $to
+     * @param TwilioMessage $message
+     * @param string|null $to
      * @param bool $useAlphanumericSender
+     *
      * @return mixed
-     * @throws \Twilio\Exceptions\TwilioException
+     * @throws TwilioException
+     * @throws CouldNotSendNotification
      */
-    public function sendMessage(TwilioMessage $message, $to, $useAlphanumericSender = false)
+    public function sendMessage(TwilioMessage $message, ?string $to, bool $useAlphanumericSender = false)
     {
         if ($message instanceof TwilioSmsMessage) {
             if ($useAlphanumericSender && $sender = $this->getAlphanumericSender()) {
@@ -59,11 +54,20 @@ public function sendMessage(TwilioMessage $message, $to, $useAlphanumericSender
      * Send an sms message using the Twilio Service.
      *
      * @param TwilioSmsMessage $message
-     * @param string $to
-     * @return \Twilio\Rest\Api\V2010\Account\MessageInstance
+     * @param string|null $to
+     *
+     * @return MessageInstance
+     * @throws CouldNotSendNotification
+     * @throws TwilioException
      */
-    protected function sendSmsMessage(TwilioSmsMessage $message, $to)
+    protected function sendSmsMessage(TwilioSmsMessage $message, ?string $to): MessageInstance
     {
+        $debugTo = $this->config->getDebugTo();
+
+        if ($debugTo !== null) {
+            $to = $debugTo;
+        }
+
         $params = [
             'body' => trim($message->content),
         ];
@@ -76,7 +80,7 @@ protected function sendSmsMessage(TwilioSmsMessage $message, $to)
             $params['from'] = $from;
         }
 
-        if (! $from && ! $messagingServiceSid) {
+        if (empty($from) && empty($messagingServiceSid)) {
             throw CouldNotSendNotification::missingFrom();
         }
 
@@ -103,11 +107,13 @@ protected function sendSmsMessage(TwilioSmsMessage $message, $to)
      * Make a call using the Twilio Service.
      *
      * @param TwilioCallMessage $message
-     * @param string $to
-     * @return \Twilio\Rest\Api\V2010\Account\CallInstance
-     * @throws \Twilio\Exceptions\TwilioException
+     * @param string|null $to
+     *
+     * @return CallInstance
+     * @throws TwilioException
+     * @throws CouldNotSendNotification
      */
-    protected function makeCall(TwilioCallMessage $message, $to)
+    protected function makeCall(TwilioCallMessage $message, ?string $to): CallInstance
     {
         $params = [
             'url' => trim($message->content),
@@ -137,9 +143,9 @@ protected function makeCall(TwilioCallMessage $message, $to)
      * Get the from address from message, or config.
      *
      * @param TwilioMessage $message
-     * @return string
+     * @return string|null
      */
-    protected function getFrom(TwilioMessage $message)
+    protected function getFrom(TwilioMessage $message): ?string
     {
         return $message->getFrom() ?: $this->config->getFrom();
     }
@@ -148,9 +154,9 @@ protected function getFrom(TwilioMessage $message)
      * Get the messaging service SID from message, or config.
      *
      * @param TwilioSmsMessage $message
-     * @return string
+     * @return string|null
      */
-    protected function getMessagingServiceSid(TwilioSmsMessage $message)
+    protected function getMessagingServiceSid(TwilioSmsMessage $message): ?string
     {
         return $message->getMessagingServiceSid() ?: $this->config->getServiceSid();
     }
@@ -160,11 +166,9 @@ protected function getMessagingServiceSid(TwilioSmsMessage $message)
      *
      * @return string|null
      */
-    protected function getAlphanumericSender()
+    protected function getAlphanumericSender(): ?string
     {
-        if ($sender = $this->config->getAlphanumericSender()) {
-            return $sender;
-        }
+        return $this->config->getAlphanumericSender();
     }
 
     /**
@@ -173,7 +177,7 @@ protected function getAlphanumericSender()
      * @param array $optionalParams
      * @return Twilio
      */
-    protected function fillOptionalParams(&$params, $message, $optionalParams)
+    protected function fillOptionalParams(&$params, $message, $optionalParams): self
     {
         foreach ($optionalParams as $optionalParam) {
             if ($message->$optionalParam) {