Laravel Iranian Sms Laravel Package

Technical Evaluation

Architecture fit

• Provides a driver/manager abstraction over multiple Iranian SMS operators (Kavenegar, Melipayamak, Ghasedak, SMS.ir class providers) behind a single Laravel service-provider + facade surface. That is the right shape for our need: one SmsGateway contract, per-operator drivers selected by config.
• Fits Laravel's idiomatic extension points (service provider, config publish, facade, likely a Notification channel), so it slots into an existing app without touching domain code — provided we own the contract and treat the package as one implementation behind it.
• Weaknesses versus our standard architecture: it is Laravel-5.x-era, so binding style, helper usage, and HTTP layer (likely raw Guzzle/curl rather than Illuminate\Support\Facades\Http) will not be PSR-18/PSR-7 clean. We should not let its interfaces leak into our domain layer.

Integration feasibility

• Low-effort spike: composer require in an isolated Laravel skeleton, publish config, exercise one operator against a sandbox account. Realistically 1–3 engineer-days to a working happy path.
• The unknown is the Laravel version gap. Laravel 5.x is fully EOL; defer provider properties, array_except/str_* helpers, facade $app access, and config() semantics have all shifted. Expect the package to install but fail at boot on Laravel 9/10/11.
• Iranian operator APIs are plain REST with API-key auth, so replacing the transport is mechanical. The valuable, harder-to-rebuild part is the per-operator payload quirks (template/"pattern" sends, Persian digit/encoding handling, delivery-report polling).

Technical risk

• High maintenance risk: single maintainer, last release 2021-03-18, 25 stars, zero dependents. Effectively unmaintained and unexercised in production by anyone we can point to.
• Compatibility risk: Laravel 5.x is unsupported (no security patches). Adopting as-is means inheriting an EOL dependency chain or forking.
• Operational risk: no evidence of idempotency, retry semantics, or queue integration; ambiguous send states (accepted vs. delivered) are the classic failure in this domain.
• Supply-chain risk: MIT and small surface area mitigate this; vendoring the operator adapters is cheap.

Key questions

1. Which operators do we actually need at launch? If one, the package's core value proposition (multi-operator abstraction) largely evaporates and a ~150-line adapter wins.
2. What Laravel version is the target, and are we willing to fork and maintain rather than consume upstream?
3. Do we need pattern/template (verify-code) sends and delivery receipts, or only fire-and-forget OTP?
4. Is there a sandbox/test credential for each operator, or is every compatibility check a paid, live-traffic test?
5. Who owns the fork, and what is the exit criterion to drop it in favor of a first-party adapter?

Integration Approach

Stack fit

• PHP/Laravel-native, so no new runtime. Recommend: pin the package behind our own SmsSender interface, register the package facade only inside an infrastructure module, and expose a Notification channel to product code. Product code must never use a package class directly.
• Replace the package's transport with Http::withToken()->retry()->post() so we inherit Laravel's HTTP client, fakes, and logging — this alone removes most of the maintenance surface.

Migration path

• Fork to a first-party namespace (or vendor the driver files) and bump to the current Laravel major. Concretely: swap helpers for Str/Arr, replace Guzzle calls with the HTTP client, add composer.json version constraints, and add a PHPUnit/Pest suite with Http::fake() fixtures per operator.
• Keep the config-driven driver selection so operators remain swappable at runtime — that is the genuine value we are buying.

Compatibility

• Treat the multi-operator drivers as the asset and everything else as disposable. Add contract tests that assert request shape per operator against recorded fixtures; that is the only thing preventing silent breakage when an operator changes its payload.
• Verify PHP 8.1+ / Laravel 10+ boot in the spike before committing; if boot fails hard, the effort shifts from "integrate" to "rewrite", which changes the build/buy decision.

Sequencing

1. Spike: install, boot, one operator, one OTP send against sandbox. Timebox 3 days.
2. Decision gate: fork-and-modernize vs. write first-party adapter (recommend adapter if ≤2 operators needed).
3. Wrap in SmsSender contract + queueable job + delivery-status polling.
4. Contract tests and fixtures per operator; add to CI.
5. Shadow traffic, then cut over operator by operator — not all at once.

Operational Impact

Maintenance

• Budget ~10–15% of one engineer ongoing for the fork: operator payload drift, Laravel upgrades, dependency bumps. Upstream contribution is unlikely to be reciprocal given the repo's activity level; plan for permanent ownership.
• No dependents and no release since 2021 means no community safety net — every regression is ours to find.

Support

• Support burden concentrates at the operator boundary: rejected credentials, changed endpoint domains, quota exhaustion, and Persian text encoding. Document a per-operator runbook (auth scheme, rate limit, delivery-report endpoint) as part of the integration, not after.
• Escalation for operator-side outages is commercial, not technical; ensure account/contract ownership sits with someone who can open operator tickets.

Scaling

• SMS throughput is gated by the operator's rate limit and our spend, not by this package — it is a thin HTTP wrapper. Scale by queueing sends (one job per message, per-operator rate limiter), not by scaling the library.
• Add per-operator rate limiting via RateLimiter and a circuit breaker so one degraded operator does not stall the queue worker.

Failure modes

• Duplicate sends on retry — highest-severity failure (cost + user trust for OTP). Require an idempotency key per logical message and a send-attempt ledger.
• Ambiguous delivery state — "accepted" ≠ "delivered"; without receipt polling we cannot distinguish operator failure from handset failure. Instrument both.
• Silent payload drift — operator changes a field, HTTP 200 comes back with an error body. Assert on response body semantics, not just status code.
• Credential leakage — API keys in config/logs; ensure secrets come from env/secret manager and response logging redacts tokens.
• Unmaintained dependency — a future Laravel major breaks the package at boot; the fork plus CI matrix is the mitigation, and CI must run on the newest Laravel on day one.

Ramp-up

• Low: a mid-level Laravel engineer is productive in a day; the domain (Iranian SMS operators, Persian encoding, pattern-based OTP) is the actual learning curve, not the code.
• Given the repo's maturity signals, the realistic framing for stakeholders is: we are adopting a set of operator adapters as reference material and taking ownership of them, not adopting a supported library. Approve on that basis or not at all.