README

Overview

The Laravel Taqnyat SMS package provides a simple integration with the Taqnyat SMS API to send SMS messages directly from your Laravel application. It includes methods for sending SMS messages, querying your account balance, retrieving available senders, and checking the system status of Taqnyat.

Features

• Send SMS: Send SMS messages to multiple recipients.
• Account Balance: Retrieve your Taqnyat account balance.
• Available Senders: Fetch the list of available sender names.
• System Status: Check the current status of the Taqnyat system.
• Configurable: Easily configure API authentication and default sender details.

Requirements

• PHP >= 7.2.5 (supports PHP 7.2.5 through 8.x)
• Laravel 6.x, 7.x, 8.x, 9.x, 10.x, 11.x, or 12.x
• GuzzleHttp for making HTTP requests.

Installation

Install the package via Composer:

composer require al-saloul/taqnyat

After installing the package, publish the configuration file:

php artisan vendor:publish --provider="Alsaloul\Taqnyat\TaqnyatSmsServiceProvider"

This command will create the config/taqnyat-sms.php configuration file where you can set your API authentication and sender information.

Configuration

After publishing the config file, update your .env file with your Taqnyat API credentials:

TAQNYAT_SMS_AUTH=your_api_key_here
TAQNYAT_SMS_SENDER=your_default_sender_name_here
TAQNYAT_SMS_BASE_URL=https://api.taqnyat.sa

Config Options

• TAQNYAT_SMS_AUTH: Your API key for authentication.
• TAQNYAT_SMS_SENDER: The default sender name for SMS messages.
• TAQNYAT_SMS_BASE_URL: The base URL for the Taqnyat API (default is https://api.taqnyat.sa).

Usage

You can use the package by either calling the TaqnyatSms facade or injecting the TaqnyatSms service into your classes.

Example: Sending an SMS via Facade

use Alsaloul\Taqnyat\TaqnyatSms;

$response = TaqnyatSms::sendMessage('Hello, this is a test message.', ['966********'], 'SenderName');
return $response;

Example: Injecting TaqnyatSms in Controller

use Alsaloul\Taqnyat\TaqnyatSms;

class SmsController extends Controller
{
    protected $sms;

    public function __construct(TaqnyatSms $sms)
    {
        $this->sms = $sms;
    }

    public function sendSms()
    {
        $body = 'Hello, this is a test message.';
        $recipients = ['966********'];
        $sender = 'SenderName';

        $response = $this->sms->sendMessage($body, $recipients, $sender);
        return response()->json($response);
    }
}

Available Methods

1. Send SMS

TaqnyatSms::sendMessage($body, $recipients, $sender, $smsId = '', $scheduled = '', $deleteId = '');

• $body: The SMS message content.
• $recipients: Array of recipient phone numbers.
• $sender: Sender name (optional, defaults to configured sender).
• $smsId (optional): Custom SMS ID for tracking purposes.
• $scheduled (optional): Scheduled date and time for sending the message.
• $deleteId (optional): ID for message deletion after sending.

2. Get Account Balance

Retrieve your account balance from Taqnyat:

$response = TaqnyatSms::getBalance();
return $response;

3. Get Available Senders

Get the list of available SMS sender names:

$response = TaqnyatSms::getSenders();
return $response;

4. Check System Status

Check the status of the Taqnyat system:

$response = TaqnyatSms::getStatus();
return $response;

Handling Errors

All methods use Guzzle for HTTP requests and are wrapped in try-catch blocks to handle exceptions gracefully. In case of an error, you will receive a descriptive error message which can help in debugging.

Example: Handling Errors

try {
    $response = TaqnyatSms::sendMessage('Hello, this is a test message.', ['966********'], 'SenderName');
    return $response;
} catch (Exception $e) {
    return 'Error: ' . $e->getMessage();
}

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Contributions are welcome! If you would like to contribute, please submit a pull request or open an issue for any bugs or feature requests.

Steps to Contribute

1. Fork the repository.
2. Create a new branch: git checkout -b feature-branch.
3. Make your changes.
4. Submit a pull request.

License

This package is open-sourced software licensed under the MIT License.