Smsir Php Laravel Package

Technical Evaluation

Architecture fit

• The package is a thin, vendor-specific REST client for the SMS.ir gateway (bulk send, verify/pattern send, credit, line info). It carries no domain logic, no persistence, and no state — it is an outbound adapter, not a subsystem.
• Correct placement is behind an application-owned port (e.g. App\Contracts\SmsSender) as an anti-corruption layer. The package should never be referenced directly from controllers, jobs, or notification classes; that keeps the vendor swappable and makes the 16-star / 0-dependent supply-chain profile a non-issue architecturally.
• Fits any Laravel app already using the notification system, queues, and the HTTP client. Standalone (non-Laravel) PHP use is likely possible but unverified.

Integration feasibility

• Low effort: composer require, publish config, supply API key and line number, call the facade or injected client. Realistic integration is 1–3 developer days including tests, a verify template, and a fallback path.
• Value is concentrated in the SMS.ir account configuration (line numbers, approved verify templates, IP allowlisting, credit), not in the code. Budget account setup lead time separately from engineering time.

Technical risk

• Code risk: low. Small, single-purpose surface; failure blast radius is one outbound call.
• Supply-chain risk: moderate-to-high. 16 stars, 0 dependents, single-organization maintainer, last release 2024-10-19. There is effectively no community battle-testing and no evidence of a maintenance cadence. Treat as "vendor this code" rather than "depend on this library."
• Compatibility risk: moderate. Must verify illuminate/* and Guzzle constraints against current Laravel (11/12) and PHP 8.2/8.3; a stale constraint set forces a fork or a replace entry. Auto-discovery and config-publish behavior should be checked against the target skeleton.
• Operational/compliance risk: high relative to code risk. SMS.ir is an Iranian provider: data residency in Iran, IRR payment rails, potential sanctions/geo restrictions on GitHub, Packagist, and CI runners, and jurisdictional constraints on storing Iranian end-user phone numbers and message content.
• Critical-path risk. SMS is usually the OTP/2FA channel. Package quality matters less than gateway availability, delivery latency, and cost per message — none of which this package controls.

Key questions

1. Which Laravel and PHP versions are asserted in composer.json, and does the service provider use package auto-discovery?
2. Does it cover verify/pattern-based sends (mandatory for OTP) as well as bulk, credit, and delivery reports — or only a subset?
3. Are timeouts, retries, and 429/5xx handling configurable, or does it rely on framework defaults?
4. Does it expose typed exceptions and a status/response object, or return raw arrays that force string matching?
5. Is the HTTP layer mockable (Http::fake) for CI, and is there a documented sandbox or test line?
6. Does it log request payloads (phone numbers, OTP codes) at debug level?
7. Is Composer installation viable from our CI regions, or does GitHub/Packagist access require a mirror or a vendored copy?
8. Who owns the SMS.ir account contract, and what are the committed throughput, delivery SLA, and per-message pricing?

Integration Approach

Stack fit

• Target: Laravel 9–12, PHP 8.1+, queue workers available, Redis or database queue for async sends. Stateless HTTP egress — no special runtime, no extensions beyond standard cURL.
• Natural fit as a Laravel notification channel (toSmsIr()) plus a lower-level client for non-notification use cases (marketing blasts, admin alerts).

Migration path

1. Define an owned SmsSender interface with domain-shaped methods (sendOtp, sendBulk, getBalance) — not vendor-shaped ones.
2. Implement SmsIrSender as a thin adapter delegating to the package; keep any incumbent provider as a second implementation.
3. Register a driver resolver keyed off config so providers can be switched per-environment and per-use-case (OTP vs marketing) without code changes.
4. If the package later proves unmaintained, the adapter can be reimplemented against SMS.ir's REST API directly in roughly 100–150 lines with no caller changes. This is the main reason the low star count is tolerable.

Compatibility

• Pin an exact version in composer.json; run composer why-not against the current framework before committing.
• Keep the vendor package out of the public API surface so a future Laravel upgrade only touches the adapter.
• Wrap the client in a project-owned config block; do not let config/smsir.php leak into application code.

Sequencing

1. Spike (0.5–1 day): sandbox/test line, send one verify message, confirm auth header, template ID handling, and response shape.
2. Contract + adapter (1 day): interface, adapter, Http::fake-based tests, exception mapping to internal error types.
3. Delivery plumbing (1 day): queued job, per-provider rate limiter, timeout/retry policy (bounded retries, no retry on 4xx), idempotency key derived from the OTP challenge ID to prevent duplicate sends.
4. Observability: structured logs with phone numbers hashed, counters for send attempts / accepted / failed / delivery-confirmed, latency histogram, credit-level gauge with alert threshold.
5. Canary: 1–5% of OTP traffic with an automatic fallback provider on error rate breach, then ramp.
6. Cutover criteria: p95 send-to-accept under target, delivery rate within X% of incumbent, no duplicate-send incidents for two weeks.

Operational Impact

Maintenance

• Expect to own it. With one releasing organization and no dependents, plan for fork-and-vendor: mirror the repo internally, tag our own patch releases, and treat upstream as a source of fixes rather than a dependency.
• Recurring cost is low — perhaps 1–2 engineer-days per year for the adapter plus a quarterly review of SMS.ir API changes (the provider has iterated its API versions historically; a v1 deprecation would require an adapter update).
• Add a scheduled dependency audit so the package's framework constraints are checked on every Laravel upgrade.

Support

• Two support surfaces: the code (internal, we own it) and the account (SMS.ir support, Iranian business hours, Persian-language correspondence likely required).
• Account-level operations are the real support burden: credit top-ups, line-number provisioning, verify-template approval cycles, IP allowlist changes, and sender-ID registration. These have lead times measured in hours-to-days and should be documented as runbook steps with named owners.

Scaling

• The PHP package is not the scaling bottleneck; it is stateless and horizontal-scales with the app tier.
• Throughput is gated by purchased line numbers, account tier, and the provider's rate limits. Model peak OTP concurrency (login storms, campaign bursts) against contracted limits before launch.
• Use a dedicated queue and a rate limiter sized to the account's allowance so bulk marketing sends cannot starve OTP traffic. Consider separate line numbers per traffic class.
• Watch connection behavior under load: enforce explicit connect/read timeouts and cap concurrency to avoid worker pool exhaustion during gateway slowdowns.

Failure modes

Ramp-up

• A Laravel developer reaches productivity in roughly half a day; the code is small. The real learning curve is SMS.ir's panel semantics — verify templates vs bulk sends, line numbers vs sender IDs, delivery-report interpretation, and the difference between "accepted" and "delivered." Document these in a short internal runbook.
• Onboarding should include: how to rotate the API key, how to add a template, how to read the dashboards, and who to escalate to when delivery rates degrade.

Bottom line for a TPM: the package itself is a low-risk, low-differentiation commodity wrapper — the opportunity score reflects that the value sits in the integration discipline, not the library. Approve it only as an implementation detail behind an owned interface, with a fallback provider, a forked mirror, and the SMS.ir account (credit, lines, templates, regional access) treated as the actual production dependency.