PHPackages dyangalih/laravel-regions - 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. [Search & Filtering](/categories/search) 4. / 5. dyangalih/laravel-regions ActiveLibrary[Search & Filtering](/categories/search) dyangalih/laravel-regions ========================= Indonesian region with official 2025 BPS & Kemendagri data v1.1.0(3w ago)53MITPHPPHP ^8.1 Since May 15Pushed 3w agoCompare [ Source](https://github.com/DyanGalih/laravel-regions)[ Packagist](https://packagist.org/packages/dyangalih/laravel-regions)[ Docs](https://github.com/DyanGalih/laravel-regions)[ RSS](/packages/dyangalih-laravel-regions/feed)WikiDiscussions main Synced 1w ago READMEChangelog (2)Dependencies (8)Versions (4)Used By (0) Laravel Indonesian Region API ============================= [](#laravel-indonesian-region-api) [![Latest Version on Packagist](https://camo.githubusercontent.com/72b69f572e52603055da76a2ff7de49abe54e5f7e7830348ba3ca2788c8b3933/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d76312e312e302d626c75653f7374796c653d666c61742d737175617265)](https://packagist.org/packages/dyangalih/laravel-regions)[![Laravel Version](https://camo.githubusercontent.com/57650d525a6dc44226b5c33a6c7e26198fc7b9bbc3df4620f90221343002b8fe/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c61726176656c2d31302532463131253246313225324631332d696e666f726d6174696f6e616c3f7374796c653d666c61742d737175617265266c6f676f3d6c61726176656c)](https://laravel.com)[![License](https://camo.githubusercontent.com/c090e080484e2a2bc766446291d04437db823929042bf614b26a1643660ddf6f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e3f7374796c653d666c61742d737175617265)](https://packagist.org/packages/dyangalih/laravel-regions)[![Status](https://camo.githubusercontent.com/370796da7ff52bf6006ef99f47d732f7c380297dc13db35b091470c0bee9ec41/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7374617475732d737461626c652d737563636573733f7374796c653d666c61742d737175617265)](https://github.com/DyanGalih/laravel-regions) A high-performance, governed Laravel package for Indonesian regional data (Provinces, Regencies, Districts, and Villages) using 2025 BPS & Kemendagri data. Featuring a deep hierarchical REST API, global search capabilities, and optimized data ingestion. Requirements ------------ [](#requirements) - **PHP**: `^8.1` (to match composer.json) - **Laravel**: `10.x`, `11.x`, `12.x`, or `13.x` Features -------- [](#features) - **Full Indonesian Hierarchy**: Provinces → Regencies → Districts → Villages. - **Dual-Access API**: Support for both deep hierarchical and flat global endpoints. - **Deep Eager Loading**: Automatically includes full parent hierarchy without N+1 queries. - **High-Performance Seeding**: Chunked data ingestion for high-volume datasets with automatic cache invalidation. - **Intelligent Caching**: Permanent versioned caching for detail lookups with self-healing serialization recovery. - **Zero-Config Auto-Discovery**: Works out of the box with standard Laravel commands. Engineering Standards --------------------- [](#engineering-standards) This package was developed using an advanced AI-assisted engineering workflow to ensure production-grade stability: - **[Spec-Kit](https://github.com/github/spec-kit)**: Orchestrated development from specification to implementation. - **[Memory-Hub](https://github.com/DyanGalih/spec-kit-memory-hub)**, **[Security-Review](https://github.com/DyanGalih/spec-kit-security-review)**, and **[Architecture-Guard](https://github.com/DyanGalih/spec-kit-architecture-guard)** enforced. Installation ------------ [](#installation) ``` composer require dyangalih/laravel-regions ``` Quick Start (Zero-Config) ------------------------- [](#quick-start-zero-config) ``` # 1. Run migrations php artisan migrate # 2. Seed the data php artisan indonesia:seed ``` --- API Documentation ----------------- [](#api-documentation) All routes are prefixed with `/api/region`. ### Hierarchical Endpoints [](#hierarchical-endpoints) Used for drill-down UIs or strictly scoped data retrieval. MethodEndpointDescription`GET``/provinces`List all provinces`GET``/provinces/{id}`Get province details`GET``/provinces/{pId}/regencies`List regencies in a province`GET``/provinces/{pId}/regencies/{rId}`Get regency details`GET``/provinces/{pId}/regencies/{rId}/districts`List districts in a regency`GET``/provinces/{pId}/regencies/{rId}/districts/{dId}/villages`List villages in a district### Global Search & Detail Endpoints [](#global-search--detail-endpoints) Used for global search boxes, autocomplete, or direct ID lookups. MethodEndpointDescription`GET``/regencies`Global search regencies`GET``/regencies/{id}`Get regency detail globally`GET``/districts`Global search districts`GET``/districts/{id}`Get district detail globally`GET``/villages`Global search villages`GET``/villages/{id}`Get village detail globally### Example JSON Response [](#example-json-response) When requesting a village (either globally or hierarchically), you get the full parent context: ``` { "id": 1101010001, "districtId": 1101010, "name": "KEUDE BAKONGAN", "district": { "id": 1101010, "regencyId": 1101, "name": "BAKONGAN", "regency": { "id": 1101, "provinceId": 11, "name": "KABUPATEN ACEH SELATAN", "province": { "id": 11, "name": "ACEH" } } } } ``` --- Programmatic Usage ------------------ [](#programmatic-usage) You can interact with the regional data directly in your PHP code using the Facade or Service. ### Using the Facade [](#using-the-facade) The `Region` facade provides a clean, expressive syntax for data retrieval. ``` use DyanGalih\LaravelRegion\Facades\Region; // Search for a village globally $villages = Region::searchVillages(query: 'Bakongan', limit: 10); // Get a district with its full hierarchy $district = Region::getDistrictById(1101010); // Get regencies for a specific province $regencies = Region::searchRegencies(provinceId: 11); ``` ### Dependency Injection [](#dependency-injection) You can also inject the `RegionService` into your controllers or services. ``` use DyanGalih\LaravelRegion\Services\RegionService; public function __construct( protected RegionService $regionService ) {} public function getMyData() { return $this->regionService->getVillageById(1101010001); } ``` --- Performance & Caching ------------------------- [](#performance--caching) The package implements an **Intelligent Caching** layer designed for static regional data. ### Forever Caching [](#forever-caching) All detail and ID-based lookups (`get*ById`, `get*Detail`) are cached **forever** by default. This ensures near-zero latency for repeated requests. ### Self-Healing Resilience [](#self-healing-resilience) To prevent crashes in unstable serialization environments (e.g., PHP 8.4 drift), the package automatically detects and purges corrupted cache entries (like `__PHP_Incomplete_Class`), re-generating them on the fly. ### Cache Invalidation [](#cache-invalidation) The cache is versioned (`region.v{version}.*`). When you update your regional data, you must increment the version to invalidate all existing cache. **Manual Flush:** ``` use DyanGalih\LaravelRegion\Facades\Region; Region::flushCache(); ``` **Automatic Flush:**The `php artisan indonesia:seed` command automatically triggers a cache flush upon successful completion. --- Contributing ------------ [](#contributing) Please see [CONTRIBUTING](CONTRIBUTING.md) for details. Credits ------- [](#credits) - **[wilayah\_indonesia](https://github.com/SalzBytes/wilayah_indonesia)**: The primary source for the Indonesian regional CSV data (2025 BPS & Kemendagri). - **[Spec-Kit](https://github.com/github/spec-kit)**: The engineering framework used for governed development. License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 41 — FairBetter than 87% of packages Maintenance95 Actively maintained with recent releases Popularity9 Limited adoption so far Community6 Small or concentrated contributor base Maturity44 Maturing project, gaining track record 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 ~1 days Total 2 Last Release 24d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/bccdf01afc153c118b1a7f3ee97e48fd04a8dfdfe9d2f4dabfe406ecf58d402e?d=identicon)[dyan.galih](/maintainers/dyan.galih) --- Top Contributors [![DyanGalih](https://avatars.githubusercontent.com/u/3088531?v=4)](https://github.com/DyanGalih "DyanGalih (27 commits)") --- Tags bpsdistrictshierarchicalindonesiakemendagrilaravellaravel-packageprovincesregenciesregionsrest-apisearchvillagesindonesialaravel-regionsprovincesregenciesdyangalih ### Code Quality TestsPest Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/dyangalih-laravel-regions/health.svg) ``` [![Health](https://phpackages.com/badges/dyangalih-laravel-regions/health.svg)](https://phpackages.com/packages/dyangalih-laravel-regions) ``` ### Alternatives [spatie/laravel-pdf Create PDFs in Laravel apps 1.0k4.3M41](/packages/spatie-laravel-pdf)[danestves/laravel-polar A package to easily integrate your Laravel application with Polar.sh 7918.0k](/packages/danestves-laravel-polar)[rawilk/profile-filament-plugin Profile & MFA starter kit for filament. 3913.7k](/packages/rawilk-profile-filament-plugin)[a2insights/filament-saas Filament Saas for A2Insights 171.5k](/packages/a2insights-filament-saas) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)