## Getting Started

### Minimal Setup
1. **Installation**
   ```bash
   composer require dunp/smsend-laravel

Publish the config file:

php artisan vendor:publish --provider="Dunp\SmsendLaravel\SmsendServiceProvider"

Configuration Edit .env with your Smsend API credentials:

SMSEND_API_KEY=your_api_key_here
SMSEND_API_SECRET=your_api_secret_here

First Use Case: Sending a Basic SMS

use Dunp\SmsendLaravel\Facades\Smsend;

Smsend::send([
    'to' => '391234567890',
    'text' => 'Hello from Laravel!'
]);

Verify Configuration Check the published config at config/smsend.php for additional settings like:
- Default sender ID
- Timeout settings
- Logging preferences

Implementation Patterns

Core Workflows

1. Sending SMS via Facade

Use the Smsend facade for simplicity in controllers/blades:

Smsend::send([
    'to' => '391234567890',
    'text' => 'Your OTP is 12345',
    'sender' => 'MyApp' // Optional
]);

2. Queueing SMS for Async Processing

Wrap the send call in a job to avoid blocking the request:

use Dunp\SmsendLaravel\Jobs\SendSmsJob;

SendSmsJob::dispatch([
    'to' => '391234567890',
    'text' => 'Your order is confirmed!'
]);

3. Handling Responses

Capture the API response for logging or retries:

$response = Smsend::send([...]);
if ($response->success()) {
    // Handle success
} else {
    logger()->error('SMS failed:', ['error' => $response->getError()]);
}

4. Batch Sending

Send to multiple recipients efficiently:

$recipients = ['391234567890', '399876543210'];
foreach ($recipients as $number) {
    Smsend::send(['to' => $number, 'text' => 'Batch message']);
}

5. Integration with Laravel Events

Trigger SMS on events (e.g., user registration):

// In an event listener
event(new Registered($user));

// In the listener
Smsend::send([
    'to' => $user->phone,
    'text' => 'Welcome to our platform!'
]);

Advanced Patterns

1. Customizing the Sender ID

Override the default sender per message:

Smsend::send([
    'to' => '391234567890',
    'text' => 'Message',
    'sender' => 'CustomSender' // Overrides config/smsend.php default
]);

2. Unicode Support

Enable Unicode for non-Latin characters:

Smsend::send([
    'to' => '391234567890',
    'text' => 'Ciao! 你好！',
    'unicode' => true
]);

3. Logging All SMS

Enable logging in config/smsend.php:

'log' => [
    'enabled' => true,
    'channel' => 'single', // or 'stack'
],

4. Testing with Mocks

Use Laravel’s mocking to test SMS logic:

$this->mock(Smsend::class)->shouldReceive('send')->once();

5. Fallback Mechanisms

Implement a fallback for failed sends (e.g., email):

try {
    Smsend::send([...]);
} catch (\Exception $e) {
    Mail::to($user->email)->send(new FallbackSmsEmail($message));
}

Gotchas and Tips

Common Pitfalls

1. API Key/Secret Mismatch

Symptom: 401 Unauthorized or empty responses.
Fix: Double-check .env and config/smsend.php for typos.
Tip: Use php artisan config:clear after changes.

2. Phone Number Format

Symptom: SMS fails silently or returns invalid number errors.
Fix: Ensure numbers include country code (e.g., 39 for Italy) and no spaces/dashes.

Tip: Validate with:

use Dunp\SmsendLaravel\Validators\PhoneValidator;
if (!PhoneValidator::validate('391234567890')) {
    // Handle invalid format
}

3. Rate Limits

Symptom: 429 Too Many Requests.
Fix: Implement exponential backoff in your retry logic or upgrade your plan.
Tip: Monitor usage via Smsend’s dashboard.

4. Unicode Misconfiguration

Symptom: Garbled characters in SMS.
Fix: Set 'unicode' => true in the send array or globally in config.

5. Queue Stuck Jobs

Symptom: SendSmsJob jobs remain in the queue.
Fix: Check for exceptions in HandleFailedJobs middleware or manually retry:
```
php artisan queue:retry all
```

Debugging Tips

1. Enable Verbose Logging

Add to config/smsend.php:

'log' => [
    'enabled' => true,
    'level' => 'debug',
],

Check logs at storage/logs/laravel.log.

2. Inspect Raw API Responses

Temporarily modify the send method in Dunp\SmsendLaravel\SmsendManager to log raw responses:

$response = $this->client->send($data);
logger()->debug('Raw API Response', ['response' => $response->getBody()->getContents()]);

3. Test with the API Directly

Use Smsend’s API docs to validate your credentials and payloads manually.

Extension Points

1. Customizing the HTTP Client

Bind a custom Guzzle client in AppServiceProvider:

$this->app->singleton(\GuzzleHttp\Client::class, function () {
    return new \GuzzleHttp\Client([
        'timeout' => 30,
        'headers' => [
            'User-Agent' => 'MyApp/Smsend',
        ],
    ]);
});

2. Adding Pre/Post-Send Hooks

Extend the SmsendManager to add logic before/after sending:

// In a service provider
$this->app->extend('smsend', function ($manager) {
    $manager->extend('preSend', function ($data) {
        // Modify $data or validate
        return $data;
    });
    return $manager;
});

3. Supporting Additional SMS Providers

Implement a provider interface and register it:

// Example: Add Twilio support
$this->app->bind(\Dunp\SmsendLaravel\Contracts\SmsProvider::class, function () {
    return new \App\Providers\TwilioSmsProvider();
});

4. Local Development Testing

Use a mock provider for testing:

// In phpunit.php
$this->app->when(Smsend::class)
    ->needs(\Dunp\SmsendLaravel\Contracts\SmsProvider::class)
    ->give(new \App\Providers\MockSmsProvider());

Configuration Quirks

1. Default Sender ID

If not specified, the package uses config('smsend.sender').

Tip: Set a fallback in config/smsend.php:

'sender' => env('SMSEND_SENDER', 'DefaultSender'),

2. Timeout Settings

Default timeout is 10 seconds. Adjust in config/smsend.php:
```
'timeout' => 30, // seconds
```

Smsend Laravel Laravel Package