README

This package makes it easy to send SMS notifications using AtomPark from your Laravel application, using Laravel's built-in notification system.

Sending an SMS to a user becomes as simple as using:

$user->notify(new Invitation());

Installation

You can install the package via composer:

composer require andriichuk/laravel-atompark-sms-channel

The service provider will be auto-discovered by Laravel.

Setting up the AtomPark service

Add your AtomPark SMS credentials to the services.php config file:

// config/services.php

return [
    // ...

    'atompark' => [
        'sms' => [
            'sender' => env('ATOMPARK_SMS_SENDER'),
            'public_key' => env('ATOMPARK_SMS_PUBLIC_KEY'),
            'private_key' => env('ATOMPARK_SMS_PRIVATE_KEY'),
        ],
    ],
];

Then add the corresponding environment variables to your .env:

ATOMPARK_SMS_SENDER="Your Sender Name"
ATOMPARK_SMS_PUBLIC_KEY="your-public-key"
ATOMPARK_SMS_PRIVATE_KEY="your-private-key"

Usage

Notifiable model

In your notifiable model (typically User), add the routeNotificationForAtomPark method that returns a full mobile number including country code:

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

class User extends Authenticatable
{
    use Notifiable;

    public function routeNotificationForAtomPark(): string
    {
        return $this->phone; // e.g. +380991112233
    }
}

Notification class

Within your notification, add the AtomPark channel to the via method and implement toAtomPark to build the SMS message:

use Andriichuk\AtomParkSmsChannel\AtomParkChannel;
use Andriichuk\AtomParkSmsChannel\Sms;
use Illuminate\Notifications\Notification;

class Invitation extends Notification
{
    public function via($notifiable): array
    {
        return [AtomParkChannel::class];
    }

    public function toAtomPark($notifiable): Sms
    {
        return new Sms(
            text: 'You have been invited!',
            lifetime: 1, // 0 = maximum, 1/6/12/24 hours
        );
    }
}

Now you can send an SMS notification to a user:

$user->notify(new Invitation());

Anonymous notifications

You can also send SMS messages to phone numbers that are not associated with a notifiable model:

use Illuminate\Support\Facades\Notification;

Notification::route(AtomParkChannel::class, '+380991112233')
    ->notify(new Invitation());

The channel resolves the recipient phone from the notifiable (via routeNotificationFor(AtomParkChannel::class) or the notifiable’s string form), so your toAtomPark method can stay the same and omit the phone argument.

Available message options

The Sms value object supports:

• text (string) – the message body.
• phone (string, optional) – recipient phone number including country code; if omitted, the channel resolves it from the notifiable.
• lifetime (int) – message lifetime in hours (0 = maximum, 1, 6, 12, 24).

Error handling

AtomPark reports failures in the response body under an HTTP 200, so a rejected message is indistinguishable from a delivered one unless the body is inspected. The channel does that for you and throws CouldNotSendNotification when AtomPark returns an error, or when the body is not readable JSON:

use Andriichuk\AtomParkSmsChannel\Exceptions\CouldNotSendNotification;

try {
    $user->notify(new Invitation());
} catch (CouldNotSendNotification $exception) {
    $exception->errorCode;    // e.g. '-443'
    $exception->errorMessage; // e.g. 'Error sendSMS'
}

Every failure is also written to the error log channel, with the recipient number masked to its last four digits.

If your notification implements ShouldQueue, a failing send now fails the job, so it follows the retry and failed_jobs behaviour configured on that notification. Set $tries and $backoff to match how long you want the queue to keep retrying an outage.

Testing

Run the test suite with:

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Serhii Andriichuk
• All Contributors

License

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