Getting Started

Minimal Setup for Laravel

Install the Package Use Composer to install the Symfony Notifier and Esendex bridge:
```
composer require symfony/notifier symfony/esendex-notifier
```
Configure the DSN Add the DSN to your .env file:
```
ESENDEX_DSN=esendex://EMAIL:PASSWORD@default?accountreference=ACCOUNT_REFERENCE&from=FROM
```
Replace placeholders with your Esendex credentials and account details.

Register the Transport In a service provider (e.g., AppServiceProvider), bind the Esendex transport:

use Symfony\Component\Notifier\Notifier;
use Symfony\Component\Notifier\Transport\EsendexTransport;

public function register()
{
    $this->app->singleton(Notifier::class, function ($app) {
        $dsn = $app['config']['services.esendex.dsn'];
        $transport = new EsendexTransport($dsn);
        return new Notifier([$transport]);
    });
}

Send Your First SMS Use Laravel’s notification system or Symfony’s Notifier directly:

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

$notifier = app(Notifier::class);
$message = new SmsMessage('+1234567890', 'Hello from Laravel!');
$notifier->send($message);

First Use Case: OTP Delivery

Leverage the package to send one-time passwords (OTPs) via SMS:

use Symfony\Component\Notifier\Message\SmsMessage;
use Symfony\Component\Notifier\Bridge\Esendex\EsendexOptions;

$sms = new SmsMessage('+1234567890', 'Your OTP is: 123456');
$options = (new EsendexOptions())
    ->accountReference('otp_account')
    ->reference('user_123_otp');
$sms->options($options);

$notifier->send($sms);

Implementation Patterns

Workflow: Sending SMS Notifications

Compose the Message Use Laravel’s SmsMessage or Symfony’s SmsMessage:
```
$message = new SmsMessage($recipientPhone, $messageBody);
```

Customize with EsendexOptions Attach Esendex-specific options (e.g., account reference, scheduling):

$options = (new EsendexOptions())
    ->accountReference('marketing_account')
    ->scheduledFor(new \DateTime('+1 hour'));
$message->options($options);

Send via Notifier Use Laravel’s Notifier facade or inject the Symfony Notifier:
```
Notifier::send($message);
// OR
$notifier->send($message);
```

Integration with Laravel Notifications

Extend Laravel’s Notification class to use the Esendex bridge:

use Illuminate\Notifications\Notification;
use Symfony\Component\Notifier\Message\SmsMessage;
use Symfony\Component\Notifier\Bridge\Esendex\EsendexOptions;

class EsendexSmsNotification extends Notification
{
    public function via($notifiable)
    {
        return ['esendex_sms'];
    }

    public function toEsendexSms($notifiable)
    {
        $message = new SmsMessage($notifiable->phone, 'Your notification message');
        $options = (new EsendexOptions())
            ->accountReference('notifications_account');
        $message->options($options);
        return $message;
    }
}

'channels' => [
    'esendex_sms' => [
        'driver' => 'esendex',
    ],
],

Async Processing with Queues

Use Laravel queues to handle Esendex sends asynchronously:

Dispatch the Notification

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

Configure the Queue Worker Ensure your queue worker processes the job:
```
php artisan queue:work
```

Handling Delivery Status

Esendex provides webhooks for delivery status updates. Set up a Laravel route to handle them:

Route::post('/esendex/webhook', function (Request $request) {
    // Parse Esendex webhook payload
    $status = $request->input('status');
    $messageId = $request->input('messageId');

    // Log or update database
    \Log::info("Esendex message $messageId status: $status");
});

Configure Esendex to send webhooks to this endpoint in their dashboard.

Gotchas and Tips

Pitfalls

DSN Configuration Errors
- Issue: Incorrect DSN format or missing credentials cause silent failures.
- Fix: Validate the DSN structure and test with a minimal setup:
```
ESENDEX_DSN=esendex://test@example.com:password@default?accountreference=test_account&from=TEST
```
- Debug: Check Symfony’s Notifier logs for connection errors.
Account Reference Mismatch
- Issue: Messages fail if the accountreference in the DSN doesn’t match Esendex’s configured account.
- Fix: Override per-message with EsendexOptions:
```
$options->accountReference('correct_account_ref');
```
Character Limits
- Issue: Esendex enforces SMS length limits (e.g., 160 characters per message). Long messages may be split or fail.
- Fix: Use EsendexOptions to set concatenated for long messages:
```
$options->concatenated(true);
```
Webhook Verification
- Issue: Esendex webhooks may be rejected if Laravel’s endpoint doesn’t verify the request signature.
- Fix: Implement signature verification (e.g., using Esendex’s X-Esendex-Signature header).

Debugging Tips

Enable Notifier Debug Mode Configure Symfony’s Notifier to log transport interactions:
```
$transport = new EsendexTransport($dsn, [
    'debug' => true,
]);
```

Inspect Raw API Calls Use Laravel’s logging to capture Esendex API requests:

\Log::debug('Esendex API Request:', [
    'url' => $request->getUri(),
    'body' => $request->getContent(),
]);

Test with Sandbox Credentials Use Esendex’s sandbox environment for testing:

ESENDEX_DSN=esendex://sandbox@example.com:password@default?accountreference=sandbox_account&from=SANDBOX

Extension Points

Custom EsendexOptions Extend EsendexOptions to add project-specific settings:

class CustomEsendexOptions extends EsendexOptions
{
    public function customTag(string $tag): self
    {
        $this->options['custom_tag'] = $tag;
        return $this;
    }
}

Override Transport Behavior Create a custom transport class to modify API calls:

use Symfony\Component\Notifier\Transport\EsendexTransport as BaseTransport;

class CustomEsendexTransport extends BaseTransport
{
    protected function doSend(SmsMessage $message): void
    {
        // Custom logic before sending
        $this->client->request('POST', '/messages', [
            'json' => [
                'to' => $message->getPhone(),
                'text' => $message->getContent(),
                'custom_tag' => 'my_tag',
            ],
        ]);
    }
}

Add Support for Email While the package focuses on SMS, you can extend it for email by creating a custom message class:

use Symfony\Component\Notifier\Message\EmailMessage;

class EsendexEmailMessage extends EmailMessage
{
    public function __construct(string $to, string $subject, string $html = null, string $text = null)
    {
        parent::__construct($to, $subject, $html, $text);
    }
}

Configuration Quirks

DSN Parameters
- from: Must match Esendex’s configured sender IDs (alphanumeric).
- accountreference: Required for API calls; defaults to the DSN value but can be overridden per-message.

Rate Limiting

Esendex enforces rate limits. Handle TooManyRequests exceptions gracefully:

try {
    $notifier->send($message);
} catch (\Symfony\Component\Notifier\Exception\TransportException $e) {
    if ($e->getCode() === 429) {
        \Log::warning('Esendex rate

Esendex Notifier Laravel Package