SMS Providers
The SmsProvider interface (jethro-sms/src/SmsProvider.php) is the seam.
Everything above it works the same regardless of which gateway is being used.
Provider Interface
See jethro-sms/src/SmsProvider.php for the full interface. Key points:
- All methods return
\Result— callers checkisSuccess()/isFailure(). No exceptions for control flow. send()returns\Result<SmsDeliveryBatch, string>— usesendSummary($batch->deliveries, $recipients)for a high-levelAllSent/PartialSuccess/Failedtagged union.cancel(SmsDeliveryBatch)returns the batch with per-delivery statuses updated; per-delivery gateway failures leave that delivery unchanged.
Capabilities are checked via hasCapability(SmsCapability). See
jethro-sms/src/SmsCapability.php for the enum and each provider's
hasCapability() method for which it supports.
Provider Comparison
| Provider | Auth | Format | Schedule | Cancel | Status Poll | Balance | Sender Reg | Sender ID Reg |
|---|---|---|---|---|---|---|---|---|
FiveCentSmsV5Provider | key-id + key-secret in JSON body | JSON | ✓ | ✓ (DELETE) | ✓ (GET /v5/sms/{id}) | ✓ | ✓ | ✓ |
CellcastSmsProvider | Bearer token header | JSON | ✓ | ✓ (POST cancel) | ✓ (GET /api/v2/report/message/{id}) | ✓ | ✓ | ✓ |
SmsBroadcastSmsProvider | username + password | URL-encoded, line-based | ✓ | ✗ | ✗ | ✓ | ✗ | ✗ |
FiveCentSmsV4Provider | header template | URL-encoded | ✗ | ✗ | ✗ | ✓ | ✗ | ✗ |
TemplateSmsProvider | configurable | URL-encoded | ✗ | ✗ | ✗ | optional | ✗ | ✗ |
FiveCentSmsV5Provider
jethro-sms/src/Providers/FiveCentSmsV5Provider.php — key: '5centsmsv5',
preference: 10. All 9 capabilities. Segment cost: 5000 millicents (5.0¢).
Deferred send max delay: 365 days.
Test mode: "test": true in JSON body — real HTTP calls, API dry-runs.
CellcastSmsProvider
jethro-sms/src/Providers/CellcastSmsProvider.php — key: 'cellcast',
preference: 9. 7 capabilities (no GET_SENDER_IDS — uses
SMS_SENDER_OPTIONS override). Segment cost: 4300 millicents (4.3¢).
Deferred send max delay: 24 hours.
Sender number registration uses OTP verification. Sender ID registration
submits to /api/v1/business/add.
Test mode: CellcastFakeHttpClient returns realistic JSON for all endpoints.
SmsBroadcastSmsProvider
jethro-sms/src/Providers/SmsBroadcastSmsProvider.php — key:
'smsbroadcast', preference: -1. Supports GET_BALANCE and DEFERRED_SEND
only. Segment cost: 7000 millicents (7.0¢). No max delay.
FiveCentSmsV4Provider
jethro-sms/src/Providers/FiveCentSmsV4Provider.php — key: '5csmsv4',
preference: -1 (excluded from help text). Extends TemplateSmsProvider
with v4-specific defaults. Only supports GET_BALANCE. Deprecated.
TemplateSmsProvider
jethro-sms/src/Providers/TemplateSmsProvider.php — preference: -2
(excluded from auto-detection and help text). Generic URL-template-based
provider. Serves as base class for FiveCentSmsV4Provider.
Decorators
The provider chain is assembled from the inside out. See SMS Architecture for the full chain order.
LocalBalanceSmsProvider
(include/Jethro/Sms/Providers/LocalBalanceSmsProvider.php) — overrides
getBalance() from sms_purchases table when SMS_BALANCE is set.
Numeric = hardcoded, 'database' = live balance. Enforces
SMS_BALANCE_ENFORCED.
Auto-Detection
When SMS_PROVIDER is unset or 'auto', auto-detection iterates
providers by usagePreference() descending:
| Preference | Provider | Required constants |
|---|---|---|
| 10 | FiveCentSmsV5Provider | SMS_5CENTSMS_APIKEY_ID, SMS_5CENTSMS_APIKEY |
| 9 | CellcastSmsProvider | SMS_CELLCAST_APIKEY |
| -1 | SmsBroadcastSmsProvider | SMS_SMSBROADCAST_PASSWORD |
| -1 | FiveCentSmsV4Provider | SMS_HTTP_URL (must match v4 endpoint) |
| -2 | TemplateSmsProvider | SMS_HTTP_URL |
Short keys: '5centsmsv5', 'cellcast', 'smsbroadcast'.
Providers with negative preference are excluded from the "not configured"
error help text.