Getting Started

Minimal Setup

Install the package via Composer:

composer require symfony/allmysms-notifier

Configure the DSN in your .env:
```
ALLMYSMS_DSN=allmysms://LOGIN:APIKEY@default?from=SENDER_NUMBER
```
Replace LOGIN, APIKEY, and SENDER_NUMBER with your AllMySms credentials.

Register the transport in Laravel’s config/services.php:

'notifier' => [
    'transports' => [
        'allmysms' => [
            'dsn' => env('ALLMYSMS_DSN'),
        ],
    ],
],

First SMS send (using Laravel’s Notifiable):

use Illuminate\Notifications\Notifiable;
use App\Notifications\SmsNotification;

class User extends Model
{
    use Notifiable;
}

// In a controller or job:
$user->notify(new SmsNotification('Your verification code is: 12345'));

Create a notification class (extend Illuminate\Notifications\Notification):

use Illuminate\Notifications\Notification;
use Symfony\Component\Notifier\Message\SmsMessage;
use Symfony\Component\Notifier\Bridge\AllMySms\AllMySmsOptions;

class SmsNotification extends Notification
{
    protected $message;

    public function __construct(string $message)
    {
        $this->message = $message;
    }

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

    public function toSms($notifiable)
    {
        $sms = new SmsMessage($notifiable->phone, $this->message);

        // Optional: Add AllMySms-specific options
        $options = (new AllMySmsOptions())
            ->campaignName('Verification')
            ->uniqueIdentifier($notifiable->id);

        $sms->options($options);

        return $sms;
    }
}

Implementation Patterns

Core Workflow: Sending SMS

Laravel Job Integration (Recommended for async):

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Notifications\Notification;

class SendSmsJob implements ShouldQueue
{
    use Dispatchable, Queueable;

    public function handle()
    {
        $user = User::find(1);
        $user->notify(new SmsNotification('Hello from queue!'));
    }
}

Direct Sending (Sync, for low-volume use):

use Symfony\Component\Notifier\Notifier;
use Symfony\Component\Notifier\Message\SmsMessage;

$notifier = new Notifier([new AllMySmsTransport(env('ALLMYSMS_DSN'))]);
$message = new SmsMessage('+1234567890', 'Hello!');
$notifier->send($message);

Advanced Patterns

Dynamic Sender IDs:

// Override sender per message
$sms->options((new AllMySmsOptions())->from('CUSTOM_SENDER'));

Scheduled SMS:

$sms->options((new AllMySmsOptions())->date('2023-12-31 12:00:00'));

Simulated SMS (Testing):

$sms->options((new AllMySmsOptions())->simulate(1));

Campaign Tracking:

$sms->options((new AllMySmsOptions())->campaignName('Marketing_2023'));

Retry Logic (Laravel Queues):

// In SendSmsJob:
public function retryAfter()
{
    return now()->addMinutes(5); // Retry after 5 minutes
}

Integration with Laravel Ecosystem

Events: Listen to Illuminate\Notifications\Events\NotificationSent or NotificationFailed:

Notification::sent(function ($notification, $channel) {
    if ($channel === 'sms') {
        Log::info('SMS sent to ' . $notification->toSms()->getPhone());
    }
});

Rate Limiting: Use Laravel’s throttle middleware for jobs:

SendSmsJob::dispatch()->throttle(60); // 60 messages/minute

Fallbacks: Combine with email notifications for critical alerts:

public function via($notifiable)
{
    return ['sms', 'mail'];
}

Gotchas and Tips

Pitfalls

DSN Format Sensitivity:

Ensure the DSN follows allmysms://LOGIN:APIKEY@default?from=SENDER exactly.

Fix: Validate the DSN in a config file or use a helper:

if (!preg_match('/^allmysms:\/\/[^:]+:[^@]+@default\?from=[^&]+$/', env('ALLMYSMS_DSN'))) {
    throw new \RuntimeException('Invalid ALLMYSMS_DSN format');
}

Character Limits:
- AllMySMS enforces a 70-character limit per segment (concatenated SMS may be needed for longer messages).
- Fix: Use Laravel’s Str::limit or a package like spatie/array-to-xml for segmentation:
```
$message = Str::limit($longMessage, 60, '...');
```
Async Delays:
- Laravel queues may introduce delays. For time-sensitive SMS (e.g., OTPs), consider:
  - Sync sending (disable queue for critical paths).
  - Database-backed queues (e.g., database driver) for immediate processing.

Error Handling:

AllMySMS may return HTTP 4xx/5xx errors. Laravel’s queue retries help, but log failures explicitly:

Notification::failed(function ($notification, $exception) {
    Log::error('SMS failed', [
        'phone' => $notification->toSms()->getPhone(),
        'exception' => $exception->getMessage(),
    ]);
});

Testing:

Use simulate(1) in AllMySmsOptions for test environments.

Mock the AllMySmsTransport in unit tests:

$transport = $this->createMock(AllMySmsTransport::class);
$transport->method('send')->willReturn(new SentMessage());
$notifier = new Notifier([$transport]);

Tips

Environment-Specific Config: Use Laravel’s config('services.notifier.transports.allmysms') to override DSN per environment:

// config/services.php
'transports' => [
    'allmysms' => [
        'dsn' => env('ALLMYSMS_DSN'),
        'from' => env('ALLMYSMS_FROM', '36180'), // Fallback sender
    ],
],

Template Reusability: Create a base SmsNotification class to avoid repetition:

abstract class BaseSmsNotification extends Notification
{
    protected $message;

    public function __construct(string $message)
    {
        $this->message = $message;
    }

    public function toSms($notifiable)
    {
        $sms = new SmsMessage($notifiable->phone, $this->message);
        $sms->options($this->getAllMySmsOptions());
        return $sms;
    }

    protected function getAllMySmsOptions(): AllMySmsOptions
    {
        return new AllMySmsOptions();
    }
}

Logging Delivery Status: Extend SentMessage to include AllMySMS-specific metadata:

use Symfony\Component\Notifier\Message\SentMessage;

class AllMySmsSentMessage extends SentMessage
{
    public function __construct(
        string $messageId,
        array $additionalInfo = []
    ) {
        parent::__construct($messageId, $additionalInfo);
        $this->additionalInfo['allmysms'] = $additionalInfo['allmysms'] ?? [];
    }
}

Performance:

Batch SMS sends using Laravel’s Bus::batch:

Bus::batch([
    new SendSmsJob($user1, 'Message 1'),
    new SendSmsJob($user2, 'Message 2'),
])->then(function (Batch $batch) {
    // Handle completion
});

Avoid sending SMS in loops without chunking (e.g., use collect($users)->chunk(50)).

Allmysms Notifier Laravel Package