PHPackages                             mohamedhabibwork/laravel-wasl - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. mohamedhabibwork/laravel-wasl

ActiveLibrary[API Development](/categories/api)

mohamedhabibwork/laravel-wasl
=============================

Laravel package for integrating with Wasl API (Saudi Arabia's Transportation General Authority dispatching platform)

11[2 PRs](https://github.com/mohamedhabibwork/laravel-wasl/pulls)PHPCI passing

Since Jan 12Pushed 1mo agoCompare

[ Source](https://github.com/mohamedhabibwork/laravel-wasl)[ Packagist](https://packagist.org/packages/mohamedhabibwork/laravel-wasl)[ RSS](/packages/mohamedhabibwork-laravel-wasl/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (3)Used By (0)

Laravel Wasl
============

[](#laravel-wasl)

[![Latest Version on Packagist](https://camo.githubusercontent.com/404581389dabd1d4ccbc23a58c6b0ced3845fc2617dde12e238dbf3e1afdb016/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d6f68616d65646861626962776f726b2f6c61726176656c2d7761736c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/mohamedhabibwork/laravel-wasl)

[![GitHub Code Style Action Status](https://camo.githubusercontent.com/695fe586baf3b2d46c9937c4c7999d3e75078b781fcd11bc8af9433a4a99e6bd/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6d6f68616d65646861626962776f726b2f6c61726176656c2d7761736c2f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/mohamedhabibwork/laravel-wasl/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/3e7c518c186055b1f617ed28a1f9d87fa70139cfd782e1182c27b52c6f08a512/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d6f68616d65646861626962776f726b2f6c61726176656c2d7761736c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/mohamedhabibwork/laravel-wasl)

A Laravel package for integrating with the Wasl API (Saudi Arabia's Transportation General Authority dispatching platform). This package provides a clean, type-safe interface for all Wasl API endpoints including driver registration, eligibility checks, trip management, and location tracking.

Features
--------

[](#features)

- ✅ Complete Wasl API integration
- ✅ Type-safe DTOs with strict typing (PHP 8.3+)
- ✅ Comprehensive error handling with custom exceptions
- ✅ Built-in validation rules (plate letters, identity numbers, etc.)
- ✅ Error message helper with all Wasl API error codes and descriptions
- ✅ Support for bulk operations (arrays)
- ✅ Clean, modern code following Laravel best practices
- ✅ Full support for all 6 Wasl API endpoints

Requirements
------------

[](#requirements)

- PHP 8.3 or higher
- Laravel 11.x or 12.x

Installation
------------

[](#installation)

You can install the package via composer:

```
composer require mohamedhabibwork/laravel-wasl
```

Configuration
-------------

[](#configuration)

Publish the config file:

```
php artisan vendor:publish --tag="laravel-wasl-config"
```

Add your Wasl API credentials to your `.env` file:

**Environment-based configuration (Recommended):**

```
# Set environment: 'live' or 'dev' (default: 'live')
WASL_ENV=live

# Live environment credentials
LIVE_WASL_BASE_URL=https://wasl.api.elm.sa/api/dispatching/v2
LIVE_WASL_CLIENT_ID=your_live_client_id
LIVE_WASL_APP_ID=your_live_app_id
LIVE_WASL_APP_KEY=your_live_app_key
LIVE_WASL_TIMEOUT=30

# Dev environment credentials
DEV_WASL_BASE_URL=https://wasl.api.elm.sa/api/dispatching/v2
DEV_WASL_CLIENT_ID=your_dev_client_id
DEV_WASL_APP_ID=your_dev_app_id
DEV_WASL_APP_KEY=your_dev_app_key
DEV_WASL_TIMEOUT=30
```

### Environment Configuration

[](#environment-configuration)

The package supports two environments:

- **`live`** - Production environment (default)
- **`dev`** - Development/Testing environment

Set `WASL_ENV=dev` in your `.env` file to use the development environment. The package will automatically use the corresponding prefixed environment variables (`DEV_WASL_*` or `LIVE_WASL_*`).

Usage
-----

[](#usage)

### Driver Registration

[](#driver-registration)

Register a driver and vehicle with Wasl:

```
use Habib\LaravelWasl\Facades\LaravelWasl;
use Habib\LaravelWasl\DTOs\DriverRegistrationRequest;
use Habib\LaravelWasl\DTOs\DriverData;
use Habib\LaravelWasl\DTOs\VehicleData;

// For Saudi driver (Hijri date)
$driver = new DriverData(
    identityNumber: '1234567890',
    emailAddress: 'driver@example.com',
    mobileNumber: '+966512345678',
    dateOfBirthHijri: '1420/01/01'
);

// For Non-Saudi driver (Gregorian date)
$driver = new DriverData(
    identityNumber: '2234567890',
    emailAddress: 'driver@example.com',
    mobileNumber: '+966512345678',
    dateOfBirthGregorian: '1990-01-01'
);

$vehicle = new VehicleData(
    sequenceNumber: '123456879',
    plateLetterRight: 'ا',
    plateLetterMiddle: 'ا',
    plateLetterLeft: 'ا',
    plateNumber: '1234',
    plateType: '1'
);

$request = new DriverRegistrationRequest(
    driver: $driver,
    vehicle: $vehicle
);

$response = LaravelWasl::registerDriver($request);

// Check eligibility status
if ($response->eligibility === \Habib\LaravelWasl\Enums\EligibilityStatus::VALID) {
    echo "Driver is eligible until: " . $response->eligibilityExpiryDate;
}
```

### Check Driver Eligibility (Single)

[](#check-driver-eligibility-single)

```
use Habib\LaravelWasl\Facades\LaravelWasl;

$response = LaravelWasl::checkEligibility('1234567890');

echo "Eligibility: " . $response->driverEligibility->value;
echo "Expiry Date: " . $response->eligibilityExpiryDate;

foreach ($response->vehicles as $vehicle) {
    echo "Vehicle: " . $vehicle->sequenceNumber;
    echo "Vehicle Eligibility: " . $vehicle->vehicleEligibility->value;
}
```

### Check Driver Eligibility (Bulk)

[](#check-driver-eligibility-bulk)

Check eligibility for multiple drivers at once (max 10,000):

```
use Habib\LaravelWasl\Facades\LaravelWasl;
use Habib\LaravelWasl\DTOs\DriverEligibilityBulkRequest;

$request = new DriverEligibilityBulkRequest([
    '1000000001',
    '1000000002',
    '1000000003'
]);

$response = LaravelWasl::checkEligibilityBulk($request);

foreach ($response->responses as $driverResponse) {
    echo "Driver: " . $driverResponse->identityNumber;
    echo "Eligibility: " . $driverResponse->driverEligibility->value;
}
```

### Register a Trip

[](#register-a-trip)

```
use Habib\LaravelWasl\Facades\LaravelWasl;
use Habib\LaravelWasl\DTOs\TripRegistrationRequest;

$request = new TripRegistrationRequest(
    sequenceNumber: '123456789',
    driverId: '1234567890',
    tripId: 'TRIP_2025_001234',
    distanceInMeters: 5420,
    durationInSeconds: 1245,
    customerRating: 4.5,
    customerWaitingTimeInSeconds: 180,
    originCityNameInArabic: 'الرياض',
    destinationCityNameInArabic: 'الرياض',
    originLatitude: 24.723437,
    originLongitude: 46.117452,
    destinationLatitude: 24.763437,
    destinationLongitude: 46.547452,
    pickupTimestamp: '2025-12-07T14:30:00.000',
    dropoffTimestamp: '2025-12-07T14:50:45.000',
    startedWhen: '2025-12-07T14:25:00.000',
    tripCost: 35.50,
    driverArrivalTime: '2025-12-07T14:28:00.000',
    driverAssignTime: '2025-12-07T14:25:30.000'
);

$response = LaravelWasl::registerTrip($request);

if ($response->success) {
    echo "Trip registered successfully!";
}
```

### Update Trip(s)

[](#update-trips)

Update a single trip or multiple trips (max 1000):

```
use Habib\LaravelWasl\Facades\LaravelWasl;
use Habib\LaravelWasl\DTOs\TripUpdateRequest;

// Single trip update
$trip = new TripUpdateRequest(
    tripId: 'TRIP_2025_001234',
    customerRating: 5.0,
    tripCost: 35.50
);

$response = LaravelWasl::updateTrips($trip);

// Multiple trips update
$trips = [
    new TripUpdateRequest(
        tripId: 'TRIP_2025_001234',
        customerRating: 5.0,
        tripCost: 35.50
    ),
    new TripUpdateRequest(
        tripId: 'TRIP_2025_001235',
        customerRating: 4.0,
        tripCost: 28.00
    ),
];

$response = LaravelWasl::updateTrips($trips);

// Check for rejected trips
foreach ($response->rejectedTrips as $rejectedTrip) {
    echo "Trip {$rejectedTrip->tripId} rejected: {$rejectedTrip->rejectionReason}";
}
```

### Update Vehicle Location(s)

[](#update-vehicle-locations)

Update location for a single vehicle or multiple vehicles (max 1000):

```
use Habib\LaravelWasl\Facades\LaravelWasl;
use Habib\LaravelWasl\DTOs\LocationUpdateRequest;

// Single location update
$location = new LocationUpdateRequest(
    driverIdentityNumber: '1234567890',
    vehicleSequenceNumber: '123456789',
    latitude: 24.723437,
    longitude: 46.117452,
    hasCustomer: true,
    updatedWhen: '2025-12-07T15:30:00.000'
);

$response = LaravelWasl::updateLocations($location);

// Multiple locations update
$locations = [
    new LocationUpdateRequest(
        driverIdentityNumber: '1234567890',
        vehicleSequenceNumber: '123456789',
        latitude: 24.723437,
        longitude: 46.117452,
        hasCustomer: true,
        updatedWhen: '2025-12-07T15:30:00.000'
    ),
    new LocationUpdateRequest(
        driverIdentityNumber: '1234567891',
        vehicleSequenceNumber: '123456780',
        latitude: 25.723437,
        longitude: 47.117452,
        hasCustomer: false,
        updatedWhen: '2025-12-07T15:30:00.000'
    ),
];

$response = LaravelWasl::updateLocations($locations);

// Check for failed vehicles
foreach ($response->failedVehicles as $failedVehicle) {
    echo "Failed: {$failedVehicle}";
}
```

Error Handling
--------------

[](#error-handling)

The package provides custom exceptions for different error scenarios:

```
use Habib\LaravelWasl\Exceptions\WaslException;
use Habib\LaravelWasl\Exceptions\WaslNotFoundException;
use Habib\LaravelWasl\Exceptions\WaslBadRequestException;
use Habib\LaravelWasl\Exceptions\WaslUnauthorizedException;
use Habib\LaravelWasl\Exceptions\WaslServerException;

try {
    $response = LaravelWasl::registerDriver($request);
} catch (WaslNotFoundException $e) {
    // Driver or vehicle not found
    echo "Error: " . $e->getMessage();
    echo "Result Code: " . $e->resultCode;
} catch (WaslBadRequestException $e) {
    // Validation error or bad request
    echo "Error: " . $e->getMessage();
    echo "Result Message: " . $e->resultMsg;
} catch (WaslUnauthorizedException $e) {
    // Authentication failed
    echo "Authentication error: " . $e->getMessage();
} catch (WaslServerException $e) {
    // Server error
    echo "Server error: " . $e->getMessage();
} catch (WaslException $e) {
    // Other Wasl API errors
    echo "Error: " . $e->getMessage();
}
```

Validation
----------

[](#validation)

The package includes built-in validation for all Wasl API fields:

### Plate Letter Validation

[](#plate-letter-validation)

```
use Habib\LaravelWasl\Rules\WaslPlateLetter;

// Use in Laravel form requests
$rules = [
    'plate_letter' => ['required', new WaslPlateLetter()],
];

// Or access allowed letters directly
$allowedLetters = WaslPlateLetter::ALLOWED_LETTERS;
// ['ا', 'ب', 'ح', 'د', 'ر', 'س', 'ص', 'ط', 'ع', 'ق', 'ك', 'ل', 'م', 'ن', 'هـ', 'و', 'ى']
```

### DTO Validation

[](#dto-validation)

All DTOs automatically validate their data when instantiated:

```
use Habib\LaravelWasl\DTOs\DriverData;

try {
    $driver = new DriverData(
        identityNumber: '1234567890', // Must be exactly 10 digits
        emailAddress: 'driver@example.com', // Must be valid email
        mobileNumber: '+966512345678', // Must match +966XXXXXXXXX format
        dateOfBirthHijri: '1420/01/01' // Must be YYYY-MM-DD or YYYY/MM/DD
    );
} catch (\InvalidArgumentException $e) {
    echo "Validation error: " . $e->getMessage();
}
```

Error Message Helper
--------------------

[](#error-message-helper)

Get human-readable descriptions for Wasl API error codes:

```
use Habib\LaravelWasl\Helpers\WaslErrorMessageHelper;

// Get result code description
$description = WaslErrorMessageHelper::getResultCodeDescription('DRIVER_NOT_FOUND');
// Returns: "Driver information is not correct"

// Get rejection reason description
$reason = WaslErrorMessageHelper::getRejectionReasonDescription('DRIVER_LICENSE_EXPIRED');
// Returns: "Driver license is expired"

// Get criminal record status description
$status = WaslErrorMessageHelper::getCriminalRecordStatusDescription('PENDING_DRIVER_APPROVAL');
// Returns: "SMS sent to driver, waiting for approval on Absher"

// Get trip rejection reason (with Arabic support)
$englishReason = WaslErrorMessageHelper::getTripRejectionReason('duplicate trip id');
// Returns: "Trip ID is already registered"

$arabicReason = WaslErrorMessageHelper::getTripRejectionReason('duplicate trip id', arabic: true);
// Returns: "رقم الرحلة مسجل مسبقا"
```

Enums
-----

[](#enums)

The package includes enums for type safety:

```
use Habib\LaravelWasl\Enums\EligibilityStatus;
use Habib\LaravelWasl\Enums\Gender;
use Habib\LaravelWasl\Enums\PlateType;
use Habib\LaravelWasl\Enums\CriminalRecordStatus;

// EligibilityStatus: VALID, INVALID, PENDING
// Gender: MALE, FEMALE
// PlateType: PRIVATE_CAR, TAXI, TRUCK, BUS, MOTORCYCLE
// CriminalRecordStatus: WAITING, PENDING_DRIVER_APPROVAL, DRIVER_APPROVED, etc.
```

Testing
-------

[](#testing)

```
composer test
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

Please review [our security policy](.github/SECURITY.md) on how to report security vulnerabilities.

Credits
-------

[](#credits)

- [Mohamed Habib](https://github.com/mohamedhabibwork)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

22

—

LowBetter than 22% of packages

Maintenance60

Regular maintenance activity

Popularity3

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity15

Early-stage or recently created project

 Bus Factor1

Top contributor holds 60% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/465ce474e9c105751d2df13e0aa0f243cdd37909529b7f957cac01251644b1b1?d=identicon)[mohamedhabibwork](/maintainers/mohamedhabibwork)

---

Top Contributors

[![mohamedhabibwork](https://avatars.githubusercontent.com/u/64292519?v=4)](https://github.com/mohamedhabibwork "mohamedhabibwork (3 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (1 commits)")

### Embed Badge

![Health badge](/badges/mohamedhabibwork-laravel-wasl/health.svg)

```
[![Health](https://phpackages.com/badges/mohamedhabibwork-laravel-wasl/health.svg)](https://phpackages.com/packages/mohamedhabibwork-laravel-wasl)
```

###  Alternatives

[stripe/stripe-php

Stripe PHP Library

4.0k143.3M480](/packages/stripe-stripe-php)[twilio/sdk

A PHP wrapper for Twilio's API

1.6k92.9M272](/packages/twilio-sdk)[knplabs/github-api

GitHub API v3 client

2.2k15.8M187](/packages/knplabs-github-api)[facebook/php-business-sdk

PHP SDK for Facebook Business

90121.9M34](/packages/facebook-php-business-sdk)[meilisearch/meilisearch-php

PHP wrapper for the Meilisearch API

73813.7M114](/packages/meilisearch-meilisearch-php)[google/gax

Google API Core for PHP

263103.1M454](/packages/google-gax)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)