README

Installation

Install Package

You can install this package via composer:

composer require squareetlabs/laravel-smsup

Add Service Provider & Facade

For Laravel 5.5+

Once the package is added, the service provider and facade will be autodiscovered.

For Older versions of Laravel

Add the ServiceProvider to the providers array in config/app.php:

SquareetLabs\LaravelSmsUp\SmsUpServiceProvider::class,

Add the Facade to the aliases array in config/app.php:

'SmsUp' => SquareetLabs\LaravelSmsUp\Facades\SmsUp::class,

Configuration

Add your SmsUp API key to your config/services.php file:

return [   
    ...
    ...
    'smsUp' => [
         'key' => env('SMSUP_KEY'),
         'test_mode' => env('SMSUP_TEST_MODE') // true or false
    ]
    ...

Set test_mode to true if you want to simulate submitting messages, it's perfect for testing and debugging, it has no cost.

Usage

Using Laravel Notification

Use artisan to create a notification:

php artisan make:notification someNotification

Return [smsUp] in the public function via($notifiable) method of your notification:

public function via(INotifiable $notifiable)
{
    return ['smsUp'];
}

Add the method public function toSmsUp($notifiable) to your notification, and return an instance of SmsUpMessage:

use SquareetLabs\LaravelSmsUp\SmsUpMessage;
...
public function toSmsUp(INotifiable $notifiable)
{
    $message = new SmsUpMessage();
    $message->to('34xxxxxxxxx') 
        ->from('Foo')
        ->text('Text of your message')
        ->custom('MyMsgID-12345') // Optional. 
        ->link('http://www.google.com'); // Optional

    return $message;
}

If you don't indicate the parameter to, make sure your notifiable entity has routeNotificationForSmsUp method defined:

/**
 * Route notifications for the SmsUp channel.
 *
 * @return string
 */
public function routeNotificationForSmsUp(): string
{
    return $this->phone;
}

To include the link in the message you must put the tag {LINK} in the area of the text of the sms you want.

example:

->text('Hi John! See our new offers only available for you: {LINK}');

Using SmsUp Facade

Send messages

use SquareetLabs\LaravelSmsUp\SmsUpMessage;
use SquareetLabs\LaravelSmsUp\Facades\SmsUp;
...
$message1 = new SmsUpMessage();
$message->to('34xxxxxxxxx') 
    ->from('Foo')
    ->text('Text of your message')
    ->custom('MyMsgID-12345') // Optional. 
    ->link('http://www.google.com'); // Optional
$message2 = new SmsUpMessage();
$message2->to('34xxxxxxxxx') 
    ->from('Foo')
    ->text('Text of your message')
    ->custom('MyMsgID-12346') // Optional. 
    ->link('http://www.google.com'); // Optional
$messages = [
    $message1->formatData(),
    $message2->formatData()
];
SmsUp::sendMessages($messages);

Get SmsUp account balance

use SquareetLabs\LaravelSmsUp\Facades\SmsUp;
...
$balance = SmsUp::getBalance();

Verify phone number by SmsUp

This method return true or false. This service has a cost charged by SmsUp.

use SquareetLabs\LaravelSmsUp\Facades\SmsUp;
...
$verify = SmsUp::verifyPhone('34xxxxxxxxx');

Available Events

LaravelSmsUp comes with handy events which provides the required information about the SMS messages.

Messages Was Sent

Triggered when one or more messages are sent.

Example:

use SquareetLabs\LaravelSmsUp\Events\SmsUpMessageWasSent;
use SquareetLabs\LaravelSmsUp\SmsUpMessage;
use SquareetLabs\LaravelSmsUp\SmsUpResponse;
use SquareetLabs\LaravelSmsUp\SmsUpResponseMessage;

class SmsUpMessageSentListener
{
    /**
     * Handle the event.
     *
     * @param  SmsUpMessageWasSent  $event
     * @return void
     */
    public function handle(SmsUpMessageWasSent $event)
    {
        $response = $event->response; // Class SmsUpResponse
        $message = $event->message; // Class SmsUpMessage

        if ($response->getStatus() != 'ok') {
            $yourModel = YourModel::find($message->getCustom());
            $yourModel->sms_status = $response->getStatus();
            $yourModel->sms_error_id = $response->getErrorId();
            $yourModel->sms_error_msg = $response->getErrorMsg();
            $yourModel->save();
        } else {
            foreach ($response->getResult() as $responseMessage) { // class SmsUpResponseMessage
                $yourModel = YourModel::find($responseMessage->getCustom());
                $yourModel->sms_status = $responseMessage->getStatus();
                $yourModel->sms_id = $responseMessage->getSmsId();
                $yourModel->sms_error_id = $responseMessage->getErrorId();
                $yourModel->sms_error_msg = $responseMessage->getErrorMsg();
                $yourModel->save();
            }
        }
    }
}

In your EventServiceProvider:

protected $listen = [
        ...
        'SquareetLabs\LaravelSmsUp\Events\SmsUpMessageWasSent' => [
            'App\Listeners\SmsUpMessageSentListener',
        ],
    ];

SmsUp Report Received

Triggered when a status report of sent sms is received from SmsUp. The callback url passed to SmsUp is: http://yourserver/yourapplication/smsup/report.

Example:

use SquareetLabs\LaravelSmsUp\Events\SmsUpReportWasReceived;
use SquareetLabs\LaravelSmsUp\SmsUpReportResponse;
use SquareetLabs\LaravelSmsUp\SmsUpReportResponseMessage;

class SmsUpReportReceivedListener
{
    /**
     * Handle the event.
     *
     * @param  SmsUpReportWasReceived  $event
     * @return void
     */
    public function handle(SmsUpReportWasReceived $event)
    {
        $response = $event->response; // Class SmsUpReportResponse
        
        foreach ($response->getResponseMessages() as $responseMessage) { // Class SmsUpReportResponseMessage
            $yourModel = YourModel::find($responseMessage->getCustom());
            $yourModel->sms_status = $responseMessage->getStatus();
            $yourModel->sms_delivery_at = $responseMessage->getDlrDate();
            $yourModel->save();
        }
    }
}

In your EventServiceProvider:

protected $listen = [
        ...
        'SquareetLabs\LaravelSmsUp\Events\SmsUpReportWasReceived' => [
            'App\Listeners\SmsUpReportReceivedListener',
        ],
    ];

SmsUp API Documentation

Visit SmsUp API Documentation for more information.

Support

Feel free to post your issues in the issues section.

Credits

License

The MIT License (MIT). Please see License File for more information.

squareetlabs / laravel-smsup

Maintainers

Details