Download the PHP package rolfhaug/laravel-front-sms without Composer

Laravel Front SMS

Send SMS to your users with Laravel and Front SMS Gateway API through the traditional notification interface of Laravel.

The package support outbound and inbound SMS, as well as and incoming delivery reports.

Quick usage example

1. Create new SMS message

Adjust your newly created message.

Send it through the notifiable user.

Installation

The Laravel Front SMS package can be installed via composer:

The package will automatically register a service provider.

You need to publish the config and migration files:

If you do not have a phone column on the user model already. Publish the user related migrations:

Please note: If you're serving only one market, you can optionally delete the country_code migration file and rely on the config setting instead. More on this later.

Then run the migrations

If you use Artisan’s migrate:rollback or migrate:refresh commands you should edit the migration files and uncomment the down methods.

Configure

Add your configuration in your .env file.

If you want to receive Delivery Reports or Inbound SMS Messages you must exclude the SMS api routes from CSRF Verification.

Register your Delivery report URL in your Front settings page

Register your Incoming SMS URL in your Front settings page

Then add the RolfHaug\FrontSms\Traits\Smsable trait to your user model.

Required data

Country Code

All messages must have a known geographic region (called country code), so we can format the recipients number correctly. This can be set three ways:

1. By specifying an E.164 formatted phone number. E.g. +4790012345
2. By specifying a country_code field on the user model (database column or Eloquent accessor)
3. Setting default region in the config file. E.g. FRONT_DEFAULT_REGION=NO

If you're serving one market, it is recommended to stick to option 3. If you're serving multiple markets, it's recommended to go with option 2.

Phone field

Your user model (or notifiable model) must have a phone field.

The field name for the phone can be customized in the .env file. If you for instance want to use a field called telephone instead, you can add the following to your .env file.

Traits

If you want to send SMS to your User model, you must use the Notifiable trait and the Smsable trait (see paths in above example).

Notifiable is a native Laravel trait. The Smsable trait adds two methods getFormattedPhone() and getCountryCode() that are necessary to successfully send SMS. These methods validate and format the recipients number before sending the SMS.

Create new messages

The package provides a convenient command to create new messages.

This will create and scaffold a new SMS notification class under the App/Notifications/Sms directory.

This can be sent through a user that uses the Notifiable and Smsable traits, as mentioned above.

You are free to store your classes in a different directory. It should extend the RolfHaug\FrontSms\Notifications\SmsNotification class.

You can also use the SmsNotification class directly.

Inbound Messages

Inbound messages can be access through the RolfHaug\FrontSms\FrontInboundMessage model.

If you prefer to use another model name, you could create a new model in your project and extend the FrontInboundMessage model.

Then get all inbound messages like this:

Tips

It is recommended to use vsprintf in the getMessage function to compile dynamic data from the notifiable (user), like the example above.

If you want to pass in additional dependencies, it can be done in the constructor.

Success 🎉

You are now ready to send SMS to your users.

Route - Delivery Reports

Front will send delivery reports on outbound SMS messages to the url you defined in your Front settings page. By default the route should be set to yourdomain.com/sms/reports.

You can override it by creating your own POST route and use RolfHaug\FrontSms\Http\Controllers\DeliveryStatusController@store.

Route - Inbound SMS Messages

Front will send inbound SMS messages to the url you defined in your Front settings page. By default the route should be set to yourdomain.com/sms/inbound.

You can override it by creating your own POST route and use RolfHaug\FrontSms\Http\Controllers\InboundMessageController@store.

Testing

The package use the Laravel Notification Interface, so you can test the notifications with Notification Fake.

There are many ways to test on-demand notifications, one way to do it like this:

Tests could look something like this:

Debugging

Set FRONT_FAKE_MESSAGES=true in your .env file to get messages outputted in the Laravel Log. Messages will not be sent to Front with this feature enabled.

Incoming SMS to local environment

If you want to test your system by receiving actual DeliveryReports or Inbound SMS Messages you can use ngrok.

1. Create a free account claim your static domain
2. Claim your static domain from ngrok
3. Enter your static domain in the Front settings page your-ngrok-domain.com/sms/report and your-ngrok-domain.com/sms/inbound
4. Activate ngrok in your local environment ngrok http --domain=your-ngrok-domaincom 80
5. Inbound SMS and Delivery reports will now arrive in your local environment