Chapaar Laravel Package

Getting Started

Chapaar is a Laravel messaging/courier package that wraps one or more delivery drivers behind a single, config-driven API. Day-to-day you'll mostly touch three things: the published config file, the facade/manager (or the provided notification channel), and your own environment credentials.

1. Install and publish

   composer require tookantech/chapaar
   php artisan vendor:publish --tag="chapaar-config"
   

   The published config/chapaar.php is the single source of truth: default driver, per-driver credential blocks, and any queue/retry options. Read this file before the README — it tells you what is actually configurable in your version.

2. Credentials via .env

   Map each driver's keys into .env (API key, sender/number, endpoint) and reference them with env() only inside the config file. Never call env() from application code — it returns null once php artisan config:cache has run.

3. First use case: one transactional send

   use TookanTech\Chapaar\Facades\Chapaar;
   
   Chapaar::driver('default')->to($user->phone)->send('Your order has shipped.');
   

   Confirm delivery with the returned response object/DTO (message id, status) rather than assuming success — most drivers return HTTP 200 with an error payload.

4. Then move to the notification channel — this is where the package earns its keep. Register the channel in your via() array and encapsulate message construction in a toChapaar() method so templates and driver choice stay out of your domain code.

Where to look first: config/chapaar.php → the facade/manager class → the driver interface. The interface is the contract you'll mock in tests and implement if you need an in-house gateway.

Implementation Patterns

Driver-per-context, not driver-per-call. Configure named connections (e.g. transactional, marketing, otp) in the config, each pointing at a driver plus its own sender line and credentials. Application code then asks for a logical connection and never knows which gateway is behind it. This is the pattern that makes swapping providers a one-line config change during an outage.

Notifications over direct facade calls. For anything user-facing, prefer the notification channel: it gives you queueing, ShouldQueue, per-channel via() logic, and a natural place to keep message templates. Reserve direct facade calls for one-off tooling, artisan commands, and health checks.

Queue everything non-interactive. Implement ShouldQueue on the notification (or dispatch the mailable-like send through a job). Gateway latency and rate limits are the main source of slow requests; OTP is the exception — send it synchronously so you can report failure to the user immediately.

Fallback chain. Wrap sends in a small service that catches the package's transport exception and retries against a secondary named connection. Log which connection served each message so you can attribute failures and cost later.

Testing. Bind a fake/spy implementation of the driver contract in your test suite (or use the package's fake, if the version ships one) and assert on the message payload, not the HTTP call. Snapshot the rendered template body — that is the part that regresses silently.

Events and logging. If the package dispatches send/failure events, hook a listener that records message id, driver, recipient hash, and duration. This is your only reliable audit trail when a provider disputes delivery.

Multi-tenant / per-tenant credentials. If tenants bring their own gateway keys, don't try to mutate config at runtime. Build the driver instance from a tenant-scoped settings model via the manager's driver() factory, or register a scoped container binding per request.

Gotchas and Tips

2.0.0 is a major bump for a non-breaking change. The only substantive changes are Laravel 13 support and widened version constraints that remain compatible with older Laravel releases. There are no reported API changes or deprecations, but Composer will treat ^1.8 as incompatible with ^2.0. Pin "tookantech/chapaar": "^1.8|^2.0" if you maintain packages or monorepos that must span both, and update the constraint deliberately rather than letting composer update surprise you in CI.

Verify the constraints, don't assume. The release note says "compatible with old versions," but the practical floor (PHP version, illuminate/* range) is set in composer.json. Run composer why-not tookantech/chapaar 2.0.0 before upgrading if you're still on an older Laravel — it will name the exact conflicting package.

Config caching bites in two directions. After changing driver credentials locally, run php artisan config:clear; in production, remember config:cache is required for the new values to load. A stale cached config sending through a decommissioned gateway is a classic silent failure.

Rate limits are per-driver and usually undocumented. Implement a RateLimiter::for('chapaar') keyed by driver + recipient, and let the queue absorb bursts. Retrying a 429 immediately is how accounts get suspended.

Error surfaces differ wildly between drivers. Normalise early: catch the package exception, inspect the driver response for a status/message code, and map it to your own domain-level result (Sent, Rejected, TemporarilyFailed). Don't let raw gateway payloads leak into controllers.

Phone number formatting. Normalise to E.164 before the send call. Most gateways accept local formats inconsistently; the package generally passes the string through unchanged, so garbage in, garbage out.

Extension points. The driver contract is the intended seam — implement it for any gateway the package doesn't ship, register the binding in a service provider, and reference it by name in the config. Keep custom drivers thin: transport + response mapping only, no business logic.

Verify against Laravel 13 in a branch first. The support was added in this release, so it is the least-exercised combination. Run your notification tests plus one real driver call in a staging environment before rolling forward; framework upgrades frequently surface deprecations in packages that use container or event internals.

Watch for the next patch. A 2.0.x follow-up fixing constraint or compatibility edge cases is likely after a Laravel-major support release; subscribe to releases rather than pinning immediately after the bump.