Twilio Bundle Laravel Package

Getting Started

Reality check first: despite the name, webonaute/twilio-bundle is a Symfony bundle, not a Laravel package. There is no service provider, no facade, no config/twilio.php. What it actually gives you is a thin DI wiring around Twilio\Rest\Client plus a config block for sid, token, and from. For a Laravel developer, treat it as a reference implementation, not a dependency you composer require into app/.

The pragmatic route that mirrors what the bundle does:

composer require twilio/sdk   # v6.x to match what the bundle targets, or v7/8 if you're greenfield

# .env
TWILIO_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_TOKEN=your_auth_token
TWILIO_FROM=+15555550100

// config/services.php
'twilio' => [
    'sid'   => env('TWILIO_SID'),
    'token' => env('TWILIO_TOKEN'),
    'from'  => env('TWILIO_FROM'),
],

// app/Providers/AppServiceProvider.php  (register)
public function register(): void
{
    $this->app->singleton(\Twilio\Rest\Client::class, fn () => new \Twilio\Rest\Client(
        config('services.twilio.sid'),
        config('services.twilio.token'),
    ));
}

First use case — one SMS, one call:

$twilio = app(\Twilio\Rest\Client::class);
$twilio->messages->create('+15555550199', [
    'from' => config('services.twilio.from'),
    'body' => 'Hello from Laravel',
]);

If you're genuinely inside a Symfony 5 app with the bundle installed, the workflow is config/packages/webonaute_twilio.yaml + autowire Twilio\Rest\Client, then ignore everything below about Laravel-specific patterns.

Implementation Patterns

Wrap the client — don't leak it into controllers. Whether you adopt the bundle or just the SDK, you want a single seam the rest of the app talks to:

// app/Services/SmsSender.php
final class SmsSender
{
    public function __construct(private \Twilio\Rest\Client $client) {}

    public function send(string $to, string $body, ?string $from = null): string
    {
        $msg = $this->client->messages->create($to, [
            'from' => $from ?? config('services.twilio.from'),
            'body' => $body,
        ]);
        return $msg->sid;
    }
}

Bind SmsSender in the container and let controllers/jobs depend on it. This is exactly what the bundle does for Symfony, minus the YAML.

Notification channel. This is where the package's shape pays off in Laravel — implement toTwilio() so the SDK client lives in one place:

use Illuminate\Notifications\Notification;
use Twilio\Rest\Client;

class InvoicePaid extends Notification
{
    public function via($notifiable): array { return ['twilio']; }

    public function toTwilio($notifiable): \Twilio\TwiML\MessagingResponse
    {
        return (new \Twilio\TwiML\MessagingResponse)
            ->message("Invoice #{$this->invoice->id} paid.");
    }
}

Note: Laravel's Twilio notification channel expects TwiML, not a messages->create() call — that's a common trip-up when porting Symfony service code into a Laravel notifier.

Jobs + queues. Wrap sends in ShouldQueue jobs so a slow Twilio API doesn't stall a request. The client is a singleton, so it's queue-safe; just don't serialize it into the job payload.

Multiple senders / messaging services. If you need different from numbers per tenant, key them off config('services.twilio.from') fallbacks or a tenants.twilio_from column. The bundle never handles this — it's a single global from.

Testing. Swap the binding for a fake in TestCase::setUp():

$this->mock(\Twilio\Rest\Client::class, function ($m) {
    $m->shouldReceive('messages->create')->andReturn((object)['sid' => 'SM123']);
});

Or bind a SmsSender interface and assert against a SpySender.

Gotchas and Tips

SDK v6 is EOA-adjacent. Twilio's SDK v6 dates to 2019–2020. If you're starting fresh, use twilio/sdk:^7 or ^8 and ignore this bundle entirely — the API surface (messages->create, calls->create) is essentially the same. The only reason to target v6 is if something else in your dependency tree pins it.

The bundle name is misleading. webonaute/twilio-bundle is a Symfony Bundle subclass. Pulling it into Laravel won't autoload a service provider; composer will just install the source and PHP will complain if you try to register() it. If you must reuse the code, copy the ~50 lines of the extension class rather than fight the container.

Zero stars, zero dependents = zero support. No issues, no PRs, no fixes. Treat the source as documentation-only. MIT license means you can vendor and patch freely.

Symfony config key quirks. If you are in Symfony, the bundle historically expected webonaute_twilio.sid / .token / .from. Typos yield "service not found" at container compile time, not a runtime error — grep your YAML for the exact key.

from must be E.164. +15555550100, never 555-555-0100 or (555) 555-0100. Twilio will 400 with unhelpful error codes if you pass a localised format. Validate at the config/services.php layer, not at send time.

Don't hardcode credentials in the Symfony YAML either. Use %env(TWILIO_SID)% and let .env do the rest — the bundle supports env placeholders, but the values must be resolved at container build time, so bin/console cache:clear after rotating a token.

Rate limits silently bite. Twilio's default throughput is 1 msg/sec per long code. A tight foreach over messages->create() will throw Twilio\Exceptions\RestException 20429 (too many requests). Use Bus::batch() or Redis::throttle() — the bundle offers no retry helper.

Webhooks. Inbound SMS/status callbacks are handled at the controller layer, not by the bundle. Validate X-Twilio-Signature with Twilio\Security\RequestValidator yourself; forgetting this is the single most common production security bug in Twilio integrations.

Extension points, if any. The bundle's only real extension surface is the DI alias — you can override the Twilio\Rest\Client service definition in a compiler pass. That's not worth it for a Laravel team; just bind your own client and move on.