Getting Started

Install with the v2 major constraint: composer require misaf/laravel-sms-gateway-kavenegar:^2.0. First check composer.json for supported PHP/Laravel versions and confirm your app meets them.
The v2.0.0 release notes only link to the GitHub compare view (v1.0.0...v2.0.0), so treat v2 as a major-version audit until you review that diff or the README. Look first at:
- service provider / facade changes
- config file name and published tag
- gateway driver name and method signatures
- environment variable names such as API key and sender/line number
Publish the package config if available, then set the Kavenegar API key and sender line in .env; do not commit real credentials.
Configure the package as the default SMS gateway or resolve it explicitly through the SMS manager/facade provided by misaf/laravel-sms-gateway.
First use case: send a single transactional SMS or OTP in a local/test route or php artisan tinker, then inspect the Kavenegar response and Laravel logs before wiring it into application flows.

Implementation Patterns

Keep gateway selection in config: set Kavenegar as the default driver for normal application SMS, and use explicit driver resolution only where you need multiple providers.
Wrap sends in a small application service or Laravel notification channel rather than calling the package directly from controllers. This gives you one place for phone normalization, message templates, logging, and retry policy.
For OTP and transactional messages, check whether the v2 package exposes Kavenegar-specific methods such as template/verify lookup versus plain send. If it only exposes plain send, keep template IDs and token payloads in your own config/service layer.
Queue non-critical SMS sends with a Laravel job and a dedicated queue. Use rate limiting and backoff to avoid hammering the Kavenegar API or exhausting credit during retries.
In tests, bind a fake/log driver or mock the underlying HTTP client if the package supports it. Do not call the live Kavenegar API from the test suite.
Use Laravel notifications for user-facing flows where practical: create a custom notification channel that delegates to the package, so SMS becomes another delivery channel alongside mail and database notifications.

v2.0.0 is a major bump, but the supplied release note contains no migration detail. Before upgrading from v1, review the full compare diff for namespace, config-key, facade, driver-name, and method-signature changes. Pin ^2.0 only after that check.
Kavenegar API failures often surface as gateway responses rather than clean Laravel validation errors. Catch package exceptions, log the Kavenegar status/message and request identifier, and avoid retrying permanently invalid requests such as bad receptors or insufficient credit.
Normalize Iranian mobile numbers before sending, and keep sender/line configuration separate per environment. A correct API key with the wrong sender line can still fail.
After changing .env values, run php artisan config:clear or php artisan config:cache as appropriate; cached config is a common cause of “new key not being used”.
Check message encoding, line breaks, and length limits before send. Long messages may be split or rejected depending on Kavenegar account settings.
Rate limits and account credit are operational concerns, not just code concerns. Add queue throttling, alerting on repeated failures, and masked logging for phone numbers.
Extension points to inspect: custom gateway registration through the SMS manager, package config overrides, and whether the HTTP client is injectable/mockable. Those determine how easily you can add failover providers or test without live SMS.