README

Package Laravel untuk data wilayah Indonesia terlengkap dan terbaru

Data terbaru 2025 sesuai Kepmendagri No. 300.2.2-2138 Tahun 2025, data daerah-daerah di Indonesia termasuk 38 provinsi, kabupaten/kota, kecamatan, dan desa/kelurahan

✨ Fitur Utama

• ????️ Data Lengkap: 38 Provinsi, 514+ Kabupaten/Kota, 7000+ Kecamatan, 83000+ Desa/Kelurahan
• ???? Multi-Language: Mendukung Bahasa Indonesia (ID) dan English (EN)
• ???? Pencarian Cerdas: Fitur search yang powerful untuk semua level wilayah
• ???? Pagination: Built-in pagination untuk performa optimal
• ???? Relasi Eloquent: Relationship yang lengkap antar model
• ⚙️ Konfigurasi Fleksibel: Customizable table prefix dan pattern
• ???? Easy Setup: Instalasi dan setup yang mudah dengan Artisan command

???? Instalasi

1. Install via Composer

composer require hitech/indonesia-laravel

2. Publish Konfigurasi dan Migration

# Publish semua file php artisan vendor:publish --provider="Hitech\IndonesiaLaravel\Providers\IndonesiaLaravelServiceProvider" # Atau publish secara terpisah php artisan vendor:publish --tag=config php artisan vendor:publish --tag=migrations

3. Jalankan Migration

php artisan migrate

4. Seed Database

php artisan indonesia:seed

⚙️ Konfigurasi

Setelah publish, edit file config/indonesia.php:

return [ // Prefix untuk nama tabel 'table_prefix' => 'indonesia_', // Pattern bahasa: 'ID' untuk Indonesia, 'EN' untuk English 'pattern' => 'ID', // Enable/disable setiap modul 'data_location' => [ 'province' => true, 'city' => true, 'district' => true, 'village' => true, // Filter berdasarkan wilayah induk (opsional) 'only' => [ 'type' => '', // Bisa: province, city, district, villages 'code' => '', // Kode wilayah sesuai tipe di atas bisa lihat kodenya disini (https://kodewilayah.id) ], ], ];

???? Penggunaan

Service Class (Recommended)

use Hitech\IndonesiaLaravel\Services\IndonesiaService; $indonesia = new IndonesiaService(); // Pencarian di semua wilayah $results = $indonesia->search('Jakarta')->all(); // Mendapatkan semua provinsi $provinces = $indonesia->allProvinces(); // Pencarian provinsi dengan pagination $provinces = $indonesia->search('Jawa')->paginateProvinces(10); // Mendapatkan provinsi dengan relasi $province = $indonesia->findProvince(1, ['cities', 'villages']); // Mendapatkan kota berdasarkan provinsi $cities = $indonesia->findCitiesByProvince(1); // Mendapatkan kecamatan berdasarkan kota $districts = $indonesia->findDistrictsByCity(1); // Mendapatkan desa berdasarkan kecamatan $villages = $indonesia->findVillagesByDistrict(1);

Direct Model Usage

use Hitech\IndonesiaLaravel\Models\Province; use Hitech\IndonesiaLaravel\Models\City; use Hitech\IndonesiaLaravel\Models\District; use Hitech\IndonesiaLaravel\Models\Village; // Mendapatkan semua provinsi $provinces = Province::all(); // Pencarian provinsi $provinces = Province::search('Jawa')->get(); // Provinsi dengan kota-kotanya $province = Province::with('cities')->find(1); // Kota dengan kecamatan dan desa $city = City::with('districts.villages')->find(1);

Contoh Relasi

// Mendapatkan provinsi dari sebuah desa $village = Village::with('district.city.province')->find(1); $provinceName = $village->district->city->province->name; // Mendapatkan semua desa dalam sebuah provinsi $province = Province::with('cities.districts.villages')->find(1); foreach ($province->cities as $city) { foreach ($city->districts as $district) { foreach ($district->villages as $village) { echo $village->name; } } }

???? Struktur Database

Tabel yang Dibuat

• indonesia_provinces - Data provinsi
• indonesia_cities - Data kabupaten/kota
• indonesia_districts - Data kecamatan
• indonesia_villages - Data desa/kelurahan

Kolom Dinamis Berdasarkan Pattern

Pattern 'ID' (Bahasa Indonesia):

• kode_provinsi, nama_provinsi
• kode_kabupaten, nama_kabupaten
• kode_kecamatan, nama_kecamatan
• kode_desa, nama_desa

Pattern 'EN' (English):

• province_code, province_name
• city_code, city_name
• district_code, district_name
• village_code, village_name

???? Fitur Pencarian

$indonesia = new IndonesiaService(); // Pencarian di semua level wilayah $results = $indonesia->search('Bandung')->all(); // Pencarian spesifik per level $provinces = $indonesia->search('Jawa')->allProvinces(); $cities = $indonesia->search('Jakarta')->allCities(); $districts = $indonesia->search('Kemang')->allDistricts(); $villages = $indonesia->search('Cipete')->allVillages();

???? Pagination

$indonesia = new IndonesiaService(); // Pagination dengan pencarian $provinces = $indonesia->search('Jawa')->paginateProvinces(15); $cities = $indonesia->search('Jakarta')->paginateCities(20); $districts = $indonesia->paginateDistricts(25); $villages = $indonesia->paginateVillages(30);

????️ Artisan Commands

# Seed database dengan data Indonesia php artisan indonesia:seed # Publish konfigurasi php artisan vendor:publish --tag=config # Publish migrations php artisan vendor:publish --tag=migrations

✅ Menjalankan Test

Package ini menggunakan PHPUnit bersama Orchestra Testbench agar bisa diuji seperti dalam konteks aplikasi Laravel.

Siapkan konfigurasi test di phpunit.xml

<php> <env name="DB_CONNECTION" value="pgsql"/> <env name="DB_HOST" value="localhost"/> <env name="DB_PORT" value="5432"/> <env name="DB_DATABASE" value="indo"/> <env name="DB_USERNAME" value="user"/> <env name="DB_PASSWORD" value="pw"/> </php>

Jalankan test dengan PHPUnit

vendor/bin/phpunit

Atau jika sudah install global PHPUnit:

phpunit

???? Requirements

• PHP ^8.1
• Laravel ^12.19
• Illuminate Support ^12.19
• Illuminate Console ^12.19
• Illuminate Database ^12.19

???? Contributing

Kontribusi sangat diterima! Silakan:

1. Fork repository ini
2. Buat branch fitur baru (git checkout -b feature/amazing-feature)
3. Commit perubahan (git commit -m 'Add amazing feature')
4. Push ke branch (git push origin feature/amazing-feature)
5. Buat Pull Request

???? License

Project ini menggunakan MIT License.

????‍???? Author

dhank77

• Email: d41113512@gmail.com

SyahrulBhudiF

• Github: https://github.com/SyahrulBhudiF

???? Sumber Data

• Wilayah
  • Data wilayah Indonesia 2025 berasal dari Yonatan Yusak Lestari bisa lihat di repo ini yang bersumber langsung dari Kepmendagri 2025.
  • Data wilayah Indonesia sebelumnya (< 2025) berasal dari github/api yang saya sudah lupa untuk cantumkan jika merasa itu data anda dengan senang hati kontak saya di linkedin atau email ataupun buat issue di repo ini.
• Kode Pos
  • Kodepos.sql datanya dari w3appdev bisa lihat di repo ini, dengan sumber utama dari nomor.net.

???? Acknowledgments

• Laravel Community
• Semua kontributor yang telah membantu

Dibuat dengan ❤️ untuk Indonesia

⭐ Star this repo | ???? Report Bug | ???? Request Feature