ahmedtaha-dev/fourjawaly-package

A Laravel package for managing fourjawaly services.

v1.0.1 2026-05-06 04:45 UTC

Requires

• illuminate/http: ^9.0|^10.0|^11.0|^12.0
• illuminate/support: ^9.0|^10.0|^11.0|^12.0

Requires (Dev)

• orchestra/testbench: ^10.11
• phpunit/phpunit: ^11.5

MIT

Published on Packagist.org on 2026-05-06 04:46 UTC

README

Send SMS through 4jawaly from a Laravel application. This package wraps the JSON API using Laravel’s HTTP client and your account credentials.

Requirements

• PHP 8.1+ (same as supported Laravel versions)
• Laravel 10, 11, or 12
• A 4jawaly account with API key, API secret, and an approved sender name

Installation

Install with Composer (adjust the constraint to match your setup):

composer require ahmedtaha/fourjawaly-package

If you are developing the package locally, add a path repository in your app’s composer.json, then require it as usual.

Register the service provider

The package does not rely on Composer auto-discovery yet. Register the provider manually.

Laravel 11+ — add to bootstrap/providers.php:

AhmedTaha\FourjawalyPackage\FourJawalyServiceProvider::class,

Laravel 10 — add to the providers array in config/app.php:

AhmedTaha\FourjawalyPackage\FourJawalyServiceProvider::class,

Configuration

Publish the config file:

php artisan vendor:publish --tag=fourjawaly-config

Set these variables in .env (names match config/fourjawaly.php):

FOURJAWALY_API_KEY=your_api_key
FOURJAWALY_API_SECRET=your_api_secret
FOURJAWALY_SENDER_NAME=your_registered_sender

FOURJAWALY_API_KEY and FOURJAWALY_API_SECRET are sent as HTTP Basic credentials (base64(key:secret)) to the 4jawaly API, consistent with their documentation.

Usage

Send a message

Use FourJawalyFacade to send SMS:

use AhmedTaha\FourjawalyPackage\Facades\FourJawalyFacade;

$result = FourJawalyFacade::send(
    ['9665XXXXXXXX', '9665YYYYYYYY'],
    'Your message text here.'
);

send returns the decoded JSON array from the API on success.

On failure it throws AhmedTaha\FourjawalyPackage\Exceptions\FourJawalyException (non-2xx responses and transport errors are wrapped).

use AhmedTaha\FourjawalyPackage\Exceptions\FourJawalyException;
use AhmedTaha\FourjawalyPackage\Facades\FourJawalyFacade;

try {
    FourJawalyFacade::send(['9665XXXXXXXX'], 'Hello');
} catch (FourJawalyException $e) {
    // Log or handle $e->getMessage()
}

FourJawalyFacade::send() validates input with AhmedTaha\FourjawalyPackage\Validation\FourJawalyValidation before calling the API: at least one phone number, each number a string using the 966 prefix with nine digits after it (no leading +), and a non-empty message. Validation failures throw FourJawalyException. You can call FourJawalyValidation::validate($phones, $message) yourself if you need the same checks outside send().

API endpoint

The client posts to:

https://api-sms.4jawaly.com/api/v1/account/area/sms/send

The package sends a JSON body with a messages array (text, numbers, and sender).

License

This package is licensed under the MIT License