README

A modern, production-ready PHP SDK for AYOSMS! Global SMS Gateway, fully aligned with their official API documentation.

⚙️ Designed for developers who want reliable SMS, OTP, and HLR integration within PHP applications — including CodeIgniter, Laravel, or pure PHP environments.

🚀 Features

✅ Complete API Coverage

• sendSMS() — Send single or bulk SMS
• checkBalance() — Retrieve account balance
• sendHLR() — Perform HLR lookups
• otpRequest() — Request OTP delivery via SMS
• otpCheck() — Verify received OTP

✅ Robust Error Handling

• Handles network, HTTP, and JSON parsing errors
• Detects invalid parameters and malformed requests
• Maps AYOSMS official error codes (ERR001–ERR999)

✅ Professional PHPDoc

• Full type-hinting for modern IDEs (PhpStorm, VSCode, etc.)
• Inline documentation for every parameter and return type

✅ Secure & Standards-Compliant

• Uses HTTPS with CURLOPT_SSL_VERIFYPEER
• Sanitizes and validates all inputs before request
• Compatible with PHP 7.4 – 8.3

✅ CodeIgniter Ready

• Drop directly into application/libraries/Ayosms.php
• Optional config file application/config/ayosms.php

🧠 Installation

🧩 Manual Install

# Copy the SDK file
cp Ayosms.php /path/to/your/project/application/libraries/

⚙️ Composer (recommended for modular use)

If you’re managing dependencies manually:

composer require imamrasyid/php-ayosms

🧰 Configuration

// application/config/ayosms.php
$config['api_key'] = 'YOUR_AYOSMS_API_KEY';

Then in your controller:

$this->load->library('Ayosms', $this->config->item('ayosms'));

Or in pure PHP:

require_once 'Ayosms.php';
$ayosms = new Ayosms(['api_key' => 'YOUR_API_KEY']);

✉️ Usage Examples

1️⃣ Send SMS

$response = $ayosms->sendSMS(
    from: 'AYOSMS',
    to: ['628123456789', '628987654321'],
    msg: 'Hello from AYOSMS PHP SDK!',
    options: [
        'trx_id' => 'demo-001',
        'dlr' => 1,
        'priority' => 'high'
    ]
);

echo $response; // JSON output

2️⃣ Check Balance

$response = $ayosms->checkBalance();

3️⃣ HLR Lookup

$response = $ayosms->sendHLR('628123456789', [
    'trx_id' => 'hlr-check-1'
]);

4️⃣ OTP Request

$response = $ayosms->otpRequest([
    'from' => 'AYOSMS',
    'to' => '628123456789',
    'secret' => 'my-shared-secret',
    'msisdncheck' => 1
]);

5️⃣ OTP Check

$response = $ayosms->otpCheck([
    'from' => 'AYOSMS',
    'secret' => 'my-shared-secret',
    'pin' => '123456'
]);

🧾 Response Format

Every method returns a JSON string — you can decode it via:

$data = json_decode($response, true);
if ($data['status'] === 1) {
    echo 'Success!';
} else {
    echo 'Error: ' . $data['error-text'];
}

⚡ Error Reference (Common Codes)

🧪 DLR (Delivery Report) Integration

If you enable DLR (Delivery Report) callback in your AYOSMS dashboard, use the helper:

$result = $ayosms->validateDlrPayload($_POST);
if ($result['valid']) {
    echo 'OK'; // required by AYOSMS
} else {
    error_log('Invalid DLR: ' . implode(',', $result['errors']));
}

🧩 Contributing

Pull requests are welcome! Please follow:

• PSR-12 coding standard
• PHPDoc best practices
• Commit message style: feat:, fix:, docs: etc.

🪄 Example Integration (CodeIgniter 3)

class Sms extends CI_Controller {
    public function send() {
        $this->load->library('Ayosms', ['api_key' => 'YOUR_KEY']);
        $resp = $this->ayosms->sendSMS('AYOSMS', '628123456789', 'Testing AYOSMS SDK');
        echo $resp;
    }
}

🧭 License

MIT License © 2025 — Created by Imam Rasyid

“Simple, elegant, and reliable — just like your SMS delivery.” 📡

📜 Changelog

🆕 v1.1 — Word-Safe SMS Splitting & Encoding Fix

Released V1.1

• 🧩 Fixed: Message encoding no longer uses rawurlencode($msg) (prevented double-encoding issues on special characters).
• 💬 Improved: Added intelligent word-safe segmentation (softSplitMessage()) ensuring long messages split naturally at spaces, never mid-word.
• 🧮 Refined: Segment calculation (calcSegments()) now respects human-readable boundaries.
• ⚡ Optimized: Internal code structure cleaned up for clarity and maintainability.
• ✅ Compatibility: 100 % backward-compatible with v1.0 API behavior.

🧰 v1.0 — Initial Release

Stable release – V1.0

• Full AYOSMS API coverage (SMS, OTP, HLR, Balance)
• Comprehensive error mapping
• CodeIgniter & Composer support
• PHPUnit test suite with 95 % coverage