PHPackages                             itpalert/web2sms - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Mail & Notifications](/categories/mail)
4. /
5. itpalert/web2sms

ActiveLibrary[Mail & Notifications](/categories/mail)

itpalert/web2sms
================

Web2sms for laravel.

v2.2.1(4mo ago)02811MITPHPPHP ^8.0CI passing

Since Jan 29Pushed 4mo ago1 watchersCompare

[ Source](https://github.com/itpalert/web2sms)[ Packagist](https://packagist.org/packages/itpalert/web2sms)[ RSS](/packages/itpalert-web2sms/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (4)Versions (16)Used By (1)

itpalert/web2sms
================

[](#itpalertweb2sms)

A modern PHP client library for the Web2SMS API with type-safe response objects, comprehensive error handling, and optional Laravel integration.

![Tests](https://camo.githubusercontent.com/d940ad7f0752e2cbe0d63c50dcebf329078807390051c41fe63258f1b5c4e182/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f74657374732d70617373696e672d627269676874677265656e)![PHP Version](https://camo.githubusercontent.com/911a83e2aa6fe73660ab613629a95c76622bf03049a7344e80c5ea72d4ef9c7d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253545382e302d626c7565)![License](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)

Official API documentation:

Features
--------

[](#features)

- ✅ **Type-safe response objects** - No more array guessing
- ✅ **Comprehensive error handling** - Clear exceptions with context
- ✅ **Automatic character conversion** - GSM-7 encoding with transliteration
- ✅ **Dynamic message type conversion** - Switch between text/unicode freely
- ✅ **Segment counting** - Know exactly how many SMS credits you'll use
- ✅ **Secure nonce generation** - Fresh nonce for every request
- ✅ **Reusable SMS objects** - Send the same message multiple times safely
- ✅ **Laravel integration** - Facade and Service Provider included
- ✅ **Framework agnostic** - Works with any PHP project
- ✅ **Fully tested** - Unit and integration tests included

Requirements
------------

[](#requirements)

- PHP 8.0 or higher
- Guzzle HTTP Client 7.2+

Installation
------------

[](#installation)

Install via Composer:

```
composer require itpalert/web2sms
```

That's it! The package works out of the box.

Quick Start
-----------

[](#quick-start)

### Laravel

[](#laravel)

**1. Add configuration to `.env`:**

```
WEB2SMS_KEY=your_api_key_here
WEB2SMS_SECRET=your_api_secret_here
WEB2SMS_SMS_FROM=YourSender
WEB2SMS_ACCOUNT_TYPE=prepaid
```

**2. Add to `config/services.php`:**

```
'web2sms' => [
    'key' => env('WEB2SMS_KEY'),
    'secret' => env('WEB2SMS_SECRET'),
    'sms_from' => env('WEB2SMS_SMS_FROM', ''),
    'account_type' => env('WEB2SMS_ACCOUNT_TYPE', 'prepaid'),
],
```

**3. Send SMS using Facade:**

```
use ITPalert\Web2sms\SMS;
use ITPalert\Web2sms\Facades\Web2sms;

$sms = new SMS(
    to: '0712345678',
    from: '',  // Uses config default
    message: 'Hello from Laravel!',
    type: 'text'
);

$response = Web2sms::send($sms);

if ($response->isSuccess()) {
    $messageId = $response->getMessageId();
    echo "SMS sent! Message ID: {$messageId}";
}
```

### Plain PHP / Other Frameworks

[](#plain-php--other-frameworks)

```
use ITPalert\Web2sms\Credentials\Basic;
use ITPalert\Web2sms\Client;
use ITPalert\Web2sms\SMS;

// Create credentials
$credentials = new Basic(
    apiKey: 'your_api_key',
    apiSecret: 'your_api_secret',
    accountType: 'prepaid'  // or 'postpaid'
);

// Create client
$client = new Client($credentials, [
    'sms_from' => 'YourSender'  // Optional default sender
]);

// Create SMS
$sms = new SMS(
    to: '0712345678',
    from: 'YourSender',
    message: 'Hello World!',
    type: 'text'
);

// Send SMS
$response = $client->send($sms);

if ($response->isSuccess()) {
    echo "Message sent! ID: " . $response->getMessageId();
} else {
    echo "Error: " . $response->getErrorMessage();
}
```

Usage Guide
-----------

[](#usage-guide)

### Creating SMS Messages

[](#creating-sms-messages)

```
use ITPalert\Web2sms\SMS;

$sms = new SMS(
    to: '0712345678',        // Formats: +40712345678, 40712345678, 0712345678
    from: 'SENDER',          // Sender ID from Web2SMS platform
    message: 'Your message', // Message content
    type: 'text'             // 'text' or 'unicode'
);
```

**Message Types:**

- **`text`** - Automatically converts Unicode characters to GSM-7 compatible characters (Romanian: ăîâșț → aiast)
- **`unicode`** - Preserves all Unicode characters (costs more credits per message)

### Message Type Flexibility

[](#message-type-flexibility)

The SMS class stores your original message and converts it on-demand based on the current type:

```
use ITPalert\Web2sms\SMS;

// Create with text type
$sms = new SMS(
    to: '0712345678',
    from: 'SENDER',
    message: 'Mesaj în română',
    type: 'text'
);

// Get converted message (GSM-7 compatible)
echo $sms->getMessage();
// Output: "Mesaj in romana"

// Get original message (unconverted)
echo $sms->getOriginalMessage();
// Output: "Mesaj în română"

// Change to unicode type
$sms->setType('unicode');

// Now getMessage() returns original without conversion
echo $sms->getMessage();
// Output: "Mesaj în română"

// Change back to text
$sms->setType('text');
echo $sms->getMessage();
// Output: "Mesaj in romana" (converted again)
```

**Key Points:**

- Original message is always preserved via `getOriginalMessage()`
- `getMessage()` returns the converted message based on current type
- Changing type with `setType()` automatically affects conversion
- Type conversion happens on-demand (not stored)

### Optional Message Settings

[](#optional-message-settings)

```
// Set client reference (max 40 characters) - useful for tracking
$sms->setClientRef('ORDER-12345');

// Set delivery receipt callback URL
$sms->setDeliveryReceiptCallback('https://yoursite.com/sms-callback');

// Set displayed message (overrides actual message in Web2SMS platform UI)
$sms->setDisplayedMessage('Generic notification');

// Schedule message for future delivery
$sms->setSchedule('2024-12-31 10:30:00');
// Or use DateTime object
$sms->setSchedule(new DateTime('+2 hours'));
```

### Getting Message Segment Count

[](#getting-message-segment-count)

SMS messages are split into segments. Know how many credits you'll use:

```
$sms = new SMS('0712345678', 'SENDER', 'Your message', 'text');
$segments = $sms->getSegmentCount();

echo "This message will use {$segments} SMS credit(s)";
```

**Segment Limits:**

- **GSM-7 (text)**: 160 chars = 1 segment, 161+ chars = multiple segments of 153 chars each
- **Unicode**: 70 chars = 1 segment, 71+ chars = multiple segments of 67 chars each
- **Extended GSM-7 chars** (`{}[]^~|€`): Count as 2 characters

API Methods
-----------

[](#api-methods)

### Send SMS

[](#send-sms)

```
$response = $client->send($sms);

if ($response->isSuccess()) {
    $messageId = $response->getMessageId();  // Store this for tracking
}
```

**Returns:** `SendResponse`

**Available Methods:**

- `isSuccess()` - Returns true if error code is 0
- `getMessageId()` - Returns the unique message ID (hash)
- `getErrorCode()` - Returns integer error code
- `getErrorMessage()` - Returns error message string
- `toArray()` - Returns raw response data

### Get Message Status

[](#get-message-status)

```
$response = $client->get($messageId);

if ($response->isSuccess()) {
    $status = $response->getStatus();
    echo "Status: {$status}";
}
```

**Returns:** `StatusResponse`

**Status Codes:**

- `0` - Pending
- `1` - Sent to carrier
- `2` - Delivered
- `3` - Failed
- `4` - Expired

**Available Methods:**

- `getStatus()` - Returns status code as string
- Plus all base response methods

### Delete Scheduled Message

[](#delete-scheduled-message)

```
$response = $client->delete($messageId);

if ($response->isDeleted()) {
    echo "Message deleted successfully";
}
```

**Returns:** `DeleteResponse`

**Available Methods:**

- `isDeleted()` - Returns true if successfully deleted
- Plus all base response methods

### Check Account Balance

[](#check-account-balance)

```
$response = $client->balance();

if ($response->isSuccess()) {
    $balance = $response->getBalance();
    echo "Balance: {$balance}";
}
```

**Returns:** `BalanceResponse`

**Available Methods:**

- `getBalance()` - Returns balance as string
- Plus all base response methods

Error Handling
--------------

[](#error-handling)

### API-Level Errors (Non-Zero Error Code)

[](#api-level-errors-non-zero-error-code)

These are returned in the response object, not thrown as exceptions:

```
$response = $client->send($sms);

if (!$response->isSuccess()) {
    $errorCode = $response->getErrorCode();
    $errorMessage = $response->getErrorMessage();

    Log::warning('SMS failed', [
        'code' => $errorCode,
        'message' => $errorMessage,
    ]);
}
```

### HTTP/Network Errors

[](#httpnetwork-errors)

These are thrown as exceptions:

```
use ITPalert\Web2sms\Exceptions\Exception;

try {
    $response = $client->send($sms);

    if ($response->isSuccess()) {
        // Success handling
    } else {
        // API error handling
    }
} catch (Exception $e) {
    // Network/HTTP error handling
    Log::error('SMS request failed', [
        'error' => $e->getMessage(),
    ]);
}
```

### Complete Error Handling Example

[](#complete-error-handling-example)

```
use ITPalert\Web2sms\Exceptions\Exception;

try {
    $response = $client->send($sms);

    if ($response->isSuccess()) {
        // Deduct credits
        $user->smsCredits -= $sms->getSegmentCount();
        $user->save();

        // Log success
        Log::info('SMS sent', ['id' => $response->getMessageId()]);

        return ['success' => true, 'id' => $response->getMessageId()];
    }

    // API returned an error
    Log::warning('SMS API error', [
        'code' => $response->getErrorCode(),
        'message' => $response->getErrorMessage(),
    ]);

    return ['success' => false, 'error' => $response->getErrorMessage()];

} catch (Exception $e) {
    // Network/HTTP error
    Log::error('SMS network error', ['error' => $e->getMessage()]);

    return ['success' => false, 'error' => 'Network error occurred'];
}
```

Error Codes Reference
---------------------

[](#error-codes-reference)

Common Web2SMS API error codes:

CodeMessageDescription0`IDS_Prepaid_MessageController_E_OK`Success268435457No available accountCalling IP not authorized268435458Wrong phone formatInvalid phone number or network not configured268435459Empty messageMessage content is empty268435460Monthly limit exceededSMS sending limit reached268435462Account misconfiguredAccount configuration error268435463Account disabledAccount is disabled268435464Internal errorError creating SMS sender268435465Internal errorError scheduling SMS268435466Phone blacklistedNumber is on blacklist268435488Time restrictionScheduled time outside allowed interval268435520Network not configuredGSM network not configured for account536870913Internal errorInternal Web2SMS errorAdvanced Usage
--------------

[](#advanced-usage)

### Reusing SMS Objects

[](#reusing-sms-objects)

SMS objects can be safely reused for multiple sends. The Client automatically generates a fresh nonce for each request:

```
$sms = new SMS('0712345678', 'ALERT', 'Notification', 'text');

// Send to the same recipient multiple times
$response1 = $client->send($sms); // Fresh nonce: 1734567890
sleep(1);
$response2 = $client->send($sms); // Fresh nonce: 1734567891
sleep(1);
$response3 = $client->send($sms); // Fresh nonce: 1734567892

// Each send is independent and secure
```

This is particularly useful for:

- Retry logic on failures
- Sending the same message at different times
- Testing without recreating SMS objects

### Custom HTTP Client

[](#custom-http-client)

You can provide your own configured Guzzle client:

```
use GuzzleHttp\Client as GuzzleClient;
use ITPalert\Web2sms\Client;

$httpClient = new GuzzleClient([
    'timeout' => 30,
    'verify' => true,
    // ... other Guzzle options
]);

$client = new Client($credentials, [], $httpClient);
```

### Laravel: Dependency Injection

[](#laravel-dependency-injection)

The Client class can be injected directly into your Laravel services:

```
use ITPalert\Web2sms\Client;
use ITPalert\Web2sms\SMS;

class NotificationService
{
    public function __construct(
        private Client $web2sms
    ) {}

    public function sendVerification($user)
    {
        $code = random_int(100000, 999999);

        $sms = new SMS(
            to: $user->phone,
            from: '',
            message: "Your verification code: {$code}",
            type: 'text'
        );

        $response = $this->web2sms->send($sms);

        if ($response->isSuccess()) {
            session(['verification_code' => $code]);
            return true;
        }

        return false;
    }
}
```

**Or use the Facade for simpler syntax:**

```
use ITPalert\Web2sms\Facades\Web2sms;
use ITPalert\Web2sms\SMS;

class NotificationService
{
    public function sendVerification($user)
    {
        $code = random_int(100000, 999999);

        $sms = new SMS($user->phone, '', "Code: {$code}", 'text');
        $response = Web2sms::send($sms);

        return $response->isSuccess();
    }
}
```

Both approaches work seamlessly with Laravel's service container.

### Bulk SMS Sending

[](#bulk-sms-sending)

```
$recipients = ['0712345678', '0723456789', '0734567890'];
$message = 'Bulk notification message';

foreach ($recipients as $recipient) {
    $sms = new SMS($recipient, 'SENDER', $message, 'text');

    try {
        $response = $client->send($sms);

        if ($response->isSuccess()) {
            echo "Sent to {$recipient}: {$response->getMessageId()}\n";
        }
    } catch (Exception $e) {
        echo "Failed to send to {$recipient}: {$e->getMessage()}\n";
    }

    // Rate limiting - avoid sending too fast
    usleep(100000); // 100ms delay between messages
}
```

### Character Encoding Examples

[](#character-encoding-examples)

```
// Romanian text - automatically converted with type 'text'
$sms = new SMS('0712345678', 'ALERT', 'Bună ziua! Ați primit un mesaj.', 'text');
echo $sms->getMessage();
// Output: "Buna ziua! Ati primit un mesaj." (GSM-7 compatible)

// Preserve Romanian characters with type 'unicode' (costs more)
$sms = new SMS('0712345678', 'ALERT', 'Bună ziua! Ați primit un mesaj.', 'unicode');
echo $sms->getMessage();
// Output: "Bună ziua! Ați primit un mesaj." (original preserved)

// Check segments before sending
echo $sms->getSegmentCount(); // Know the cost

// Access original message regardless of type
echo $sms->getOriginalMessage(); // Always returns: "Bună ziua! Ați primit un mesaj."
```

**Supported Transliterations:**

- Romanian: `ăîâșț` → `aiast`, `ĂÎÂȘȚ` → `AIAST`
- Polish: `ąćęłńóśźż` → `acelnoszz`
- Czech/Slovak: `čďěňřšťůž` → `cdenrstuz`
- French: `œ` → `oe`, `Œ` → `OE`
- And many more...

Examples
--------

[](#examples)

### Laravel Notification

[](#laravel-notification)

```
use ITPalert\Web2sms\SMS;
use ITPalert\Web2sms\Facades\Web2sms;

class OrderConfirmed
{
    public function send($order)
    {
        $message = "Order #{$order->id} confirmed! Total: {$order->total} RON";

        $sms = new SMS(
            to: $order->customer->phone,
            from: '',
            message: $message,
            type: 'text'
        );

        $sms->setClientRef("ORDER-{$order->id}");

        $response = Web2sms::send($sms);

        if ($response->isSuccess()) {
            $order->update([
                'sms_sent' => true,
                'sms_message_id' => $response->getMessageId(),
            ]);
        }
    }
}
```

### Scheduled Reminder

[](#scheduled-reminder)

```
$sms = new SMS(
    to: '0712345678',
    from: 'REMINDER',
    message: 'Appointment tomorrow at 10:00 AM. Reply CONFIRM to confirm.',
    type: 'text'
);

// Schedule for tomorrow at 9:00 AM
$sms->setSchedule((new DateTime('tomorrow'))->setTime(9, 0));

$response = $client->send($sms);

if ($response->isSuccess()) {
    echo "Reminder scheduled: " . $response->getMessageId();
}
```

### Two-Factor Authentication

[](#two-factor-authentication)

```
$code = random_int(100000, 999999);

$sms = new SMS(
    to: $user->phone,
    from: 'VERIFY',
    message: "Your verification code is: {$code}",
    type: 'text'
);

$response = $client->send($sms);

if ($response->isSuccess()) {
    // Store code in session/cache
    session(['2fa_code' => $code, '2fa_expires' => now()->addMinutes(5)]);
}
```

### Dynamic Type Switching

[](#dynamic-type-switching)

```
// Start with text type for cost efficiency
$sms = new SMS(
    to: '0712345678',
    from: 'ALERT',
    message: 'Mesaj important în română',
    type: 'text'
);

// Check if conversion is acceptable
echo $sms->getMessage(); // "Mesaj important in romana"

// If diacritics are important, switch to unicode
if ($requiresDiacritics) {
    $sms->setType('unicode');
    echo $sms->getMessage(); // "Mesaj important în română"
}

// Send with the chosen type
$response = $client->send($sms);
```

Testing
-------

[](#testing)

Run the test suite:

```
composer test
```

Run specific test suites:

```
# Unit tests only
vendor/bin/phpunit --testsuite "Unit Tests"

# Laravel integration tests only
vendor/bin/phpunit --testsuite "Laravel Integration"
```

Contributing
------------

[](#contributing)

Contributions are welcome! Please feel free to submit a Pull Request.

Changelog
---------

[](#changelog)

### v2.2.0 (2024-12-12)

[](#v220-2024-12-12)

**Breaking Changes:**

- Removed `getNonce()` method from SMS class (nonce now generated by Client)

**New Features:**

- Added `getOriginalMessage()` to SMS class
- Dynamic message type conversion (change type and conversion updates automatically)
- Improved SMS object reusability (can safely send multiple times)

**Improvements:**

- Fresh nonce generated for each request (better security)
- Cleaner separation of concerns (SMS = data, Client = requests)

### v2.1.1 (2024-12-11)

[](#v211-2024-12-11)

**New Features:**

- Added comprehensive Laravel integration tests
- Framework-agnostic architecture with optional Laravel support

### v2.0.1 (2024-12-10)

[](#v201-2024-12-10)

**Bug Fixes:**

- Fixed Unicode to GSM-7 conversion bug in `SMS::setMessage()`

**Improvements:**

- Added comprehensive test suite (40+ tests)
- Simplified Guzzle dependency management

### v2.0.0 (2024-12-09)

[](#v200-2024-12-09)

Major rewrite with breaking changes:

- Added typed response objects (`SendResponse`, `StatusResponse`, etc.)
- Improved error handling with dedicated exception classes
- Simplified API with cleaner method signatures
- Requires PHP 8.0+

See [CHANGELOG.md](CHANGELOG.md) for full release notes.

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE) for more information.

Support
-------

[](#support)

For issues, questions, or contributions:

- **GitHub Issues**:
- **Email**:
- **Web2SMS Support**:

Credits
-------

[](#credits)

- **Author**: Gere Attila
- **Web2SMS API**: [Web2SMS Romania](https://www.web2sms.ro)

###  Health Score

40

—

FairBetter than 88% of packages

Maintenance74

Regular maintenance activity

Popularity13

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity54

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~49 days

Recently: every ~3 days

Total

15

Last Release

147d ago

Major Versions

1.3.2 → 2.0.12025-12-09

### Community

Maintainers

![](https://www.gravatar.com/avatar/e8df0aad126cca40aa8e0d8cd1307044acd978219393c09da1e7f5469b4d5c53?d=identicon)[itpalert](/maintainers/itpalert)

---

Top Contributors

[![itpalert](https://avatars.githubusercontent.com/u/37656719?v=4)](https://github.com/itpalert "itpalert (31 commits)")

---

Tags

notificationsweb2sms

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/itpalert-web2sms/health.svg)

```
[![Health](https://phpackages.com/badges/itpalert-web2sms/health.svg)](https://phpackages.com/packages/itpalert-web2sms)
```

###  Alternatives

[minishlink/web-push

Web Push library for PHP

1.9k12.0M53](/packages/minishlink-web-push)[paragraph1/php-fcm

PHP application server for google firebase cloud messaging (FCM)

1991.2M10](/packages/paragraph1-php-fcm)[benwilkins/laravel-fcm-notification

Laravel FCM (Firebase Cloud Messaging) Notification Channel

210964.1k1](/packages/benwilkins-laravel-fcm-notification)[bentools/webpush-bundle

Send push notifications through Web Push Protocol to your Symfony users.

71274.3k](/packages/bentools-webpush-bundle)[beyondcode/slack-notification-channel

Slack Notification Channel for Laravel using API tokens.

85525.8k](/packages/beyondcode-slack-notification-channel)[edwinhoksberg/php-fcm

A library for sending Firebase cloud messages and managing user topic subscriptions, device groups and devices.

68328.5k1](/packages/edwinhoksberg-php-fcm)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)