Smsir Php Laravel Package

Technical Evaluation

Architecture fit

• Thin SDK/adapter around the sms.ir REST API, packaged for Laravel (service provider + facade + config file). Footprint is small and peripheral — it should never be imported by domain code directly.
• For a layered/modular Laravel app it belongs in an infrastructure adapter behind an internal interface (e.g. SmsGateway), so the vendor facade stays behind one seam.
• Framework-agnostic core (plain PHP usage) is unclear; assume Laravel-coupled until verified.

Integration feasibility

• Install is straightforward (composer require, publish config, set API key + line number). Typical effort: under a day for a happy path.
• Real friction is version constraints and API-generation drift, not wiring.

Technical risk

• Abandonment / bus factor: unofficial package, 17 stars, single maintainer, last release Feb 2023. Effectively you adopt the code, not a supported product.
• API drift: a 2023 wrapper may target an older sms.ir API generation. sms.ir has evolved around template/verify sends, bulk endpoints, and delivery reporting; subtle behavioral breakage is plausible even if requests succeed.
• Quality signals unknown: no visible guarantee of tests, CI, static analysis, or an exception model. Error handling may be generic or swallowed.
• Supply chain: low-scrutiny dependency; audit the source before adoption rather than trusting semver.
• Secrets / PII: risk of message bodies or OTP codes being logged; API keys may default to a config file rather than a secret manager.
• No built-in resilience: retry/backoff/idempotency likely absent, which matters most on the OTP path.
• Positives: MIT license is permissive; scope is small enough to fork and own if needed.

Key questions

1. Which sms.ir API generation does it target, and does it cover verify/template OTP, bulk, delivery reports, line status, and credit balance?
2. PHP and Laravel version constraints — does it run on Laravel 11/12, or would we need a fork?
3. How are provider errors surfaced: typed exceptions, error codes, or silent nulls?
4. Is there CI/tests, and what is the maintainer's responsiveness on recent issues and PRs?
5. Does it log payloads? Where does the API key come from — config, env, or hard-coded default?
6. Do we have a preferred official sms.ir SDK or the option to call the REST API directly via Laravel's HTTP client?

Integration Approach

Stack fit

• Natural fit for a Laravel 9/10 app on the same PHP version line. On newer Laravel versions, assume either a fork or a thin in-house replacement is required.
• If the app is non-Laravel PHP, or if we want the option to swap providers, prefer a direct HTTP client implementation over the package.

Migration path (recommended)

1. Spike (1–2 days): vendor the repo or fork into a private repo, pin to a commit SHA (not a floating tag), run composer audit, PHPStan, and a staging smoke test against real test credentials.
2. Abstract first: define an internal SmsGateway contract (send, sendVerify, deliveryStatus). Implement it with this package in exactly one adapter class.
3. Second adapter: implement the same contract over Laravel's HTTP client for the same endpoints. It doubles as a fallback and as a way to diff response shapes against the package.
4. Config-driven selection: resolve the implementation from config so switching to another provider (Kavenegar, Ghasedak) or to the in-house adapter is a config change.
5. Contract tests: run the same test suite against both adapters in staging to catch drift early.

Compatibility

• Pin PHP/Laravel constraints explicitly and document them. Verify the package does not conflict with existing dependencies (Guzzle, HTTP client versions).
• Check whether the package's config keys collide with existing app config.

Sequencing

• Isolate → smoke test → staging → canary on low-risk traffic (marketing/transactional notifications) → then OTP.
• Keep OTP on the existing known-good path, or dual-send to a second number, until failure rate and latency are proven over at least a couple of weeks.

Operational Impact

Maintenance

• Low day-to-day burden if isolated; but you own the code. Budget ~1–2 days per quarter for upstream review and fork upkeep, plus friction each time the platform upgrades PHP/Laravel.
• Pin in composer.lock; treat upgrades as a deliberate change, not routine.

Support

• No vendor SLA. Upstream issues may go unanswered; for delivery and account problems you rely on sms.ir's own support, not the package author.
• Document the internal owner of the adapter — otherwise this becomes orphaned glue code.

Scaling

• Throughput is bounded by the provider's rate limits and line capacity, not by the package. Confirm sms.ir concurrency and per-line limits during evaluation.
• Sends are likely synchronous: route them through Laravel queues with a dedicated worker and per-provider rate limiter so OTP latency doesn't degrade under bulk-marketing load.
• Separate queues (and ideally separate line numbers) for OTP vs. marketing so a campaign can't starve authentication traffic.
• Add idempotency where the API supports it — duplicate SMS costs money and erodes user trust.

Failure modes

• Token expiry/rotation or revoked line → total send failure; validate config at boot, not at send time.
• Provider outage or geo/IP restriction → timeouts; sync calls become slow user requests.
• 429 rate limiting without backoff → cascading retries and duplicate sends.
• Silent failures if errors are swallowed → OTP never arrives and nobody is paged.
• Upstream API deprecation → breakage with no notice.
• Log leakage of OTP codes or full message bodies.

Observability

• Instrument: send success rate, p50/p95 latency, provider error codes, queue depth, cost per message, and delivery rate from reports/webhooks.
• Alert on failure-rate spikes and on zero-traffic anomalies (a silent auth failure looks like "no errors").

Ramp-up

• A Laravel developer integrates this in about a day and instruments it in another. The real learning curve is sms.ir domain knowledge: line registration, template/message approval workflows, Iranian content rules, and data-residency constraints — not the PHP code.

Compliance notes

• Message content is subject to local approval/screening; plan for template registration lead time.
• Store API keys in a secret manager, redact OTPs from logs, and retain message metadata only as long as needed.