Getting Started

Minimal Setup

Install the package:

composer require symfony/vonage-notifier

Configure DSN in .env:
```
VONAGE_DSN=vonage://KEY:SECRET@default?from=FROM
```
Replace KEY, SECRET, and FROM with your Vonage credentials and sender ID.

First use case: Send an SMS notification via Symfony Notifier:

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

$notifier = new NotifierInterface();
$message = new SmsMessage('Hello from Laravel!', 'recipient@example.com');
$notifier->send($message);

Where to Look First

Symfony Notifier Documentation: Symfony Notifier for message types (SMS, voice, etc.).
Vonage API Docs: Vonage API Reference for advanced use cases (e.g., templates, scheduling).
Webhook Validation: If using Vonage webhooks, update endpoints to use hash_equals() for signature validation (see Gotchas).

Implementation Patterns

Core Workflows

1. Sending Notifications

Use Symfony Notifier’s message types with Vonage transport:

// SMS
$message = new SmsMessage('Your OTP is 12345', '+1234567890');
$notifier->send($message);

// Voice call
$message = new VoiceMessage('Hello, this is a test call', '+1234567890');
$notifier->send($message);

// Email (if using Vonage's email API)
$message = new Email('welcome@example.com', 'Welcome!', 'Hello!');
$notifier->send($message);

2. Async Processing with Messenger

Leverage Symfony Messenger for background jobs:

use Symfony\Component\Messenger\MessageBusInterface;

$bus->dispatch(new SendSmsMessage('Hello', '+1234567890'));

Define a handler:

#[AsMessageHandler]
public function __invoke(SendSmsMessage $message)
{
    $notifier->send(new SmsMessage($message->content, $message->to));
}

3. Templates and Variables

Use Vonage’s template system for dynamic content:

$message = new SmsMessage(
    'Your balance is {{balance}}',
    '+1234567890',
    ['balance' => 100.50]
);

4. Webhook Handling

For Vonage callbacks (e.g., delivery receipts), validate signatures securely:

use Symfony\Component\Notifier\Bridge\Vonage\Webhook\VonageWebhookValidator;

$validator = new VonageWebhookValidator('your-secret');
if ($validator->isValidSignature($request->getContent(), $request->headers->get('X-Vonage-Signature'))) {
    // Process webhook (e.g., update notification status in DB)
}

Integration Tips

Laravel-Specific Patterns

Service Provider Setup:

public function register()
{
    $this->app->bind(NotifierInterface::class, function ($app) {
        return new Notifier([
            new VonageTransport($app['config']['vonage.dsn']),
        ]);
    });
}

Notification Channels: Extend VonageChannel for custom logic:

use Symfony\Component\Notifier\Bridge\Vonage\VonageChannel;

class CustomVonageChannel extends VonageChannel
{
    protected function getOptions(): array
    {
        return ['template' => 'custom_template'];
    }
}

Queued Notifications: Use Laravel Queues with Symfony Messenger:

$bus->dispatch(new SendSmsMessage('Hello'))->setOnQueue('vonage');

Advanced Use Cases

Scheduling: Use Vonage’s API to schedule messages (e.g., time-sensitive alerts).

Multi-Channel: Combine SMS, voice, and email in a single workflow:

$message = new MultipartMessage();
$message->addPart(new SmsMessage('SMS part', '+1234567890'));
$message->addPart(new Email('email@example.com', 'Email part', 'Hello!'));

Gotchas and Tips

Pitfalls

Webhook Signature Validation:

Issue: Older code may use insecure string comparison for Vonage webhook signatures.
Fix: Update to hash_equals() as shown in the webhook example.

Example Vulnerability:

// UNSAFE: Timing attack risk
if (hash_hmac('sha256', $content, $secret) === $signature) { ... }

// SAFE: Use hash_equals
if (hash_equals(hash_hmac('sha256', $content, $secret), $signature)) { ... }

DSN Configuration:
- Issue: Incorrect from parameter in DSN may cause failed deliveries.
- Fix: Verify the sender ID (from) matches Vonage’s registered numbers/emails.
- Example:
```
VONAGE_DSN=vonage://KEY:SECRET@default?from=+1234567890  # Must match Vonage's registered number
```
Rate Limits:
- Issue: Vonage enforces rate limits (e.g., 1 SMS/sec by default).
- Fix: Implement retries with exponential backoff using Symfony Messenger or Laravel Queues.
Character Limits:
- Issue: SMS messages are truncated to 160 characters (70 for Unicode).
- Fix: Use Vonage’s long-code (up to 459 characters) or split messages.
Webhook URLs:
- Issue: Vonage requires HTTPS for webhook endpoints.
- Fix: Ensure your endpoint uses HTTPS and is publicly accessible.

Debugging Tips

Enable Debugging:

$transport = new VonageTransport($dsn, [
    'debug' => true, // Logs requests/responses
]);

Check Vonage Dashboard:
- Monitor delivery status, errors, and usage in Vonage Console.

Log Failures:

$notifier->send($message)->then(
    null,
    function (Throwable $e, $message) {
        \Log::error("Failed to send {$message->getTransport()}: " . $e->getMessage());
    }
);

Test with Sandbox: Use Vonage’s sandbox environment for testing:
```
VONAGE_DSN=vonage://KEY:SECRET@sandbox?from=VonageSMS
```

Extension Points

Custom Transport: Extend VonageTransport to add features like:
- Custom headers.
- Request/response logging.
- Retry logic.

Message Transformers: Override VonageMessage to modify payloads before sending:

class CustomVonageMessage extends VonageMessage
{
    public function getBody(): string
    {
        return parent::getBody() . "\n-- Custom footer";
    }
}

Webhook Middleware: Add middleware to Vonage webhook handlers for:
- Authentication.
- Rate limiting.
- Logging.

Laravel Notifications: Create a custom channel:

use Illuminate\Notifications\VonageChannel;
use Symfony\Component\Notifier\Bridge\Vonage\VonageTransport;

class CustomVonageChannel extends VonageChannel
{
    public function __construct(VonageTransport $transport)
    {
        parent::__construct($transport);
    }
}

Configuration Quirks

DSN Format:
- Ensure the DSN follows the exact format: vonage://KEY:SECRET@transport?from=FROM.
- Supported transports: default (SMS/voice), email (if enabled).
Environment Variables:
- Avoid hardcoding secrets. Use Laravel’s .env or Symfony’s %env(VONAGE_DSN)%.

Timeouts:

Vonage API timeouts default to 30 seconds. Adjust if needed:

$transport = new VonageTransport($dsn, [
    'timeout' => 60, // 60 seconds
]);

Region-Specific Endpoints:
- Vonage offers regional endpoints (e.g., us, eu). Specify if needed:
```
VONAGE_DSN=vonage://KEY:SECRET@us?from=+12345678
```

Vonage Notifier Laravel Package