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

1. Install the package via composer:

composer require 4jawalycom/sms-gateway-4jawaly

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

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

1. Publish the configuration file:

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

1. 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.