PHPackages kossa/algerian-cities - 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. [Utility & Helpers](/categories/utility) 4. / 5. kossa/algerian-cities ActiveLibrary[Utility & Helpers](/categories/utility) kossa/algerian-cities ===================== A Laravel package to create/load wilayas and communes of Algeria v4.1.2(1y ago)847.9k↓27.5%17[4 PRs](https://github.com/kossa/algerian-cities/pulls)MITPHPPHP ^8.1CI passing Since Apr 6Pushed 2mo ago6 watchersCompare [ Source](https://github.com/kossa/algerian-cities)[ Packagist](https://packagist.org/packages/kossa/algerian-cities)[ Docs](https://github.com/kossa/algerian-cities)[ RSS](/packages/kossa-algerian-cities/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (4)Dependencies (5)Versions (18)Used By (0) [![Laravel Algerian Cities](docs/package-social-preview-readme.png)](docs/package-social-preview-readme.png) [![GitHub Workflow Status (master)](https://camo.githubusercontent.com/c5c35a66d3ffb9888d220578629958b6e84c6c93ac382e34d158fb94fd2e1190/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6b6f7373612f616c67657269616e2d6369746965732f6c61726176656c2e796d6c3f6272616e63683d6d6173746572266c6162656c3d5465737473)](https://github.com/kossa/algerian-cities/actions) [![Total Downloads](https://camo.githubusercontent.com/77224b452506ad694c00844cf06d8da410f1c958639f6819dab9b3b1461cbc15/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6b6f7373612f616c67657269616e2d636974696573)](https://packagist.org/packages/kossa/algerian-cities) [![Latest Version](https://camo.githubusercontent.com/39529f5aece0fb54342f2dee200dc168e1ce309d49e37bae34b061fff79fa232/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6b6f7373612f616c67657269616e2d636974696573)](https://packagist.org/packages/kossa/algerian-cities) [![GitHub Workflow Status (master)](https://camo.githubusercontent.com/197ad6a11efff59ae87475fe7a830332255bb783e4dc16b34fd7c2aa701d0d49/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6b6f7373612f616c67657269616e2d6369746965732f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d6173746572266c6162656c3d436f6465205374796c65)](https://github.com/kossa/algerian-cities/actions) [![License](https://camo.githubusercontent.com/5e472686cf349bc2addd5c3f10b10c35015a56f6f0e1fbdcb52e30b3f29a2b5b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6b6f7373612f616c67657269616e2d636974696573)](https://packagist.org/packages/kossa/algerian-cities) --- **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 -------- [](#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](#using-helper-functions). - [Available as API endpoints](#using-the-package-as-an-api). Requirements ------------ [](#requirements) - **PHP** : 8.1 or higher - **Laravel** : 10 or higher Installation ------------ [](#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 ----- [](#usage) ### Basic 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 [](#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 [](#blade-templates--views) You can leverage the provided helpers or models to populate `` elements: ``` @foreach (wilayas() as $id => $wilaya) {{ $wilaya }} @endforeach @foreach (communes() as $id => $commune) {{ $commune }} @endforeach @foreach (communes(16) as $id => $commune) {{ $commune }} @endforeach @foreach (communes(null, true) as $id => $commune) {{ $commune }} @endforeach @foreach (communes(null, true, 'arabic_name') as $id => $commune) {{ $commune }} @endforeach ``` Using the Package as an API --------------------------- [](#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: VerbURIDescriptionGET`/api/wilayas`Retrieve all WilayasGET`/api/wilayas/{id}`Retrieve a specific Wilaya by IDGET`/api/wilayas/{id}/communes`Retrieve all Communes from a specific Wilaya by IDGET`/api/communes`Retrieve all CommunesGET`/api/communes/{id}`Retrieve a specific Commune by IDGET`/api/search/wilaya/{q}`Search Wilayas by name or Arabic nameGET`/api/search/commune/{q}`Search Communes by name or Arabic name### API Availability Toggle [](#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 ----------------------- [](#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 ------------ [](#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 -------------------------------- [](#issues--suggesting-features) If you encounter any issues or have ideas for new features, please [open an issue](https://github.com/kossa/algerian-cities/issues/new). We appreciate your feedback and contributions to help improve this package. Credits ------- [](#credits) - [Kouceyla](https://github.com/kossa) , and all [contributors](https://github.com/kossa/algerian-cities/graphs/contributors) who have helped improve and enhance the project. - The list of Wilayas and Communes is sourced from [Wilaya-Of-Algeria](https://github.com/bahinapster/Wilaya-Of-Algeria/). Security Reports ---------------- [](#security-reports) If you discover any security vulnerabilities, please report them by emailing the package maintainer at `hadjikouceyla at gmail`. ⭐ Support Us ------------ [](#-support-us) If you find this package helpful, please consider giving it a ⭐ on [GitHub](https://github.com/kossa/algerian-cities) ! Your support encourages us to keep improving the project. Thank you! [![Stargazers repo roster for @kossa/algerian-cities](https://camo.githubusercontent.com/9459230b6031013d503df65b0f3f344d4dcf94a212e20ae09ea30de55052953e/68747470733a2f2f7265706f726f737465722e636f6d2f73746172732f6461726b2f6b6f7373612f616c67657269616e2d636974696573)](https://github.com/kossa/algerian-cities/stargazers) License ------- [](#license) This package is open-sourced software licensed under the [MIT License](https://opensource.org/licenses/MIT). ### Health Score 54 — FairBetter than 97% of packages Maintenance67 Regular maintenance activity Popularity40 Moderate usage in the ecosystem Community20 Small or concentrated contributor base Maturity73 Established project with proven stability Bus Factor2 2 contributors hold 50%+ of commits 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. ### Release Activity Cadence Every ~127 days Recently: every ~57 days Total 15 Last Release 448d ago Major Versions v1.0.4 → v2.0.02020-04-19 v2.1.1 → v3.0.12020-11-02 v3.0.3 → v4.0.02024-10-27 PHP version history (5 changes)v1.0.0PHP ^7.2 v3.0.2PHP ^7.2|^8.0|^8.1 v3.0.3PHP ^8.0|^8.1|^8.2|^8.3|^8.4 v4.0.0PHP ^8.1|^8.2|^8.3 v4.1.2PHP ^8.1 ### Community Maintainers ![](https://www.gravatar.com/avatar/32210c945bbfcd78618d5657a2129cbf196fa3b108e0df8f28a941b5816bc84f?d=identicon)[kossa](/maintainers/kossa) --- Top Contributors [![n4ss1m](https://avatars.githubusercontent.com/u/1750845?v=4)](https://github.com/n4ss1m "n4ss1m (40 commits)")[![kossa](https://avatars.githubusercontent.com/u/1175584?v=4)](https://github.com/kossa "kossa (32 commits)")[![celyes](https://avatars.githubusercontent.com/u/21331907?v=4)](https://github.com/celyes "celyes (23 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (4 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (4 commits)")[![akhedrane](https://avatars.githubusercontent.com/u/297340?v=4)](https://github.com/akhedrane "akhedrane (2 commits)")[![fbenmadani](https://avatars.githubusercontent.com/u/1666626?v=4)](https://github.com/fbenmadani "fbenmadani (1 commits)") --- Tags algeriaarabiccitiescommunegpslaravelwilayalaravelcitiescommuneWilayaAlgeria ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/kossa-algerian-cities/health.svg) ``` [![Health](https://phpackages.com/badges/kossa-algerian-cities/health.svg)](https://phpackages.com/packages/kossa-algerian-cities) ``` ### Alternatives [livewire/volt An elegantly crafted functional API for Laravel Livewire. 4205.3M84](/packages/livewire-volt)[pragmarx/countries-laravel Countries for Laravel 1471.1M2](/packages/pragmarx-countries-laravel)[gehrisandro/tailwind-merge-laravel TailwindMerge for Laravel merges multiple Tailwind CSS classes by automatically resolving conflicts between them 341682.2k18](/packages/gehrisandro-tailwind-merge-laravel)[whitecube/laravel-timezones Store UTC dates in the database and work with custom timezones in the application. 106106.2k](/packages/whitecube-laravel-timezones)[forxer/laravel-gravatar A library providing easy gravatar integration in a Laravel project. 4235.6k](/packages/forxer-laravel-gravatar)[iteks/laravel-enum A comprehensive Laravel package providing enhanced enum functionalities, including attribute handling, select array conversions, and fluent facade interactions for robust enum management in Laravel applications. 2516.7k](/packages/iteks-laravel-enum) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)