Laravel Algeria Sms Laravel Package

Technical Evaluation

Architecture fit djouamaah/laravel-algeria-sms is a domain-specific Laravel package rather than a generic SMS abstraction. It follows idiomatic Laravel conventions: a facade (AlgeriaSms), a notification channel (algeria-sms), a validation rule (AlgerianMobile), package events (MessageSent, MessageFailed), a publishable config file, a packaged migration (sms_opt_outs), a queue-aware marketing path, and a fake() testing double. For any Laravel application serving Algerian users — e-commerce checkout OTP, delivery notifications, cash-on-delivery confirmation, promotional campaigns — this maps directly onto existing app architecture with no adapter layer required. The extension point (AlgeriaSms::extend()) plus a generic configurable http driver means the package owns the domain logic (OTP lifecycle, opt-out compliance, segmentation, quiet hours, number normalization) while delegating the transport contract to us. That is the correct split: it keeps vendor-specific API shape out of our codebase while removing the tedious, error-prone parts (GSM-7 vs UCS-2 counting, 05/06/07 carrier detection, accented-character transliteration) that we would otherwise reimplement badly.

Integration feasibility Install is three commands (composer require, php artisan migrate, vendor:publish), and the public API surface is small and legible: send(), otp()->send()/verify(), marketing(), optOut()/optIn()/isOptedOut(). The log driver provides a zero-dependency local path, so integration work can begin before any commercial contract with a carrier or aggregator exists. The critical caveat is stated plainly in the release notes: Algerian carriers and local providers do not publish API documentation, so the http driver must be configured from the provider's own docs after contracting, or a bespoke driver written via extend(). That makes provider onboarding the real integration cost, not the package itself — budget it as a distinct workstream.

Technical risk

• Transport is unbounded scope. The generic http driver shifts provider-specific concerns (auth scheme, payload shape, encoding, response codes, rate-limit semantics) onto our configuration. Every provider is a fresh, undocumented integration exercise.
• No delivery-receipt handling is described. MessageSent appears to fire on successful API call, not on handset delivery. For OTP and transactional use we should assume "accepted by gateway" ≠ "delivered," and plan accordingly.
• Version 1.0.0, first release, single-package provenance. No track record, no deprecation history, no stated support window. Treat as a young dependency.
• Compliance logic is opinionated and hardcoded. Quiet hours are fixed at 21:00–08:00 Algeria time, which is correct for Algerian marketing regulation but non-configurable per the notes — verify whether config can override before assuming.
• Security posture is promising but needs verification. OTPs stored HMAC-hashed, with expiry, wrong-attempt cap, resend cap, and hourly cap, is a sound design. Confirm the HMAC uses an app-keyed secret, constant-time comparison, and that caps are enforced per-identifier and per-purpose, not globally.
• Queue semantics. Marketing via queue raises the classic duplicate-send question on job retry; confirm whether the package provides idempotency or whether we must supply it.

Key questions

1. Supported PHP and Laravel version matrix, and the intended support/deprecation policy for 1.x?
2. Does the http driver support delivery-report (DLR) callbacks, or is that left entirely to the application?
3. Are rate-limit / quiet-hour / opt-out rules enforced at enqueue time or send time — and does a queued marketing batch re-check opt-outs before each dispatch?
4. Is the OTP HMAC derived from APP_KEY, and are comparisons constant-time and caps scoped per phone+purpose?
5. Which queue connections and batching primitives are assumed, and what is the retry/backoff story for http 5xx and 429 responses?
6. Does AlgeriaSms::fake() cover OTP verification flows and opt-out state, or only outbound sends?
7. Is there a per-tenant / multi-connection story, or is one global provider configuration assumed?
8. Who maintains the package, what is the issue-response expectation, and is there a private security disclosure channel?

Integration Approach

Stack fit Fit is high and narrow: Laravel app, PHP, queue worker already running, MySQL/Postgres for the sms_opt_outs migration. It slots in beside existing mail/notification infrastructure rather than replacing it — we keep Laravel's notification system as the dispatch surface and use the package as the algeria-sms channel. The AlgerianMobile validation rule should be standardized at the form-request layer so phone normalization is consistent from input through to send, which is where most SMS bugs in this domain actually originate.

Migration path There is nothing to migrate from unless we currently send via a raw HTTP client or an international aggregator. If we do, the path is: (1) wrap the existing sender behind AlgeriaSms::extend() so both paths produce identical payloads; (2) run the new package in shadow mode alongside the incumbent for a pilot cohort, comparing normalization, segmentation, and delivery outcomes; (3) cut over per use case (OTP first, then transactional, then marketing) rather than per environment. If we are greenfield, start with log, then a single http connection, then marketing.

Compatibility Two compatibility surfaces matter. First, Laravel/PHP version support — pin the package version in composer.json and validate against our framework version in CI before merging. Second, provider compatibility: the http

Sequencing

1. Feasibility spike (short). Install, publish config, run log driver end-to-end, stand up AlgeriaSms::fake() in the test suite. Confirm PHP/Laravel matrix. No provider needed.
2. Provider selection and contracting. Decide aggregator vs. direct carrier. This is a commercial and procurement task on the critical path — start it in parallel with step 1, not after.
3. Transport implementation. Configure the http driver or write an extend() driver against the contracted provider. Capture the provider's error taxonomy explicitly; this is where undocumented-API risk concentrates.
4. Transactional + OTP rollout. Wire MessageSent/MessageFailed into observability, add the AlgerianMobile rule to registration and checkout forms, and set OTP expiry/caps to match our security policy.
5. Opt-out and compliance. Ship sms_opt_outs, expose opt-out on every marketing message path, and verify quiet-hours behavior in a staging timezone test.
6. Marketing rollout. Enable queued batches last, with a low daily cap for the first two weeks, and reconcile opt-out state against any existing suppression list.

Deliberately deferring marketing until last keeps the highest-volume, highest-regulatory-risk path off the critical path for launch.

Operational Impact

Maintenance Ongoing cost is low but non-zero: track 1.x releases for a young package, re-verify after each Laravel major upgrade, and re-verify after any provider API change — the latter is the more likely breakage since the transport contract is ours, not the package's. Expect the accent-transliteration (gsm()) and segmentation logic to be the parts most likely to need local patches for edge cases (mixed Arabic/Latin content, emoji, URLs in message bodies). Keep such patches as thin application-side overrides rather than forks.

Support Documentation and API surface are Arabic-first with French/English message templates, which suits an Algerian product team; ensure at least one engineer can read the docs unaided. Support load will be dominated by provider issues, not package issues — so the operational runbook should be organized around the provider relationship (credentials rotation, sender-ID registration, rate-limit ceilings, escalation contact) rather than around the package.

Scaling Marketing throughput is bounded by the queue and by the provider's rate limits, not by the package; the batching and opt-out filtering design is appropriate. OTP and transactional sends are synchronous HTTP calls and will be the latency-sensitive path — set explicit connect/read timeouts and a bounded retry policy so a slow provider cannot tie up request workers. If volume grows past a single provider's capacity, the extend() mechanism permits multiple named connections, but failover across providers is not described and should be assumed to be our responsibility.

Failure modes

• Provider 5xx/timeout: OTP delivery silently degrades from the user's perspective. Needs alerting on MessageFailed rate and a user-facing "resend code" path that respects the resend cap.
• Rate-limit (429) during a marketing batch: jobs back off or fail; without idempotency, retries risk duplicate sends to the same number.
• Opt-out race: a contact opts out while a batch is already queued. Verify opt-out is checked at dispatch time, not only at enqueue time.
• Quiet-hours edge: a batch enqueued at 20:55 must be deferred, not partially sent. Validate this explicitly rather than assuming.
• Segmentation mismatch: sending Arabic content as GSM-7 or miscounting parts inflates cost and truncates messages — cover with unit tests around gsm() and the segment counter.
• Single-maintainer abandonment: mitigate by keeping the transport in our own driver (so a replacement package or a direct client is a small step) and by not letting domain state — opt-outs, OTP records — live solely in package-owned tables without an export path.

Ramp-up Ramp-up is genuinely short for a Laravel team: the facade and notification channel are idiomatic, the log driver and fake() let engineers work without credentials, and the example block is close to copy-pasteable. Realistically one engineer can complete steps 1–4 above in a sprint or two, with the provider contract as the pacing item. The knowledge that must be deliberately transferred rather than absorbed: (a) the provider's error taxonomy and how we map it to retries, (b) the compliance rules baked into quiet hours and opt-out — why they exist, and why they must not be "temporarily" bypassed for a campaign deadline, and (c) the OTP security parameters, so that a future engineer does not casually extend expiry or raise the attempt cap. Write those three down as decision records at adoption time; they are the parts most likely to be eroded silently.