README

A Laravel package for sending SMS messages through 4Jawaly SMS Gateway (4jawaly.com).

Requirements

PHP ^7.4|^8.0|^8.1|^8.2|^8.3
Laravel 7.x|8.x|9.x|10.x
Guzzle HTTP ^7.0

Installation

Install the package via composer:

composer require 4jawalycom/sms-gateway-4jawaly

Add the service provider to your config/app.php:

'providers' => [
    // ...
    Jawalycom\SMSGateway4Jawaly\SMSGatewayServiceProvider::class,
],

'aliases' => [
    // ...
    'SMSGateway' => Jawalycom\SMSGateway4Jawaly\Facades\SMSGateway::class,
],

Publish the configuration file:

php artisan vendor:publish --provider="Jawalycom\SMSGateway4Jawaly\SMSGatewayServiceProvider"

Add these variables to your .env file:

JAWALY_SMS_API_KEY=your_api_key
JAWALY_SMS_API_SECRET=your_api_secret
JAWALY_SMS_SENDER=your_sender_name

Usage

Method 1: Using the Facade

use Jawalycom\SMSGateway4Jawaly\Facades\SMSGateway;

// Important: All three parameters (number, message, sender) are required
// رقم الجوال ونص الرسالة واسم المرسل كلها متطلبات إلزامية

// Send SMS to a single number
$result = SMSGateway::send('966500000000', 'Your message here', 'SENDER_NAME');

// Send SMS to multiple numbers
$result = SMSGateway::send(
    ['966500000000', '966500000001'],
    'Your message here',
    'SENDER_NAME'
);

// Note: The sender name must be pre-approved by 4jawaly.com
// ملاحظة: يجب أن يكون اسم المرسل معتمداً مسبقاً من 4jawaly.com

// Check the result
if (!empty($result['success'])) {
    echo "Message sent successfully!";
    if (!empty($result['job_ids'])) {
        echo "Job IDs: " . implode(', ', $result['job_ids']);
    }
} else {
    echo "Failed to send message.";
    if (!empty($result['errors'])) {
        foreach ($result['errors'] as $error => $numbers) {
            echo "Error: $error - Numbers: " . implode(', ', $numbers);
        }
    }
}

Method 2: Using Direct Instantiation

use Jawalycom\SMSGateway4Jawaly\SMSGateway;

// Setup configuration array
$config = [
    'api_key' => env('JAWALY_SMS_API_KEY'),
    'api_secret' => env('JAWALY_SMS_API_SECRET'),
    'base_url' => 'https://api-sms.4jawaly.com/api/v1/',
    'default_sender' => env('JAWALY_SMS_SENDER'), // Must be pre-approved by 4jawaly.com
    'timeout' => 30,
    'verify_ssl' => true
];

// Create a new instance
$gateway = new SMSGateway($config);

// Send SMS (all parameters are required)
$result = $gateway->send('966500000000', 'Your message here', 'SENDER_NAME');

// Check the result
if (!empty($result['success'])) {
    echo "Message sent successfully!";
    if (!empty($result['job_ids'])) {
        echo "Job IDs: " . implode(', ', $result['job_ids']);
    }
} else {
    echo "Failed to send message.";
    if (!empty($result['errors'])) {
        foreach ($result['errors'] as $error => $numbers) {
            echo "Error: $error - Numbers: " . implode(', ', $numbers);
        }
    }
}

Getting Account Balance

// Using Facade
$balance = SMSGateway::getBalance();

// Using Direct Instantiation
$sms = new SMSGateway(config('jawaly-sms'));
$balance = $sms->getBalance();

// Get balance with custom options
$balance = SMSGateway::getBalance([
    'is_active' => 1,           // get active packages only
    'order_by' => 'id',         // package_points, current_points, expire_at or id
    'order_by_type' => 'desc',  // desc or asc
    'page' => 1,                // page number
    'page_size' => 10,          // items per page
    'return_collection' => 1    // get all collection
]);

Getting Sender Names

// Using Facade
$senders = SMSGateway::getSenderNames();

// Using Direct Instantiation
$sms = new SMSGateway(config('jawaly-sms'));
$senders = $sms->getSenderNames();

// Get sender names with custom options
$senders = SMSGateway::getSenderNames([
    'page_size' => 10,          // items per page
    'page' => 1,                // page number
    'status' => 1,              // 1 for active, 2 for inactive
    'sender_name' => '',        // search by sender name
    'is_ad' => '',             // 1 for ads, 2 for not ads
    'return_collection' => 1    // get all collection
]);

Response Format

Send SMS Response

[
    'success' => true,
    'job_id' => 'xxxxx',
    'data' => [
        // Full response from the API
    ]
]

Balance Response

{
    "collection": [
        {
            "id": xxx,
            "package_points": xxx,
            "current_points": xxx,
            "expire_at": "yyyy-mm-dd",
            // ... other package details
        }
    ],
    "pagination": {
        "total": xxx,
        "count": xxx,
        "per_page": xxx,
        "current_page": x,
        "total_pages": x
    }
}

Sender Names Response

{
    "collection": [
        {
            "id": xxx,
            "sender_name": "SENDER_NAME",
            "status": x,
            "note": "xxx",
            // ... other sender details
        }
    ],
    "pagination": {
        "total": xxx,
        "count": xxx,
        "per_page": xxx,
        "current_page": x,
        "total_pages": x
    }
}

Error Handling

The package throws exceptions for various error cases:

Invalid credentials
Empty message
Invalid sender name
Network errors
API errors

Example error handling:

try {
    $result = SMSGateway::send('966500000000', 'Your message', 'SENDER_NAME');
    // Message sent successfully
    echo "Message sent! Job ID: " . $result['job_id'];
} catch (\Exception $e) {
    // Handle the error
    echo "Error: " . $e->getMessage();
}

Features

Send SMS to single or multiple numbers
Support for Arabic and Unicode messages
Get account balance and package details
Retrieve approved sender names with filtering options
Pagination support for balance and sender names
Exception handling with meaningful error messages
Laravel integration with Facade support
Support for PHP 7.4 to 8.3
Support for Laravel 7.x to 10.x

Support

For support, please contact info@4jawaly.com

License

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

4jawalycom / sms-gateway-4jawaly

Maintainers

Details