ahmedtaha-dev/fourjawaly-package

A Laravel package for managing fourjawaly services.

1.0.0 2026-05-02 12:51 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

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()
}

Optional: validate input with the DTO

FourJawalyDTO checks that numbers are non-empty strings, use the 966 country prefix, and do not start with +. It also ensures the message is not blank. Use it before calling the API if you want consistent validation:

use AhmedTaha\FourjawalyPackage\DTO\FourJawalyDTO;
use AhmedTaha\FourjawalyPackage\Facades\FourJawalyFacade;

$dto = new FourJawalyDTO(['9665XXXXXXXX'], 'Hello from Laravel');
FourJawalyFacade::send($dto->phones, $dto->message);

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