Fb Sms Laravel Package

Getting Started

• Install: composer require mortezamasumi/fb-sms. v5.3.0 adds Laravel 13 support, so the same constraint line now covers Laravel 10/11/12/13 — check composer.json for the exact illuminate/* range and the minimum PHP version your app must satisfy before bumping the framework.
• Publish config first: run php artisan vendor:publish --tag=fb-sms-config (confirm the tag in the README — the tag name is the one thing most likely to differ between majors). Commit the published config file so credential keys are versioned and values stay in .env.
• Credentials: the package is a thin client over an upstream SMS gateway, so nothing works until the API key/sender number are set. Put them in .env (FB_SMS_*), reference them from config/fb-sms.php, and add them to .env.example and your deploy secrets store in the same commit.
• Where to look first: the published config file tells you more than the README does — it enumerates drivers, endpoints, default sender, and any queue/retry knobs. Read it top to bottom before writing code.
• First use case: a single transactional send from a console command or php artisan tinker to prove credentials and number formatting work before wiring it into a notification. Nothing wastes more time than debugging a notification layer on top of a broken credential.

Implementation Patterns

• Prefer the notification channel over direct calls. For anything user-facing (OTP, order status, alerts) implement via() returning the package's SMS channel and a toSms()/toFbSms() payload method. You get queueing, ShouldQueue, and per-notifiable routing for free, and swapping providers later is a one-line change.
• Reserve the facade/manager for imperative cases. Direct sends are right for admin-triggered broadcasts, cron digests, and one-off operational alerts — anywhere there is no Notifiable model to hang a notification on.
• Always send queued in production. Wrap sends in a job (or ShouldQueue on the notification) with tries, backoff, and retryUntil. Gateway timeouts are normal; a synchronous HTTP call inside a web request turns a 2-second page into a 30-second one.
• Centralise number normalisation. Iranian and regional numbers arrive as 09…, +989…, and 00989…. Normalise to the format the gateway expects in a single helper or a custom cast, and validate before enqueueing — an invalid number that fails at send time burns a retry budget for nothing.
• Layer your own thin service. A small SmsService (or Notification base class) that owns normalisation, templating, and logging keeps the package behind one seam. When the provider changes — or you add a second one for failover — only that class moves.
• Audit every send. Add a sent_sms table (recipient, template, provider message id, status, cost) written from a listener or in the service. Delivery reports and billing disputes are impossible to reconcile from application logs alone.
• Failover driver. Register the second provider as an alternative driver in config and catch transport exceptions in your service to re-attempt once. Keep the fallback synchronous-from-the-queue so both attempts run in the same job.
• Test with fakes. Assert the intent in feature tests (notification dispatched to the right number) rather than the HTTP payload, and keep one integration test that hits a sandbox/stub endpoint per driver.

Gotchas and Tips

• Laravel 13 support is additive, not a breaking change. v5.3.0 only widens framework compatibility, so upgrading from 5.2.0 should be a composer update with no code changes. Verify your laravel/framework and PHP constraints resolve before bumping the framework in the same PR — if two things break at once you won't know which caused it.
• Config caching bites. After editing config/fb-sms.php locally or in deploy, php artisan config:clear (or config:cache in the deploy script). Silent "credentials missing" errors in production are almost always a stale config cache.
• Queue workers cache code. After a package upgrade, php artisan queue:restart. Jobs serialised before the upgrade can otherwise fail on class/signature changes.
• Character encoding drives cost. Persian/Arabic text forces UCS-2 encoding, so the per-part character limit roughly halves versus GSM-7. Budget for multi-part messages and keep templates short; test with real content, not "test 123".
• Sender number and template approval. Many gateways require a pre-registered sender ID and pre-approved template text. A send that works in sandbox and fails in production is usually an unapproved sender or a template mismatch, not a code bug.
• Rate limits are per-account, not per-process. If you fan out with Bus::batch() or Notification::send() over a large collection, throttle with RateLimited middleware or a job middleware; otherwise you'll get 429s and retries that triple your bill.
• Extension point: most packages of this shape let you register custom drivers or swap the HTTP client. Bind your own transport in a service provider behind the package's driver contract rather than forking — it survives the next major.
• Debugging: log the gateway's raw response body on failure (mask the API key), and keep the provider message ID. Every support ticket you file upstream will ask for it.
• Pin the major: use "^5.3" rather than "*". The v5 line is stable, but a future v6 with renamed config keys or a changed channel contract would otherwise land silently in CI.