README

This package makes it easy to send SMS Broadcast SMS notifications with Laravel 8

Contents

• Requirements
• Installation
• Setting up your SMSBroadcast account
• Using a custom logging channel
• Usage
  • Available methods
  • Available events
• Changelog
• Testing
• Security
• Contributing
• Credits
• License

Requirements

• Sign up for a free SMS Broadcast account

Installation

You can install the package via composer:

composer require hachetaustralia/smsbroadcast

for Laravel 6 and 7, please use the 2.x version of this package. for Laravel 5.8 or lower, please use the 1.x version of this package.

Setting up your SMSBroadcast account

Add the environment variables to your config/services.php:

// config/services.php
...
'smsbroadcast' => [
    'username' => env('SMSBROADCAST_USERNAME'),
    'password' => env('SMSBROADCAST_PASSWORD'),
    'from' => env('SMSBROADCAST_FROM'),
    'sandbox' => env('SMSBROADCAST_SANDBOX'),
],
...

Add your SMS Broadcast username and password as well as the default from number/alphanumeric code to your .env:

// .env
...
SMSBROADCAST_USERNAME=
SMSBROADCAST_PASSWORD=
SMSBROADCAST_FROM=
SMSBROADCAST_SANDBOX=false
],
...

Notice: The from can contain a maximum of 11 alphanumeric characters. You can also specify sandbox to true for testing (no post requests are made).

Setup your route on your notifiable model such as your User with the default destination for that model (single number or array of numbers).

namespace App;

use Illuminate\Notifications\Notifiable;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use Notifiable;

    public function routeNotificationForSmsBroadcast()
    {
        return $this->mobile;
    }
}

namespace App;

use Illuminate\Notifications\Notifiable;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use Notifiable;

    public function routeNotificationForSmsBroadcast()
    {
        return [ $this->mobile_primary, $this->mobile_secondary ];
    }
}

Using a Custom Logging Channel

Debug logs will automatically use your default logging channel, however you can specify a custom logging channel by adding the following to your config/services.php file:

// config/services.php
...
'smsbroadcast' => [
    'logging_channel' => env('SMSBROADCAST_LOGGING_CHANNEL'),
]
...

And the following to your .env file

// .env
...
SMSBROADCAST_LOGGING_CHANNEL=
...

Usage

Now you can use the channel in your via() method inside the notification:

use NotificationChannels\SMSBroadcast\SMSBroadcastChannel;
use NotificationChannels\SMSBroadcast\SMSBroadcastMessage;
use Illuminate\Notifications\Notification;

class VpsServerOrdered extends Notification
{
    public function via($notifiable)
    {
        return [SMSBroadcastChannel::class];
    }

    public function toSMSBroadcast($notifiable)
    {
        return (new SMSBroadcastMessage("Your {$notifiable->service} was ordered!"));
    }
}

Available methods

Additionally you can add or change recipients (single value or array)

return (new SMSBroadcastMessage("Your {$notifiable->service} was ordered!"))->setRecipients($recipients);

In order to handle a status report you can also set a reference

return (new SMSBroadcastMessage("Your {$notifiable->service} was ordered!"))->setReference($id);

Maximum message splits are supported as well to determine the maximum number of SMS message credits to use per recipient. This defaults to 1.

return (new SMSBroadcastMessage("Your {$notifiable->service} was ordered!"))->setMaxSplit(2);

You can also delay message sending by a specified number of minutes

return (new SMSBroadcastMessage("Your {$notifiable->service} is ready to go!"))->setDelay(10);

Setting a private reference will not transmit to SMS Broadcast and be available should you need it on the MessageWasSent event as a property of the SMSBroadcastMessage. This is useful if you want to set something like a foreign key that you can utilise on a listener listening to the MessageWasSent event.

return (new SMSBroadcastMessage("Your {$notifiable->service} is ready to go!"))->setPrivateReference(12345);

If you wish to use SMS Broadcast's default two-way SMS number as the from number, simply setNoFrom() on the message instance

return (new SMSBroadcastMessage("Your {$notifiable->service} is ready to go!"))->setNoFrom();

Available events

SMS Broadcast Notification channel comes with handy events which provides the required information about the SMS messages.

1. Message Was Sent (NotificationChannels\SMSBroadcast\Events\MessageWasSent)

Example:

namespace App\Listeners;

use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Contracts\Queue\ShouldQueue;
use NotificationChannels\SMSBroadcast\Events\MessageWasSent;

class SentMessageHandler
{
    /**
     * Handle the event.
     *
     * @param  MessageWasSent  $event
     * @return void
     */
    public function handle(MessageWasSent $event)
    {
        $response = $event->response;
        $message = $event->message;
    }
}

Changelog

Please see CHANGELOG for more information what has changed recently.

Testing

$ composer test

Security

If you discover any security related issues, please email support@hachet.com.au instead of using the issue tracker.

Contributing

Please see CONTRIBUTING for details.

Credits

• Hatchet
• glennforrest

License

The NoHarm Licence. Please see License File for more information.