README

A framework-agnostic PHP package for integrating with the YourBulkSMS HTTP API gateway. It provides a clean, SDK-like API, robust data normalization, custom exception handling, defensive webhook parsing, and optional Laravel integration.

Table of Contents

1. Features
2. Installation
3. Client Initialization
4. Public Methods & Feature Showcase
   • Send Standard SMS
   • Send Unicode SMS
   • Send Scheduled SMS
   • Send Scheduled Unicode SMS
   • Send International SMS
   • Check Route Balance
   • Fetch Delivery Report
5. Overriding Configuration Per-Request
6. Route Constants (Enums)
7. Webhook & DLR Parsing
   • Variant A: Query String Style
   • Variant B: JSON POST data Payload
8. Response DTO Structures
9. Laravel Integration
10. CodeIgniter 4 Integration
11. Testing

Features

• Framework Agnostic: Works out of the box in plain PHP, CodeIgniter 4, Laravel, or any PSR-4 compliant application.
• Guzzle Client Wrapper: Decoupled, clean HTTP request execution.
• Normalized Response DTOs: Consistent response shapes across all endpoints.
• Route Constants: Clear mapping of gateway route IDs.
• Robust Webhook Support: Automatically parses multiple DLR push payload formats.
• Defensive Error Handling: Explicit custom exceptions for validation, HTTP, authentication, and webhook errors.

Installation

Install the package via Composer:

composer require mysteryinfosolutions/yourbulksms

Client Initialization

To instantiate the client manually in plain PHP, pass an array configuration:

use MysteryInfo\YourBulkSms\YourBulkSmsClient;

$client = new YourBulkSmsClient([
    'authkey'                 => 'YOUR_AUTH_KEY',             // Required API Key
    'sender'                  => 'ABCDEF',                    // Default 6-char Sender ID (Optional)
    'route'                   => 2,                           // Default Route ID (Optional)
    'country'                 => 0,                           // Default Country Code prefix (Optional)
    'dlt_te_id'               => 'YOUR_DLT_TEMPLATE_ID',      // Default DLT template ID (Optional)
    'timeout'                 => 30.0,                        // HTTP Request timeout (Optional)
    'base_url'                => 'http://login.yourbulksms.com/api', // Base URL override (Optional)
    'default_response_format' => 'json',                      // Response format, 'json' or 'text' (Optional)
]);

Public Methods & Feature Showcase

Send Standard SMS

Accepts a single mobile number (string) or an array of numbers. Arrays are normalized to a comma-separated format automatically.

$response = $client->send(
    ['919999999990', '919999999999'], 
    'Hello from Mystery Info Solutions'
);

if ($response->success) {
    echo "Sent! Gateway Code: " . $response->code; // e.g. 001
}

Send Unicode SMS

Appends unicode=1 and sends the message payload as UTF-8 encoded text.

$response = $client->sendUnicode('919999999999', 'مرحبا بكم في حلول ميسري');

Send Scheduled SMS

Accepts a DateTimeInterface instance or a string format. Automatically normalizes it to the gateway-required Y-m-d H:i:s format.

$scheduleTime = new \DateTime('2026-07-01 15:30:00');
$response = $client->sendScheduled('919999999999', 'This is a scheduled message.', $scheduleTime);

Send Scheduled Unicode SMS

Combines Unicode payload and scheduling logic.

$response = $client->sendScheduledUnicode('919999999999', 'Scheduled Unicode ميسري', '2026-07-01 15:30:00');

Send International SMS

Uses the gateway global SMS endpoint (/global-smsapi.php).

$response = $client->sendInternational('447700900077', 'Hello international user!');

Check Route Balance

Checks remaining SMS balance on a specific route.

// Balance check for route type 1 (Promotional)
$balanceResponse = $client->getBalance(1); 
echo "Available Balance: " . $balanceResponse->balance;

Fetch Delivery Report

Retrieves the real-time status of an SMS by its message ID.

$report = $client->getDeliveryReport('message_id_123456');
echo "Status: " . $report->message;

Overriding Configuration Per-Request

You can override defaults (like sender, route, or dlt_te_id) on a per-request basis by passing them in the $options array:

use MysteryInfo\YourBulkSms\Support\Route;

$response = $client->send('919999999999', 'Override Example', [
    'sender'    => 'OTPSDR',          // Override default sender ID
    'route'     => Route::OTP,        // Override default route ID
    'dlt_te_id' => 'DLT_TEMPLATE_99', // Override default DLT Template ID
]);

Route Constants (Enums)

Use MysteryInfo\YourBulkSms\Support\Route to keep code clean and self-documenting:

use MysteryInfo\YourBulkSms\Support\Route;

Route::PROMOTIONAL;       // 1
Route::TRANSACTIONAL;     // 2
Route::CBIS_TRANS;        // 3
Route::UNI_TRANS;         // 4
Route::TELSPIES_TRANS;    // 5
Route::OTP;               // 6

Webhook & DLR Parsing

The SDK automatically detects the incoming webhook format and returns a normalized WebhookReportCollection containing WebhookReportItem objects.

Variant A: Query String Style

Webhook request format: GET /webhook.php?requestId=12345&userId=67890&status=000&date=1680766504000&senderId=TXTSMS&number=919999999999&desc=Delivered

$reports = $client->parseWebhook($_GET);

Variant B: JSON POST data Payload

Webhook request format: POST /webhook.php with a data parameter containing a raw JSON array string.

$reports = $client->parseWebhook($_POST); // or $_REQUEST

Parsing implementation:

foreach ($reports->items() as $item) {
    echo "Request ID: " . $item->requestId;
    echo "Recipient: " . $item->number;
    echo "Status Code: " . $item->status;
    echo "Description: " . $item->description;
    echo "Delivered At: " . $item->date; // Y-m-d H:i:s or date string
}

Response DTO Structures

All requests return structured DTOs containing the following public fields:

SendSmsResponse & DeliveryReportResponse

• bool $success: true if the gateway returns a success status.
• ?string $code: The raw status code from the gateway (e.g. 001, 002).
• ?string $message: Mapped human-readable message from ResponseCode mapper.
• mixed $data: Mapped response parameters (from JSON).
• string|array|null $raw: The exact HTTP response body from the gateway.

BalanceResponse

• bool $success: Request outcome.
• ?string $code: Gateway code.
• ?string $message: Human-readable status.
• mixed $balance: Extracted balance value.
• mixed $data: Decoded payload structure.
• string|array|null $raw: Raw response body.

Laravel Integration

1. Publish the configuration file:

   php artisan vendor:publish --tag="yourbulksms-config"

2. Add environment variables in .env:

   YOURBULKSMS_AUTHKEY=your_actual_auth_key
   YOURBULKSMS_SENDER=ABCDEF
   YOURBULKSMS_ROUTE=2

3. Call the API using the Facade:

   use MysteryInfo\YourBulkSms\Laravel\Facades\YourBulkSms;
   
   $response = YourBulkSms::send('919999999999', 'Hello from Laravel!');

CodeIgniter 4 Integration

Instantiate the client directly within your controllers:

use MysteryInfo\YourBulkSms\YourBulkSmsClient;

$client = new YourBulkSmsClient([
    'authkey' => 'YOUR_AUTH_KEY',
    'sender'  => 'SENDER_ID'
]);

$response = $client->send('919999999999', 'Hello from CodeIgniter!');

Testing

Run tests locally using PHPUnit:

vendor/bin/phpunit tests/YourBulkSmsClientTest.php