README.md

---

Laravel Algerian Cities : A comprehensive Laravel package to easily manage and interact with Algerian administrative divisions.

It provides functionality to load Wilayas (provinces) and Communes (municipalities) in both Arabic and French, complete with postal codes and precise latitude/longitude coordinates for each commune.

Features

• Includes all 58 Algerian Wilayas and 1541 Communes.
• Wilaya and Commune Eloquent models with relationships.
• Supports Arabic and French languages.
• Includes postal codes and latitude/longitude for each commune.
• Helper functions for easy integration in Blade views.
• Available as API endpoints.

Requirements

• PHP : 8.1 or higher
• Laravel : 10 and 11

Installation

You can install the package via composer:

composer require kossa/algerian-cities

Next, publish the migrations and seeders by running the installation command:

php artisan algerian-cities:install

Usage

Basic usage

The package provides two models: Wilaya and Commune.

A Wilaya has many Commune, and you can interact with them just like any other Eloquent models.

// Retrieve all Wilayas
$wilayas = Wilaya::all();
    
// Retrieve all Communes
$communes = Commune::all();
    
// Get all Communes belonging to Algiers (Wilaya ID: 16)
$algiers_communes = Commune::where('wilaya_id', 16)->get();

Using Helper Functions

The package provides several helper functions for convenient data retrieval:

$wilayas = wilayas();                                                // Get all Wilayas as $id => $name
$wilayas = wilayas('arabic_name');                                   // Get all Wilayas with names in Arabic
$communes = communes();                                              // Get all Communes as $id => $name
$communes = communes(16);                                            // Get all Communes of Algiers (Wilaya ID: 16) as $id => $name
$communes = communes(16, $withWilaya = true);                        // Get all Communes of Algiers (16) including Wilayas: "Alger Centre, Alger"
$communes = communes(16, $withWilaya = true, $name = 'arabic_name'); // Get all Communes of Algiers (16) with Wilayas in Arabic: "الجزائر الوسطى, الجزائر"

$single_commune = commune(1);                      // Retrieve a single Commune model
$single_commune = commune(1, $withWilaya = true);  // Retrieve a single Commune model, including its Wilaya
$single_wilaya = wilaya(1);                        // Retrieve a single Wilaya model

Blade Templates / Views

You can leverage the provided helpers or models to populate <select> elements:

<!-- Select for Wilayas -->
<select>
    @foreach (wilayas() as $id => $wilaya)
        <option value="{{ $id }}">{{ $wilaya }}</option>
    @endforeach
</select>

<!-- Select for Communes -->
<select>
    @foreach (communes() as $id => $commune)
        <option value="{{ $id }}">{{ $commune }}</option>
    @endforeach
</select>

<!-- Select for Communes of Algiers (Wilaya ID: 16) -->
<select>
    @foreach (communes(16) as $id => $commune)
        <option value="{{ $id }}">{{ $commune }}</option>
    @endforeach
</select>

<!-- Select for Communes with Wilaya Name (e.g., "Adrar, Adrar") -->
<select>
    @foreach (communes(null, true) as $id => $commune)
        <option value="{{ $id }}">{{ $commune }}</option>
    @endforeach
</select>

<!-- Select for Communes with Wilaya Name in Arabic (e.g., "أدرار, أدرار") -->
<select>
    @foreach (communes(null, true, 'arabic_name') as $id => $commune)
        <option value="{{ $id }}">{{ $commune }}</option>
    @endforeach
</select>

Using the Package as an API

This package includes api.php routes, allowing you to interact with the data through a RESTful API. Here are the available endpoints:

Verb	URI	Description
GET	/api/wilayas	Retrieve all Wilayas
GET	/api/wilayas/{id}	Retrieve a specific Wilaya by ID
GET	/api/wilayas/{id}/communes	Retrieve all Communes from a specific Wilaya by ID
GET	/api/communes	Retrieve all Communes
GET	/api/communes/{id}	Retrieve a specific Commune by ID
GET	/api/search/wilaya/{q}	Search Wilayas by name or Arabic name
GET	/api/search/commune/{q}	Search Communes by name or Arabic name

API Availability Toggle

You can enable or disable the Algerian Cities API endpoints by setting the following option in your .env file:

ALGERIAN_CITIES_API_ENABLED=false # Default: true

---

Future Planned Features

• Add support for Dairas (districts), including relationships with Wilayas and Communes
• Add support for additional languages
• Add a configuration file to allow customizing package behaviors
• Add support for caching to optimize API responses
• fix PHPUnit Deprecations

Contribution

We welcome all contributions! Please follow these guidelines:

1. Document any changes in behavior — ensure README.md updated accordingly.
2. Write tests to cover any new functionality.
3. Please ensure that your pull request passes all tests.

Issues & Suggesting Features

If you encounter any issues or have ideas for new features, please open an issue.

We appreciate your feedback and contributions to help improve this package.

Credits

• Kouceyla , and all contributors who have helped improve and enhance the project.
• The list of Wilayas and Communes is sourced from Wilaya-Of-Algeria.

Security Reports

If you discover any security vulnerabilities, please report them by emailing the package maintainer at hadjikouceyla at gmail.

⭐ Support Us

If you find this package helpful, please consider giving it a ⭐ on GitHub ! Your support encourages us to keep improving the project. Thank you!

License

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