byjg / sms-client

6.0.0 2025-11-24 18:05 UTC

Requires

• php: >=8.3 <8.6
• ext-curl: *
• byjg/webrequest: ^6.0

Requires (Dev)

• phpunit/phpunit: ^10.5|^11.5
• vimeo/psalm: ^5.9|^6.13

MIT

Published on Packagist.org on 2025-12-25 14:37 UTC

README

sidebar_key	sms-client
sidebar_category	messaging
tags	php sms

SMS Client

One interface to send SMS through any provider, and the right provider chosen by the phone number's country.

Why

SMS providers differ by country: one is cheap or reliable in the US, another in Brazil. Each has its own SDK, so supporting two means two code paths, and the choice is spread wherever a message is sent.

SMS Client puts the providers behind one interface, chosen by the connection URI, and can route each message by the destination country:

ProviderFactory::registerServices("twilio://accountId:authToken@default", "+1");
ProviderFactory::registerServices("byjg://username:password@default", "+55");

ProviderFactory::createAndSend("[phone]", new Message("Hello USA!"));      // Twilio
ProviderFactory::createAndSend("[phone]", new Message("Olá Brasil!"));   // ByJG

Phone numbers are validated and formatted per country, and a new provider is one class.

Features

• Low code - Simple, intuitive API for sending SMS
• Provider agnostic - Support for multiple SMS providers
• Extensible - Easy to implement custom providers
• Phone formatting - Built-in phone number validation and formatting
• Multi-provider support - Route messages to different providers based on country codes

Installation

composer require byjg/sms-client

Quick Start

use ByJG\SmsClient\Message;
use ByJG\SmsClient\Provider\ProviderFactory;
use ByJG\SmsClient\Provider\TwilioMessagingProvider;
use ByJG\Util\Uri;

// Register and create provider
ProviderFactory::registerProvider(TwilioMessagingProvider::class);
$provider = ProviderFactory::create(new Uri("twilio://$accountSid:$authToken@default"));

// Send message
$response = $provider->send(
    "[phone]",
    (new Message("Hello World!"))->withSender("[phone]")
);

// Check result
if ($response->isSent()) {
    echo "Message sent successfully!";
}

Documentation

• Basic Usage - Learn how to send SMS messages
• Phone Formatting - Phone number validation and formatting
• Providers - Available SMS providers and configuration
• Custom Providers - Create your own SMS provider

Available Providers

Provider	URI Scheme	Documentation	Region
Twilio Messaging	twilio://accountId:authToken@default	Twilio SMS	Global
Twilio Verify	twilio_verify://accountId:authToken@serviceSid	Twilio Verify	Global
ByJG SMS	byjg://username:password@default	ByJG	Brazil
Fake Sender	fakesender://	Testing only	Testing

Multi-Provider Setup

Route messages to different providers based on country codes:

use ByJG\SmsClient\Provider\ProviderFactory;
use ByJG\SmsClient\Provider\TwilioMessagingProvider;
use ByJG\SmsClient\Provider\ByJGSmsProvider;
use ByJG\SmsClient\Message;

// Register providers
ProviderFactory::registerProvider(TwilioMessagingProvider::class);
ProviderFactory::registerProvider(ByJGSmsProvider::class);

// Associate with country codes
ProviderFactory::registerServices("twilio://accountId:authToken@default", "+1");
ProviderFactory::registerServices("byjg://username:password@default", "+55");

// Automatically routes to the right provider
ProviderFactory::createAndSend("[phone]", new Message("Hello USA!"));
ProviderFactory::createAndSend("[phone]", new Message("Olá Brasil!"));

Phone Number Formatting

Format and validate phone numbers with country-specific rules:

use ByJG\SmsClient\Phone;
use ByJG\SmsClient\PhoneFormat\USPhoneFormat;

$phone = Phone::phone("2345678900", new USPhoneFormat())
    ->withPlusPrefix()
    ->withCountryCode();

echo $phone->hydrate();  // Output: [phone]
echo $phone->format();   // Output: [phone]

// Validate phone numbers
$isValid = $phone->validate(throwException: false);

Running Tests

vendor/bin/phpunit

Open source ByJG