Lox24 Api Client Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package. There is no Lox24ServiceProvider, no publishable config, no facade. The bundle's value — DI extension, autoconfiguration, parameter resolution — is inert under Laravel. What you actually consume is the underlying lox24/api-client-php client; the bundle is only the wiring.

Minimal path:

1. composer require lox24/api-client-php-symfony-bundle:0.3.* (see Gotchas — do not float this constraint blindly).
2. Read vendor/lox24/api-client-php-symfony-bundle/DependencyInjection/Configuration.php first. It is the only authoritative list of config keys and defaults; the README typically lags behind.
3. Then read the underlying client's public methods in vendor/lox24/api-client-php/ — that is your actual API surface (send message, fetch balance, delivery status, etc.).
4. Register the client yourself in AppServiceProvider::register() as a singleton, feeding it the token from config('services.lox24.token').
5. First use case: send one SMS to your own number from php artisan tinker, then immediately test the balance/status call — it verifies both auth and response parsing before you build anything on top.

If step 5 fails, the problem is almost never Laravel. It is auth, a wrong base URI, or a Symfony HTTP exception you haven't caught yet.

Implementation Patterns

Container binding over bundle autowiring. The bundle expects constructor injection of its client interface. Mirror that in Laravel: bind the interface to the concrete client in a singleton, resolve it by type-hint everywhere else. This keeps you one line away from swapping a fake in tests.

Config in config/services.php, token from .env. Never call env('LOX24_TOKEN') inside a service class — config:cache in production will return null. Put the whole client options array (base URI, timeout, token) in config and pass it as an array to the binding.

Wrap it once. A thin SmsSender service with send(), balance(), status() methods means vendor exceptions, payload shapes, and any eventual replacement stay in one file. Every call site then depends on your class, not on Lox24\....

Queue the sends. A SendSms job per message (or a batched job for bulk) gets you retries, backoff, and failure visibility for free. Keep the job payload as plain scalars so retries serialize cleanly.

Notification channel. For app-level ergonomics, implement a custom Notification channel that delegates to SmsSender. This is the pattern that makes SMS feel native in Laravel and is usually the last integration step you need.

Testing. Bind a fake SmsSender (or a fake of the vendor interface) in setUp. Do not Http::fake() unless you have explicitly constructed the client on Laravel's HTTP client — by default it is on Symfony HttpClient and Http::fake() will silently not intercept, so your tests will hit the network.

Logging and metrics. Decorate the client interface with a logging decorator and bind the decorator over the real client. This beats sprinkling Log::info around call sites and survives a vendor upgrade.

Gotchas and Tips

0.x means minor bumps are breaking. The 0.2.4 → 0.3 release notes contain nothing but a compare link — no migration guide, no summary. Treat 0.3 as a potentially breaking change: diff the repo before upgrading, and pin exactly (0.2.4 or ~0.2.4) if you are already shipping. Check for a PHP minimum bump and any renamed config keys or constructor arguments.

Symfony exceptions are not Laravel exceptions. You will catch Symfony\Contracts\HttpClient\Exception\ClientExceptionInterface / TransportExceptionInterface, not Illuminate\Http\Client\RequestException. Retry behaviour you configure via Laravel's Http::retry() does not apply to this client — set timeouts and retries in the client's own options.

The bundle extension will not run. Any %lox24.something% parameter or service alias the bundle defines does not exist in Laravel's container. Resolve the concrete client class, not the bundle's alias.

Rate limits and duplicate sends. SMS is billable, and 429s are normal under bulk load. Dedupe before enqueueing (a unique job key or a DB marker on your message record), and use exponential backoff rather than immediate retries — otherwise you pay twice for the same message.

Config caching bites late. Everything works locally and breaks on deploy. Verify with php artisan config:cache before merging any config change.

Extension points are limited by design here: the practical ones are (a) rebinding the client interface in a service provider, (b) decorating that interface, and (c) wrapping in your own service. There is no event system to hook into, so don't design around one.

Watch the delivery-report path. Status callbacks/webhooks are typically a plain route plus a controller you write — the bundle does not register routes for you. Verify any signature/secret check yourself and return 200 fast, then process on a queue.