Sms Api Laravel Package

Technical Evaluation

What the package actually is. octopush/sms-api is a vendor-published PHP client for Octopush's REST SMS gateway, not a Laravel package. It ships a thin HTTP wrapper around send/balance/credit endpoints with no ServiceProvider, no facade, no publishable config, no queue integration, and no Notification channel. That distinction drives the whole assessment: we are buying a transport, and we will be building the Laravel-shaped layer on top of it ourselves.

Architecture fit. The lack of framework coupling is a genuine advantage. A stateless, dependency-light client nests cleanly behind an application-owned port (SmsSender interface) so the rest of the codebase never imports the vendor namespace. It also keeps our domain code swappable if Octopush's commercial terms or deliverability degrade. The cost is that every cross-cutting concern — retries, idempotency, rate limiting, structured logging, credential isolation, delivery-receipt ingestion — lands on us. None of that exists in the package.

Integration feasibility. High. composer require octopush/sms-api, wrap the client in a singleton bound to an interface, add a Notification channel class, and expose credentials via config/services.php and .env. Sending is a synchronous cURL call, so it must be moved behind a queued job from day one. Realistic estimate: 2–4 engineering days including tests, config, a sandbox smoke test, and a delivery-receipt webhook endpoint — with the caveat that the webhook is entirely ours to design, since the library does not manage callbacks or signature verification.

Technical risk. This is where the score and metadata matter more than the code.

Key questions for the spike.

1. Does it install and run clean on PHP 8.2/8.3 and the current Laravel LTS, or does the PHP constraint block us?
2. Does it target Octopush's current API version, or a deprecated endpoint set?
3. How are errors surfaced — exceptions, return codes, or silent nulls? What does a partial batch failure look like?
4. Are delivery receipts (DLRs) supported at all, and via webhook or polling?
5. Is there a sandbox/test mode, or does validation burn live credits?
6. Does it handle GSM-7 vs UCS-2 encoding and segment counting, or do we own concatenation and cost estimation?
7. Country-specific sender ID registration and 2-way/SMS-marketing compliance — does the library expose any of it, or is it purely send-only?
8. Is retry/idempotency keyed at all, or will a network timeout cause duplicate sends and duplicate charges?

Integration Approach

Stack fit. Laravel with a queued-job or Notification-channel send path. The library's synchronous cURL transport is the only real friction point; once sends are dispatched to a queue worker, the integration behaves like any other outbound HTTP dependency. Credentials belong in config/services.php, never in the package's own configuration surface (it doesn't have one).

Migration path. If we are already on Twilio/Vonage, do not rip it out. Introduce the SmsSender interface first, register the existing provider as the default implementation, then add OctopushSender as a second binding. Traffic shifts by config flag, one route or one notification type at a time, with per-channel metrics on both sides. This makes the evaluation reversible and gives us a real cost and deliverability comparison rather than a vendor argument.

Compatibility. Pin the exact version in composer.json. Because the package is unmaintained in practice, prefer vendoring the source into a small internal namespace over depending on an unversioned remote — it removes supply-chain and packagist-availability risk and lets us patch PHP 8 compatibility in-place. Verify Composer's platform requirements early; a hard php: ^7.x constraint would force the fork decision before any code is written.

Sequencing.

1. Spike (1–2 days). Install, send to a sandbox number, confirm error surface and DLR mechanism. Exit criteria: documented error taxonomy and a confirmed PHP/Laravel compatibility verdict.
2. Adapter (1–2 days). SmsSender interface, OctopushSender implementation, config binding, unit tests with a faked transport.
3. Delivery path (1 day). Notification channel plus a queued job with bounded retries and an idempotency key derived from the notification UUID.
4. Receipts and observability (1–2 days). DLR webhook endpoint, per-country success-rate and cost dashboards, alerting on failure-rate spike and credit depletion.
5. Failover (optional). Second provider behind the same interface, guarded by a circuit breaker.

Operational Impact

Maintenance. Effectively ours. With 18 stars, zero dependents, and no release since January 2022, there is no realistic prospect of timely upstream fixes. Budget for a named owner and a periodic compatibility review each time we bump PHP or the framework. The code surface is small, so this is hours per year, not days — but it must be someone's explicit responsibility rather than assumed.

Support. Layer the escalation path: Octopush account support for deliverability, sender ID registration, and billing; our own team for the integration layer. Expect the vendor's documentation to be more current than the library, so engineers should read the raw HTTP API docs and treat the package as a convenience, not a specification. Confirm the vendor's support hours and languages against our own on-call coverage before committing to SMS as an alerting channel.

Scaling. The library is stateless, so horizontal scaling is trivial — throughput is bounded entirely by Octopush's account-level rate limits, per-country sender registration, and prepaid credit balance. Two things to get right early: cost per segment is not linear with message length once UCS-2 encoding kicks in (non-Latin characters), so cost estimation must live in application code; and credit exhaustion is a hard global failure mode that deserves a proactive alert at a threshold, not a reactive one after a failed send.

Failure modes.

• Silent failure — the send call returns without raising, and nobody notices messages were dropped. Mitigate with explicit response parsing and a success assertion in the adapter.
• Duplicate sends — network timeout plus retry generates two billable messages. Mitigate with idempotency keys and a no-blind-retry rule on ambiguous timeouts.
• Partial batch failure — mixed success within one request. Mitigate by rejecting batch APIs entirely and sending one message per job.
• Global outage on credit exhaustion — all sends fail simultaneously. Mitigate with balance monitoring and a circuit breaker that surfaces a distinct error class.
• Unverified DLRs — an open webhook endpoint accepts spoofed delivery receipts. Mitigate with a shared secret or IP allowlist from day one, not later.
• Credential leakage — cURL-based clients often log full request context. Mitigate with an explicit redaction rule before the first production deploy.

Ramp-up. Low for any PHP developer — the public API is a handful of methods. The real onboarding cost is domain knowledge, not code: country-specific sender ID rules, encoding and segment math, quiet hours, and opt-out handling for marketing traffic. Plan half a day of provider documentation review per engineer, and encode that knowledge in tests rather than tribal memory.