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

README

Total Downloads Version License Tests Code Quality

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

  • ๐ŸŒ 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

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. 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