README

Package Laravel untuk data wilayah administratif Indonesia (Provinsi, Kabupaten/Kota, Kecamatan, Desa) lengkap dengan Kodepos. Super cepat, ringan, dan tidak membebani database.

Keunggulan Utama

Zero Query (Nanodetik): Menggunakan sistem Caching Array murni di RAM, bebas dari overhead Eloquent Model. Setelah cache terbentuk, pemanggilan data terjadi dalam hitungan nanodetik.
Dotless Code: Kode wilayah disimpan tanpa titik (contoh: 1101012001), memaksimalkan performa indexing database dan kecepatan pemotongan string (substr) di PHP.
Dynamic Table Prefix: Tabel bisa diawali indonesia_, ref_, atau bebas sesuai konfigurasi .env tanpa merusak relasi.
Data Lengkap: Sudah termasuk data lebih dari 80.000 Desa/Kelurahan dan Kodepos seluruh Indonesia.
Custom Artisan Command: Dilengkapi perintah khusus untuk seeding data secara instan.

Cocok Digunakan Untuk:

Package ini dirancang khusus untuk performa tinggi dan pengambilan data cepat. Sangat cocok digunakan untuk:

Form Alamat Bertingkat: Dropdown / Select2 bertingkat (Provinsi -> Kota -> Kecamatan -> Desa) yang merespons sangat cepat.
Autocomplete / Pencarian Kodepos: Fitur pencarian desa atau kodepos dengan response time cepat karena menggunakan Cache Array di RAM.
Menampilkan Detail Alamat: Mengubah kode desa (contoh: 1101012001) menjadi alamat lengkap (Provinsi s/d Kodepos) tanpa melakukan query JOIN ke database.
Microservice / API: Aplikasi yang membutuhkan response JSON ringan tanpa adanya overhead dari Eloquent Model.

Filosofi: Data Lengkap Tanpa Memaksa ORM (Model-Agnostic)

Package ini sengaja tidak menyertakan file Eloquent Model. Kami hanya menyediakan struktur tabel (Migrations) dan data lengkapnya (Seeders).

Kenapa ini menguntungkan?

Nol Konflik: Tidak ada pemaksaan namespace Model (seperti Hifzi\WilayahIndonesia\Models\Village).
Bebas Memilih: Anda bebas membuat Model sendiri di folder app/Models/ aplikasi Anda sesuai arsitektur bisnis Anda.
Zero Overhead: Untuk kebutuhan Form dan Autocomplete, gunakan Facade IndReg yang menggunakan Cache Array murni.
Fleksibel untuk ORM: Jika Anda butuh fitur relasi Eloquent (belongsTo, hasMany), cukup buat Model di aplikasi Anda yang mengarah ke tabel prefix yang Anda gunakan.

Contoh Membuat Model Sendiri di Aplikasi Anda:

Jika Anda butuh relasi ORM, buat Model di aplikasi Laravel Anda seperti ini:

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Village extends Model
{
    // Sesuaikan prefix tabel dengan config Anda
    protected $table = 'indonesia_villages';
    protected $primaryKey = 'code';
    public $incrementing = false;
    protected $keyType = 'string';
    
    public function district()
    {
        return $this->belongsTo(District::class, 'district_code', 'code');
    }
}

Instalasi

Tambahkan package ke proyek Laravel Anda via Composer:
```
composer require hifzi/wilayah-indonesia
```

Publish Config & Migration:

php artisan vendor:publish --tag="wilayah-indonesia-config"
php artisan vendor:publish --tag="wilayah-indonesia-migrations"

Jalankan Migration:
```
php artisan migrate
```

Jalankan Seeder Data Wilayah:

php artisan hifzi:wilayah-indonesia:seed

(Opsional) Jika Anda ingin memasukkannya ke auto-seeder bawaan Laravel, tambahkan ini di database/seeders/DatabaseSeeder.php aplikasi Anda:

use Hifzi\WilayahIndonesia\Database\Seeders\WilayahIndonesiaSeeder as IndonesiaSeeder;

public function run(): void
{
    $this->call([
        IndonesiaSeeder::class,
    ]);
}

Konfigurasi (Opsional)

Anda bisa mengubah pengaturan di file config/wilayah-indonesia.php atau lewat file .env:

WILAYAH_TABLE_PREFIX=indonesia_   # Prefix tabel di database
WILAYAH_CACHE_ENABLED=true        # Aktifkan/Nonaktifkan cache
WILAYAH_CACHE_TTL=2592000         # Waktu cache dalam detik (30 hari)
WILAYAH_CACHE_STORE=redis         # Driver cache (null = ikut default Laravel)
WILAYAH_CACHE_PREFIX=wilayah:     # Prefix key di cache store

Penggunaan

Anda bisa menggunakan Facade IndReg di Controller Anda. (Anda juga bebas mengubah namanya menggunakan use ... as Wilayah; jika diinginkan).

1. Form Alamat Bertingkat (Select2 / Dropdown)

Untuk kebutuhan form alamat bertingkat (Provinsi -> Kota -> Kecamatan -> Desa). Data di-cache per level.

use Hifzi\WilayahIndonesia\Facades\IndReg;

// Ambil Semua Provinsi
$provinces = IndReg::getProvinces();
// Return: [['code' => '11', 'name' => 'Aceh'], ...]

// Ambil Kota berdasarkan Kode Provinsi
$cities = IndReg::getCitiesByProvince('11');
// Return: [['code' => '1101', 'name' => 'Kabupaten Aceh Selatan'], ...]

// Ambil Kecamatan berdasarkan Kode Kota
$districts = IndReg::getDistrictsByCity('1101');
// Return: [['code' => '110101', 'name' => 'Bakongan'], ...]

// Ambil Desa berdasarkan Kode Kecamatan
$villages = IndReg::getVillagesByDistrict('110101');
// Return: [['code' => '1101012001', 'name' => 'Keude Bakongan', 'postal_code' => '23773'], ...]

2. Dapatkan Alamat Lengkap dari Kode Desa

Sesuai untuk menampilkan detail alamat dari tabel companies atau users tanpa query JOIN.

use Hifzi\WilayahIndonesia\Facades\IndReg;

$address = IndReg::getFullAddressByVillageCode('1101012001');

/* Hasil return (Array):
[
    'province' => ['code' => '11', 'name' => 'Aceh'],
    'regency'  => ['code' => '1101', 'name' => 'Kabupaten Aceh Selatan'],
    'district' => ['code' => '110101', 'name' => 'Bakongan'],
    'village'  => ['code' => '1101012001', 'name' => 'Keude Bakongan', 'postal_code' => '23773']
]
*/

3. Pencarian Desa (Autocomplete / Select2)

Mencari desa berdasarkan Nama Desa atau Kode Pos.

Fungsi ini digunakan untuk kebutuhan autocomplete/select2 pada form alamat. Hasil pencarian menampilkan informasi ringkas agar operator dapat memilih desa yang tepat ketika terdapat nama desa yang sama di wilayah berbeda.

use Hifzi\WilayahIndonesia\Facades\IndReg;

// Cari berdasarkan nama desa
$results = IndReg::searchVillages('Bakongan', 10);

// Cari berdasarkan kode pos (5 digit)
$results = IndReg::searchVillages('23773', 10);

/* Hasil return (Array):
[
    [
        'value' => '1103072001',

        'label' => '23773 - Bakongan - Bakongan - Kabupaten Aceh Selatan - Aceh',

        'data' => [
            'code' => '1103072001',
            'name' => 'Bakongan',
            'postal_code' => '23773',
            'district' => 'Bakongan',
            'city' => 'Kabupaten Aceh Selatan',
            'province' => 'Aceh',
        ],
    ],
]
*/

Terimakasih Kepada

Data database wilayah dan kodepos yang digunakan pada package ini merupakan hasil kontribusi open-source dari:

cahyadsn/wilayah

hifzi / wilayah-indonesia

Maintainers

Package info

Statistics

Security