turahe / master-data
Package Laravel yang berisi data Provinsi, Kabupaten/Kota, Kecamatan, dan Keluarahan/Desa di seluruh Master.
v1.1.1
2025-07-19 18:44 UTC
Requires
- php: ^8.2
- ext-json: *
- laravel/framework: ^10.0|^11.0|^12.0
Requires (Dev)
- doctrine/dbal: ^4.1
- laravel/pint: ^1.17
- laravel/scout: ^10.11
- orchestra/testbench: ^8.0|^9.0|^10.0
- phpstan/phpstan: ^1.10
- spatie/eloquent-sortable: ^4.4
- spatie/geocoder: ^3.10
Suggests
- spatie/geocoder: Synchronize latitude longitude data directly using Google's Geocoding Service
README
A comprehensive Laravel package that provides master data for countries, provinces, cities, districts, villages, banks, currencies, and languages. Perfect for applications requiring geographical data, banking information, and internationalization support.
๐ Table of Contents
- Features
- Requirements
- Installation
- Configuration
- Usage
- Data Overview
- API Reference
- Testing
- Contributing
- License
โจ Features
- ๐ Geographical Data: Complete hierarchy of countries, provinces, cities, districts, and villages
- ๐ฆ Banking Information: Indonesian banks with codes, names, and company details
- ๐ฑ Currency Support: Global currencies with codes and symbols
- ๐ Language Support: International languages with ISO codes
- ๐ผ๏ธ Visual Assets: Country flags and city images included
- ๐ Easy Querying: Eloquent models with relationships and scopes
- โก Performance: Optimized database structure and caching
- ๐งช Comprehensive Testing: Full test coverage across multiple PHP/Laravel versions
๐ Requirements
- PHP: 8.2, 8.3, 8.4
- Laravel: 10.x, 11.x, 12.x
- Database: MySQL, PostgreSQL, SQLite (for testing)
๐ Installation
1. Install via Composer
composer require turahe/master-data
2. Publish Assets and Migrations
php artisan vendor:publish --provider="Turahe\Master\MasterServiceProvider" --tag=assets
3. Run Migrations
php artisan migrate
4. Seed the Database (Optional)
php artisan master:seed
โ๏ธ Configuration
The package configuration is published to config/master.php
. You can customize table names and model classes:
return [ 'tables' => [ 'countries' => 'tm_countries', 'provinces' => 'tm_provinces', 'cities' => 'tm_cities', 'districts' => 'tm_districts', 'villages' => 'tm_villages', 'banks' => 'tm_banks', 'currencies' => 'tm_currencies', 'languages' => 'tm_languages', ], 'models' => [ 'country' => \Turahe\Master\Models\Country::class, 'province' => \Turahe\Master\Models\Province::class, 'city' => \Turahe\Master\Models\City::class, 'district' => \Turahe\Master\Models\District::class, 'village' => \Turahe\Master\Models\Village::class, ], ];
๐ก Usage
Using Eloquent Models
use Turahe\Master\Models\Country; use Turahe\Master\Models\Province; use Turahe\Master\Models\City; use Turahe\Master\Models\Bank; use Turahe\Master\Models\Currency; // Get all countries $countries = Country::all(); // Get Indonesia $indonesia = Country::where('name', 'Indonesia')->first(); // Get provinces in Indonesia $provinces = $indonesia->provinces; // Get cities in a specific province $jakarta = Province::where('name', 'DKI Jakarta')->first(); $cities = $jakarta->cities; // Get banks $banks = Bank::all(); // Get currencies $currencies = Currency::all();
Using the Facade
use Turahe\Master\Master; // Access models through facade $countries = Master::country()->all(); $provinces = Master::province()->all(); $cities = Master::city()->all(); $banks = Master::bank()->all();
Relationships
// Country -> Provinces $country = Country::find(1); $provinces = $country->provinces; // Province -> Cities $province = Province::find(1); $cities = $province->cities; // City -> Districts $city = City::find(1); $districts = $city->districts; // District -> Villages $district = District::find(1); $villages = $district->villages;
Search and Filter
// Search cities by name $cities = City::where('name', 'like', '%Jakarta%')->get(); // Get cities by province $cities = City::where('province_id', $provinceId)->get(); // Get banks by code $bank = Bank::where('code', '008')->first(); // Bank Mandiri
๐ Data Overview
This package provides comprehensive master data:
Data Type | Count | Description |
---|---|---|
Countries | 266 | Global countries with ISO codes |
Provinces | 4,526 | Administrative divisions worldwide |
Cities | 7,376 | Cities and municipalities |
Districts | 81,153 | Districts and sub-districts |
Villages | 1,570 | Villages and neighborhoods |
Banks | 256 | Indonesian banks with codes |
Currencies | 423 | Global currencies with symbols |
Languages | 266 | International languages with ISO codes |
Flags | 1,570 | Country flag images |
City Images | 7,376 | City landmark images |
๐ง API Reference
Models
Country
Country::all() // Get all countries Country::find($id) // Find by ID Country::where('name', $name) // Find by name $country->provinces // Get related provinces
Province
Province::all() // Get all provinces Province::find($id) // Find by ID Province::where('country_id', $id) // Get by country $province->cities // Get related cities $province->country // Get parent country
City
City::all() // Get all cities City::find($id) // Find by ID City::where('province_id', $id) // Get by province $city->districts // Get related districts $city->province // Get parent province
Bank
Bank::all() // Get all banks Bank::where('code', $code) // Find by bank code Bank::where('name', $name) // Find by bank name
Currency
Currency::all() // Get all currencies Currency::where('code', $code) // Find by currency code Currency::where('name', $name) // Find by currency name
Commands
# Seed all master data php artisan master:seed # Sync coordinates (requires spatie/geocoder) php artisan master:sync-coordinates
๐งช Testing
This package is thoroughly tested against:
- PHP: 8.2, 8.3, 8.4
- Laravel: 10.x, 11.x, 12.x
Running Tests Locally
# Install dependencies composer install # Run tests vendor/bin/phpunit # Run code quality checks vendor/bin/pint --test vendor/bin/phpstan analyse src tests --level=8
Test Matrix
The CI/CD pipeline excludes incompatible combinations:
- Laravel 12.x requires PHP 8.3+
- Laravel 10.x doesn't support PHP 8.4
๐ค Contributing
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature
) - Commit your changes (
git commit -m 'Add some amazing feature'
) - Push to the branch (
git push origin feature/amazing-feature
) - Open a Pull Request
Development Setup
# Clone the repository git clone https://github.com/turahe/master-data.git # Install dependencies composer install # Run tests vendor/bin/phpunit # Check code style vendor/bin/pint
๐ License
This package is open-sourced software licensed under the MIT license.
๐ Acknowledgments
- Data sources for geographical information
- Laravel community for the excellent framework
- Contributors and maintainers
Made with โค๏ธ by Nur Wachid