Clockworksms Laravel Package

Technical Evaluation

Architecture fit. mediaburst/clockworksms is a thin client for the Clockwork SMS REST API (a UK/IE-focused Mediaburst gateway). There is no persistence, no queueing, no domain model — it is a transport adapter. That is architecturally good: it is a small, replaceable boundary that can sit behind an internal SmsGateway interface without contaminating the domain layer. Expect a single client class with send(), credit(), deliveryReport()-style methods returning a result object or array with a success flag and error code. Do not expect framework features beyond (possibly) a Laravel service provider and facade alias.

Integration feasibility. Low. Composer install, one config value (API key, plus optional from-name/from-address), and a handful of calls. Realistically a half-day proof of concept for one engineer. The integration cost is not the code — it is the decisions around it (vendor lock-in, error semantics, secrets handling).

Technical risk. The material risk here is lifecycle, not complexity:

• Unmaintained: last release 2017-11-30. No tagged release in ~8 years. No visible evidence of PHP 8.1/8.2/8.3 support, return-type declarations, PSR-18/PSR-17 HTTP abstraction, or dependency hygiene (it may use raw cURL or file_get_contents, which is untestable and mock-hostile).
• Weak ecosystem signal: 45 stars, 0 dependents, package score 1.495. Effectively zero peer review; we would be one of the only consumers, which means we find the bugs.
• Vendor coupling: the package name and the vendor service are the same organisation. If Clockwork's API changes, the package will not chase it.
• Hidden surface: encoding (GSM-7 vs UCS-2), segment counting, concatenated messages, and long-message billing are classic SMS gotchas that thin wrappers often leave to the caller.

Key questions to answer before committing:

1. Is Clockwork still the right vendor for our regions/volumes, or is this a legacy preference? Confirm current pricing, delivery-report/webhook support, and sender-ID rules per country.
2. Does the package install cleanly on our PHP version, and does it pass a smoke send against the live API?
3. What HTTP layer does it use, and can we inject a mock for tests, or will we need to fork?
4. How are errors surfaced — exception, boolean, or error-code array? Is a failed send reliably distinguishable from a queued send?
5. Is there a maintained alternative (Twilio/Vonage/MessageBird SDKs, or a Laravel notification channel) that gives us the same outcome with active support?

Recommendation: viable as a contained adapter for a low-volume transactional SMS need, provided it is wrapped and vendored. Not appropriate as a strategic, long-lived dependency without ownership.

Integration Approach

Stack fit. Fits any Laravel/PHP application as an outbound side-effect service. The correct pattern is:

• app/Services/Sms/ClockworkGateway.php implementing an internal SmsGateway contract (send(to, body): SmsResult).
• The vendor package bound only inside that adapter — never injected into controllers, jobs, or models.
• Credentials in environment/secret manager (CLOCKWORK_API_KEY), never in config/ defaults committed to VCS.
• Config published to config/services.php or a dedicated config/sms.php, cached in production.

Migration path. Greenfield: trivial, direct adapter. Brownfield: define the SmsGateway interface first, implement it with the existing provider, then add Clockwork as a second implementation. This makes vendor swap a one-line container binding and enables A/B or failover between providers later.

Compatibility. Pin the package version explicitly in composer.json (do not float ^1.0 on an abandoned package). Run the test suite under the target PHP minor version before merge. If PHP 8 compatibility fails, the fallback is a fork-and-vendor: copy the ~200–400 lines into app/Support/Clockwork/ or a private Composer VCS repository, add type declarations, and own it. Given the code volume, this is cheap and probably the right call regardless.

Sequencing.

1. Spike: install, send one live SMS to a test number, confirm error shape.
2. Define SmsGateway contract and result value object.
3. Implement adapter with explicit error mapping and logging (message ID, recipient, status).
4. Move all sends off the request path into queued jobs with retry/backoff.
5. Add feature test with a faked HTTP client or a stubbed adapter.
6. Wire monitoring/alerting on failure rate before enabling production traffic.

Operational Impact

Maintenance. Treat as owned source, not as a dependency. Budget a small annual review (PHP version bump, API drift, credential rotation) plus a standing ticket to evaluate maintained alternatives. Because the code is tiny, the ongoing cost is hours, not days — but it is non-zero and it will not be handled by the upstream maintainer.

Support. Two distinct support surfaces: the service (Clockwork — account, billing, delivery, sender IDs) and the package (abandoned). Escalation for delivery issues goes to the vendor; escalation for bugs goes to us. Document this in the runbook so on-call does not chase a dead GitHub issue tracker.

Scaling. Bottleneck is the vendor (throughput caps, per-country sender rules, cost per segment), not the client. The client-side scaling concerns are: synchronous sends blocking web requests, connection reuse, and timeouts. Standard answer — queue all sends, set explicit connect/read timeouts (e.g. 2s/5s), cap concurrency against the vendor's rate limit, and track segment counts since billing is per 160-char GSM segment.

Failure modes to instrument.

• Vendor outage or 5xx → retries with exponential backoff; dead-letter queue after N attempts.
• Invalid/revoked API key → fast-fail loudly, alert immediately; this is a silent-outage risk if errors are swallowed.
• Rate limiting (429) → backoff, not tight-loop retry.
• Silent partial failure — result object with success=false but HTTP 200. Any code that ignores the return value will drop messages without a trace. Enforce return-value checking via the adapter contract.
• Encoding/length errors on unicode or emoji body content → validate and normalise before send.
• Duplicate sends from job retries → idempotency key or a sent-marker in the job.

Ramp-up. Very low for a competent Laravel developer — under a day to be productive, most of it spent on the vendor's error taxonomy and delivery-report semantics rather than the package. The knowledge that actually matters (SMS encoding, segment billing, carrier filtering, opt-out compliance) is not in this package and must come from the vendor docs and our own runbook. Write that runbook early; it outlives the dependency.