PPPHP

SMS API – SMS Class

The SMS class sends text messages through a fully modular driver system. Built‑in international providers (Twilio, Vonage, Plivo, etc.) and five top Nepali providers are included. A Generic HTTP driver allows any custom gateway, and users can create their own named providers from the SMS Settings UI without writing code.

Contents

Architecture & Design

The SMS system follows a driver pattern: every provider is a small driver behind the same SMS API, so your code never changes when you switch provider. The installed drivers populate the provider dropdown in Misc → SMS Settings.

Quick Start

use PpPhp\Core\SMS;

// 1. Configure (usually done via Misc → SMS Settings, or programmatically)
SMS::SetConfig([
    'provider'   => 'twilio',
    'accountSid' => 'AC...',
    'authToken'  => 'abc...',
    'from'       => '+1234567890',
]);

// 2. Send
$result = SMS::Send('+9779812345678', 'Hello from pp-php!');
if ($result['success']) {
    echo 'Sent!';
} else {
    echo 'Error: ' . $result['error'];
}

Built‑in International Providers

ProviderRequired FieldsNotes
TwilioaccountSid, authToken, fromTrial accounts can only send to verified numbers.
Vonage (Nexmo)apiKey, apiSecret, fromSupports alphanumeric sender IDs.
MessageBirdaccessKey, fromCreate access key in Developers section.
PlivoauthId, authToken, fromTiered pricing; strong alternative to Twilio.
SinchservicePlanId, bearerToken, fromChoose region for base URL.
InfobipapiKey, baseUrl, fromBase URL found in Infobip portal.
ClickSendusername, apiKeyFrom is optional; uses shared numbers if blank.
Generic HTTPurl, method, toParam, msgParam, fromParamWorks with any gateway accepting HTTP requests.

Nepali Providers

ProviderRequired FieldsEndpoint
Sparrow SMStoken, identity, fromapi.sparrowsms.com/v2/sms/
Aakash SMStoken, fromaakashsms.com/admin/public/sms/v3/send

Need a provider that is not listed? Ask the platform owner — new providers are added as drivers and then appear in the dropdown automatically.

Creating Custom Providers (UI)

In the Misc → SMS Settings tab, click Add Custom Provider. Fill in:

After saving, the new provider appears in the dropdown and works like any built‑in driver. All settings are stored in project.json.

Example: Creating a Custom Provider for "BulkSMS"

  1. Click Add Custom Provider.
  2. Key: bulksms
  3. Label: BulkSMS Gateway
  4. API URL: https://bulksms.example.com/api/v1/send
  5. Method: POST
  6. to param: recipient
  7. message param: content
  8. from param: sender
  9. Extra params: api_key=MY_API_KEY,type=text
  10. Click Save.

Now select "BulkSMS Gateway" from the provider dropdown, fill in the required fields (like from), and send a test SMS.

Generic HTTP Driver

The Generic HTTP driver allows any SMS gateway that accepts HTTP requests. Use it directly from the SMS Settings tab (select "Generic HTTP") or programmatically:

SMS::SetConfig([
    'provider'     => 'http',
    'url'          => 'https://sms.example.com/api/send',
    'method'       => 'POST',
    'toParam'      => 'phone',
    'msgParam'     => 'text',
    'fromParam'    => 'sender',
    'extraParams'  => 'api_key=abc123,priority=high',
    'from'         => 'MyApp',
]);

$result = SMS::Send('+9779812345678', 'Your OTP is 123456');

Sending SMS

The SMS::Send($to, $message) method returns an associative array:

// Success
['success' => true]

// Failure
['success' => false, 'error' => 'Description of the error']

Example: Sending with a custom provider configured via the UI

// The UI already saved this config. In your code, just load the project state.
$state = ProjectState::load('my-project');
$smsConfig = $state['misc']['sms'] ?? [];
SMS::SetConfig($smsConfig);

$result = SMS::Send('+9779812345678', 'Hello!');
if ($result['success']) {
    echo 'OK';
} else {
    echo $result['error'];
}

Troubleshooting


🔗 Related Help Topics

Email API Notification API