Getting Started

Minimal Setup for Laravel

Install Dependencies (if using Symfony Notifier):
```
composer require symfony/http-client symfony/notifier symfony/octopush-notifier
```
For minimal risk, skip symfony/notifier and use Laravel’s Http facade instead.
Configure DSN in .env:
```
OCTOPUSH_DSN=octopush://USERLOGIN:APIKEY@default?from=YOUR_SENDER&type=FR
```
- Replace USERLOGIN with your Octopush email.
- Replace APIKEY with your Octopush API token.
- from = Sender ID (e.g., "+1234567890" or "YourApp").
- type = SMS route (XXX for LowCost, FR for Premium, WWW for World).

First Use Case: Send an SMS Option A (Direct HTTP - Recommended for Laravel):

use Illuminate\Support\Facades\Http;

$response = Http::withOptions(['auth' => [env('OCTOPUSH_USER'), env('OCTOPUSH_KEY')]])
    ->post('https://api.octopush.com/sms', [
        'to' => '+33612345678',
        'message' => 'Hello from Laravel!',
        'from' => env('OCTOPUSH_FROM'),
        'type' => env('OCTOPUSH_TYPE', 'FR'),
    ]);

Option B (Symfony Notifier - Higher Risk):

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

$notifier = new NotifierInterface([new OctopushTransport(env('OCTOPUSH_DSN'))]);
$notifier->send(new SmsMessage('Hello from Symfony!', '+33612345678'));

Verify Credentials:
- Check Octopush’s API documentation for valid from formats (e.g., alphanumeric sender IDs may require approval).
- Test with a low-cost SMS type (XXX) first.

Implementation Patterns

Workflows

1. SMS Notifications in Laravel

Pattern: Use Laravel’s Http facade for simplicity.

// app/Services/OctopushService.php
class OctopushService {
    public function send(string $to, string $message): bool {
        $response = Http::post('https://api.octopush.com/sms', [
            'to' => $to,
            'message' => $message,
            'from' => config('services.octopush.from'),
            'type' => config('services.octopush.type'),
        ])->auth(config('services.octopush.login'), config('services.octopush.key'));

        return $response->successful();
    }
}

Usage:

OctopushService::send('+33612345678', 'Your verification code: 12345');

2. Queue-Based SMS (Scalable)

Pattern: Dispatch a job to avoid blocking the request.

// app/Jobs/SendOctopushSms.php
class SendOctopushSms implements ShouldQueue {
    use Dispatchable, InteractsWithQueue, Queueable;

    public function handle() {
        Http::post('https://api.octopush.com/sms', [
            'to' => $this->to,
            'message' => $this->message,
            // ... other params
        ]);
    }
}

Dispatch:

SendOctopushSms::dispatch('+33612345678', 'Your order is confirmed!');

3. Symfony Notifier Integration (Advanced)

Pattern: Useful if already using Symfony’s Notifier for multi-channel notifications.

// config/services.php
'octopush' => [
    'dsn' => env('OCTOPUSH_DSN'),
],

// app/Providers/AppServiceProvider.php
public function register() {
    $this->app->singleton('octopush.transport', function () {
        return new \Symfony\Component\Notifier\Transport\OctopushTransport(
            env('OCTOPUSH_DSN')
        );
    });
}

Usage:

$notifier = new \Symfony\Component\Notifier\Notifier([
    $this->app->make('octopush.transport'),
]);
$notifier->send(new \Symfony\Component\Notifier\Message\SmsMessage(
    'Hello via Symfony!',
    '+33612345678'
));

4. Dynamic Sender/Type

Pattern: Override from or type per message.

$response = Http::withOptions([
    'auth' => [env('OCTOPUSH_USER'), env('OCTOPUSH_KEY')],
    'query' => [
        'from' => 'DynamicSender',
        'type' => 'WWW', // World SMS
    ],
])->post('https://api.octopush.com/sms', [
    'to' => '+33612345678',
    'message' => 'Global message!',
]);

Integration Tips

Environment Variables: Store credentials in .env:

OCTOPUSH_LOGIN=your_email@example.com
OCTOPUSH_KEY=your_api_token
OCTOPUSH_FROM=YourApp
OCTOPUSH_TYPE=FR

Error Handling: Octopush returns HTTP codes (e.g., 400 for invalid from, 429 for rate limits). Handle gracefully:
```
$response = Http::post(...)->throwUnlessSuccessful();
```

Logging: Log failed sends for debugging:

if (!$response->successful()) {
    \Log::error('Octopush failed', [
        'status' => $response->status(),
        'body' => $response->body(),
        'to' => $to,
    ]);
}

Rate Limiting: Octopush enforces rate limits. Implement exponential backoff:

use Symfony\Component\Mime\Header\UnstructuredHeader;

$response = Http::withHeaders([
    'X-RateLimit-Retry-After' => new UnstructuredHeader('Retry-After'),
])->post(...);

Gotchas and Tips

Pitfalls

Sender ID Restrictions:
- Alphanumeric sender IDs (e.g., "MyApp") require pre-approval from Octopush. Use numeric IDs (e.g., "+1234567890") for testing.
- Fix: Check Octopush’s sender ID guidelines.
DSN Format Sensitivity:
- The DSN (octopush://USER:KEY@default?from=FROM&type=TYPE) must include @default and query params. Missing these causes:
```
new \Symfony\Component\Notifier\Exception\TransportException('Invalid DSN')
```
- Fix: Always use the full DSN format:
```
OCTOPUSH_DSN=octopush://user:key@default?from=Sender&type=FR
```
Symfony Dependency Conflicts:
- If your Laravel app uses guzzlehttp/guzzle, symfony/http-client may conflict. Symptom:
```
Composer could not find a compatible version of guzzlehttp/guzzle.
```
- Fix: Use Laravel’s Http facade instead of Symfony’s Notifier.
Character Limits:
- Octopush enforces 160 characters for SMS. Longer messages are split (extra cost).
- Fix: Truncate or use a premium route (type=FR) for longer messages.

API Key Exposure:

Hardcoding keys in DSN strings or config files risks leaks. Symptom:

new \Symfony\Component\Notifier\Exception\TransportException('Invalid credentials')

Fix: Use Laravel’s .env and avoid exposing keys in logs:

// In OctopushTransport (if extending)
$this->client->setCredentials(
    env('OCTOPUSH_LOGIN'),
    env('OCTOPUSH_KEY')
);

Timeouts:
- Octopush API may time out during peak hours. Symptom:
```
cURL error 28: Connection timed out
```
- **

Octopush Notifier Laravel Package