PHPackages barialay/afghanistan-province-district-village - 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. barialay/afghanistan-province-district-village ActiveLibrary[Utility & Helpers](/categories/utility) barialay/afghanistan-province-district-village ============================================== Afghanistan province district village — a Laravel package for provinces, districts, and villages with GPS coordinates. 1.4.0(yesterday)12↑2900%MITPHPPHP ^7.3|^8.0 Since Jun 9Pushed todayCompare [ Source](https://github.com/barialay/afghanistan-province-district-village)[ Packagist](https://packagist.org/packages/barialay/afghanistan-province-district-village)[ RSS](/packages/barialay-afghanistan-province-district-village/feed)WikiDiscussions main Synced today READMEChangelogDependencies (5)Versions (3)Used By (0) Afghanistan Province District Village ===================================== [](#afghanistan-province-district-village) [![Latest Version on Packagist](https://camo.githubusercontent.com/ca995d47e9ea80cbd308938b8efca22025689fd7cdd0d906d1458ce44ccfe306/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f62617269616c61792f61666768616e697374616e2d70726f76696e63652d64697374726963742d76696c6c6167652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/barialay/afghanistan-province-district-village)[![Total Downloads](https://camo.githubusercontent.com/2ba22b602f17964ffeae22db9dd1ee29bad4b7dfa86905cc5fa36bc4a70f5311/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f62617269616c61792f61666768616e697374616e2d70726f76696e63652d64697374726963742d76696c6c6167652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/barialay/afghanistan-province-district-village)[![License: MIT](https://camo.githubusercontent.com/a7e65aee57b11d28e4caff8b945729a66be0bb663f7f93bd24c5aa65699f148e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d626c75652e7376673f7374796c653d666c61742d737175617265)](https://opensource.org/licenses/MIT)[![PHP Version](https://camo.githubusercontent.com/40f152a18f6fc3e8af64de37d6ebf5df7e15cbdcb6c3f006452540ddcaa51671/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f62617269616c61792f61666768616e697374616e2d70726f76696e63652d64697374726963742d76696c6c6167652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/barialay/afghanistan-province-district-village) A Laravel package for Afghanistan **provinces**, **districts**, and **villages**. This package includes a full **village database** — **8,892 villages** across all **34 provinces**, each with a name, GPS coordinates, and links to its province and district. No database migrations or seeding required; villages ship as JSON and load at runtime. Built by [Barialay](https://github.com/Barialay). What's included --------------- [](#whats-included) DataCountDetailsProvinces34English, Dari, and Pashto names + GPS coordinatesDistricts400+Linked to provinces, multilingual names**Villages****8,892****Name, GPS, province ID, district ID** — all provincesFeatures -------- [](#features) - **List all 8,892 villages** or filter by province / district - **Province → district → village** cascade — ideal for 3-level dropdowns - Villages include **latitude**, **longitude**, and area data when available - Find a village by **ID** or **name** - Multilingual province and district names (English, Dari, Pashto) - Laravel auto-discovery (Service Provider + `Afghanistan` Facade) - Publishable config and JSON data files - Typed objects: `Province`, `District`, `Village` Requirements ------------ [](#requirements) PHPLaravel7.3 – 7.48.x8.0+8.x, 9.x, 10.x, 11.x, 12.x- **PHP:** `^7.3` or `^8.0` - **Laravel:** `^8.0` through `^12.0` > PHP 7.3/7.4 only works with **Laravel 8**. Laravel 9 and above require PHP 8.0+. Installation ------------ [](#installation) ``` composer require barialay/afghanistan-province-district-village:^1.4 ``` The package auto-registers. No manual setup needed. ### If Composer blocks installation (security advisories) [](#if-composer-blocks-installation-security-advisories) If you see errors about `security advisories` on `laravel/framework`, update your Laravel app first — this is not a package issue: ``` composer update composer require barialay/afghanistan-province-district-village:^1.4 ``` ### Publish config (optional) [](#publish-config-optional) ``` php artisan vendor:publish --tag=afghanistan-province-district-village-config ``` ### Publish data files (optional) [](#publish-data-files-optional) ``` php artisan vendor:publish --tag=afghanistan-province-district-village-data ``` Villages -------- [](#villages) The package **lists villages**. Use any of the methods below depending on your UI or API. ### List all villages [](#list-all-villages) ``` use Barialay\AfghanistanProvinceDistrictVillage\Facades\Afghanistan; $allVillages = Afghanistan::villages(); // Collection of 8,892 Village objects $total = Afghanistan::countVillages(); // 8892 ``` ### List villages by province [](#list-villages-by-province) ``` $kabul = Afghanistan::provinceByName('Kabul'); $villages = Afghanistan::villagesByProvince($kabul->id); // Every village in Kabul province ``` ### List villages by district (recommended for dropdowns) [](#list-villages-by-district-recommended-for-dropdowns) ``` $kabul = Afghanistan::provinceByName('Kabul'); $districts = Afghanistan::districts($kabul->id); $kabulDistrict = $districts->firstWhere('name', 'Kabul'); $villages = Afghanistan::villagesByDistrict($kabulDistrict->id); // Every village in Kabul district — works for all 34 provinces ``` ### List villages by province + district name [](#list-villages-by-province--district-name) ``` $villages = Afghanistan::villages('Kabul', 'Kabul'); $villages = Afghanistan::villages('Herat', 'Herat'); $villages = Afghanistan::villages('Badakhshan', 'Wakhan'); ``` ### Find a single village [](#find-a-single-village) ``` $village = Afghanistan::village(4183); $village = Afghanistan::villageByName('Ab Bala'); echo $village->name; // Ab Bala echo $village->province; // Bamyan echo $village->district; // ... echo $village->latitude; echo $village->longitude; ``` ### Verify villages in Tinker [](#verify-villages-in-tinker) ``` php artisan tinker ``` ``` Afghanistan::countVillages(); // 8892 Afghanistan::villages()->count(); // 8892 // Villages exist in every province Afghanistan::villagesByProvince(Afghanistan::provinceByName('Herat')->id)->count(); Afghanistan::villagesByProvince(Afghanistan::provinceByName('Ghazni')->id)->count(); ``` Province → District → Village cascade ------------------------------------- [](#province--district--village-cascade) Full 3-level flow for forms and APIs: ``` use Barialay\AfghanistanProvinceDistrictVillage\Facades\Afghanistan; // 1. List provinces $provinces = Afghanistan::provinces(); // 2. User picks a province → list its districts $herat = Afghanistan::provinceByName('Herat'); $districts = Afghanistan::districts($herat->id); // 3. User picks a district → list its villages $heratDistrict = $districts->firstWhere('name', 'Herat'); $villages = Afghanistan::villagesByDistrict($heratDistrict->id); foreach ($villages as $village) { echo $village->id; echo $village->name; echo $village->latitude; echo $village->longitude; } ``` ### Blade — 3 dropdowns (province, district, village) [](#blade--3-dropdowns-province-district-village) ``` {{-- Province --}} @foreach (Afghanistan::provinces() as $province) {{ $province->nameFor('fa') }} @endforeach {{-- District (load via AJAX when province changes) --}} {{-- Village (load via AJAX when district changes) --}} ``` Load districts and villages from your controller: ``` // GET /districts/{provinceId} return Afghanistan::districts($provinceId)->map->toArray(); // GET /villages/{districtId} return Afghanistan::villagesByDistrict($districtId)->map->toArray(); ``` ### API routes example [](#api-routes-example) ``` use Barialay\AfghanistanProvinceDistrictVillage\Facades\Afghanistan; use Illuminate\Http\Request; // GET /api/provinces public function provinces() { return Afghanistan::provinces()->map->toArray(); } // GET /api/districts/{provinceId} public function districts(int $provinceId) { return Afghanistan::districts($provinceId)->map->toArray(); } // GET /api/villages?district_id=129 public function villages(Request $request) { if ($request->filled('district_id')) { return Afghanistan::villagesByDistrict((int) $request->query('district_id'))->map->toArray(); } if ($request->filled('province_id')) { return Afghanistan::villagesByProvince((int) $request->query('province_id'))->map->toArray(); } return Afghanistan::villages()->map->toArray(); } ``` API Reference ------------- [](#api-reference) ### Facade [](#facade) ``` use Barialay\AfghanistanProvinceDistrictVillage\Facades\Afghanistan; // Provinces Afghanistan::provinces(); Afghanistan::province(32); Afghanistan::provinceByName('Kabul'); Afghanistan::provinceByName('کابل'); // Districts Afghanistan::districts(); Afghanistan::districts($provinceId); // Villages — list, filter, find Afghanistan::villages(); // all 8,892 villages Afghanistan::villagesByProvince($provinceId); // villages in one province Afghanistan::villagesByDistrict($districtId); // villages in one district Afghanistan::villages('Badakhshan', 'Wakhan'); // by province + district name Afghanistan::village(4183); // by ID Afghanistan::villageByName('Ab Bala'); // by name // Counts Afghanistan::countProvinces(); // 34 Afghanistan::countDistricts(); Afghanistan::countVillages(); // 8892 ``` ### Dependency injection [](#dependency-injection) ``` use Barialay\AfghanistanProvinceDistrictVillage\Afghanistan; class LocationController { protected $afghanistan; public function __construct(Afghanistan $afghanistan) { $this->afghanistan = $afghanistan; } public function villagesByDistrict(int $districtId) { return $this->afghanistan ->villagesByDistrict($districtId) ->map->toArray(); } } ``` Configuration ------------- [](#configuration) ``` // config/afghanistan-province-district-village.php return [ 'villages_file' => resource_path('afghanistan-province-district-village/villages.json'), 'provinces_file' => resource_path('afghanistan-province-district-village/provinces-and-districts.json'), 'default_locale' => 'en', // en, fa, pa ]; ``` Data Structure -------------- [](#data-structure) ### Village [](#village) Each of the **8,892 villages** has: FieldTypeDescription`id`intUnique village ID`name`stringVillage name`province`stringProvince name`district`stringDistrict name`province_id`intLinked province ID`district_id`intLinked district ID`latitude`floatGPS latitude`longitude`floatGPS longitude`area_square_meters`floatArea in m² (when available)`hectares`floatArea in hectares### Province / District [](#province--district) FieldTypeDescription`id`intUnique ID`name`stringEnglish name`name_fa`stringDari name`name_pa`stringPashto name`latitude`floatGPS latitude`longitude`floatGPS longitudeTesting ------- [](#testing) ``` composer test ``` Data Disclaimer --------------- [](#data-disclaimer) Geographic data is compiled from public sources. Some village entries may be incomplete or inaccurate. Always verify critical location data independently. Contributing ------------ [](#contributing) See [CONTRIBUTING.md](CONTRIBUTING.md). Contributions are welcome via Pull Request on [GitHub](https://github.com/Barialay/afghanistan-province-district-village). License ------- [](#license) This package is open-source software licensed under the [MIT License](LICENSE). Copyright (c) 2026 [Barialay Rahimi](https://github.com/Barialay). ### Health Score 39 — LowBetter than 84% of packages Maintenance100 Actively maintained with recent releases Popularity5 Limited adoption so far Community6 Small or concentrated contributor base Maturity39 Early-stage or recently created project Bus Factor1 Top contributor holds 100% 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. ### Release Activity Cadence Every ~0 days Total 2 Last Release 1d ago PHP version history (2 changes)1.0.0PHP ^8.2 1.4.0PHP ^7.3|^8.0 ### Community Maintainers ![](https://www.gravatar.com/avatar/61482ce33005367ae86d5a3d84c55ddf3ec9519517e201d414cd9bf41181c503?d=identicon)[barialay](/maintainers/barialay) --- Top Contributors [![barialay](https://avatars.githubusercontent.com/u/57029478?v=4)](https://github.com/barialay "barialay (8 commits)") --- Tags laravellaravel-packagegpscoordinatesprovincevillagedistrictafghanistandariafghanistan-province-district-villageafghanistan provinceafghanistan districtafghanistan villagepashto ### Code Quality TestsPHPUnit Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/barialay-afghanistan-province-district-village/health.svg) ``` [![Health](https://phpackages.com/badges/barialay-afghanistan-province-district-village/health.svg)](https://phpackages.com/packages/barialay-afghanistan-province-district-village) ``` ### Alternatives [psalm/plugin-laravel Psalm plugin for Laravel 3325.1M337](/packages/psalm-plugin-laravel)[laravel/ai The official AI SDK for Laravel. 9782.1M153](/packages/laravel-ai)[moonshine/moonshine Laravel administration panel 1.3k239.9k72](/packages/moonshine-moonshine)[linkxtr/laravel-qrcode A clean, modern, and easy-to-use QR code generator for Laravel 3614.9k](/packages/linkxtr-laravel-qrcode)[tomshaw/electricgrid A feature-rich Livewire package designed for projects that require dynamic, interactive data tables. 119.2k](/packages/tomshaw-electricgrid) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)