Download the PHP package edenohana/sms-free-php without Composer

What this solves

Talking to the SMS4Free API is one curl call. Everything around it is where the work actually is.

Phone numbers arrive messy. 054-123-4567, +972 54 123 4567 and 00972541234567 are the same line, so they all get parsed into one canonical form, and anything that isn't a real Israeli mobile number is skipped and reported, so the rest of the list still goes out.

Hebrew breaks naive string handling. Cutting a message with substr() splits a two-byte character in half, and counting with strlen() reports bytes rather than characters. Everything here is multibyte-safe.

Failures need to be told apart. "The number is invalid", "the provider says you're out of balance" and "the network is down" call for three different reactions in your application, so each one is a different exception type.

And credentials are secrets: they never reach an exception message, and they're redacted from var_dump() output.

Requirements

Installation

Not using Composer? Copy the folder into your project and require the bundled autoloader:

Quick start

Keep secrets out of the source tree by reading them from the environment:

Handling failures

send() either returns a SendResult or throws. Every exception the library raises implements SmsFreeException, so a single catch is enough when you don't care about the difference:

Validating before you send

Checking numbers costs nothing, so validate the form first and only then spend a credit:

Provider-native bulk sends

sendBulk() preflights and deduplicates the complete input before making any network request, then sends all valid unique recipients through SMS4Free's native bulk capability in one POST. An invalid row at position 401 can therefore never appear after the first 400 rows were sent locally.

SMS4Free reports only an accepted count. If it is lower than the submitted count, the result exposes hasIndeterminateRecipientOutcomes(): the totals are known, but the provider does not identify which individual recipients were accepted. Never retry that request automatically.

Balance

Negative provider codes become ApiException; malformed or unusable responses become TransportException. A balance check is never performed automatically before a send because the balance could change between the two requests.

One bad number in a list of five hundred

By default an unparseable recipient is skipped: the message goes to everyone the library can parse, and the rest come back from SendResult::skippedRecipients(). A send to a single invalid number still throws, because there is nobody left to send to.

The skipped values come back exactly as they were supplied, so they can go straight into a report for whoever owns the list. A send where no recipient survives still throws, because delivering to nobody is never what the caller meant.

If you prefer one bad number to block the whole request (useful for OTP flows where the single recipient must be valid), switch the policy:

Or work with the value object directly:

Message length, Hebrew and credits

A Hebrew message is carried as UCS-2, which fits 70 characters per SMS part instead of the 160 a Latin message gets. That's the most common billing surprise with this provider, so the library makes it visible:

SMS4Free accepts long messages and splits them automatically. Version 3 sends the full body by default and estimates one credit for the first 134 characters, then another for every 67-character continuation. The provider's balance and invoice remain authoritative.

You can impose your own limit and reject a longer body:

Or explicitly opt into truncation. Enabling it without setting a custom limit uses the historical 134-character boundary:

One-time passcodes

Codes come from random_int(), PHP's cryptographically secure generator. Store the code hashed with an expiry and an attempt limit. examples/send-otp.php shows the whole flow.

Configuration

Defaults: a 5 second connect timeout and a 15 second overall timeout, full messages with no application-defined length cap, Israeli recipients only, unparseable recipients skipped, and TLS verification always on.

A note on retries

The library does not retry automatically. A timeout doesn't tell you whether the provider received the request, since the answer may simply have been lost on the way back, and an automatic retry can quietly send the same message twice and bill you twice. A local queue idempotency key can prevent the same job from running twice, but it cannot deduplicate a second provider request after a timeout.

Using a different HTTP stack

The transport sits behind HttpClient. Implement it to route requests through Guzzle, Symfony HttpClient, a PSR-18 client, or a fake in your own tests:

Laravel

The package ships a service provider, a facade and a notification channel, discovered automatically by Laravel 12 and 13. Fill in .env and you can send:

docs/laravel.md covers the config file, where the channel looks for a phone number, queued notifications and testing.

Upgrading to 3.0

Version 3 requires PHP 8.3, removes the deprecated global SMSService class, sends long messages in full by default, and corrects native bulk formatting to the provider's semicolon-delimited contract. UPGRADING.md contains the complete migration table.

Development

Contributing

Bug reports and pull requests are welcome, see CONTRIBUTING.md. Found a security issue? Please follow SECURITY.md instead of opening a public issue.

Legal

The MIT licence covers the code, including its "as is" disclaimer: no warranty, and no liability for what happens when you use it. Two things it does not cover, both of which sit with whoever sends the messages.

Israeli anti-spam law. Amendment 40 to the Communications (Telecommunications and Broadcasting) Law requires explicit prior consent before an advertising message is sent, an identifiable sender, and a working way to opt out. Statutory damages reach ₪1,000 per message without the recipient having to prove any loss, so a careless bulk send gets expensive quickly. A transactional message, such as a verification code or a delivery update for an order the person placed, is a different matter from marketing.

The provider's terms. This is an unofficial client. Your account is governed by SMS4Free's own terms, and nothing in this package changes what they permit.

smsFreePHP is not affiliated with, endorsed by, or connected to SMS4Free. The name is used only to say which API the library speaks to. None of the above is legal advice.

License

MIT © Eden Ohana