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.4, 8.5
Laravel: 12.x, 13.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.4, 8.5
Laravel: 12.x, 13.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

Testing with MySQL and PostgreSQL

The Docker test image includes PHP and the PDO drivers for SQLite, MySQL, and PostgreSQL. Use the Makefile targets to build the image and run tests:

make test          # SQLite (in memory)
make test-mysql
make test-postgres
make test-all      # all three databases
make pint          # format PHP files using Laravel Pint in Docker
make down          # stop the database services
make test PHP_VERSION=8.5  # use PHP 8.5 instead of the default 8.4

To run tests using the host PHP installation instead, start the required service and set the connection variables. The host PHP CLI must have the matching PDO extension enabled:

docker compose up -d --wait mysql
DB_CONNECTION=mysql DB_HOST=127.0.0.1 DB_PORT=3306 DB_DATABASE=master_data_test DB_USERNAME=master DB_PASSWORD=secret vendor/bin/phpunit

docker compose up -d --wait postgres
DB_CONNECTION=pgsql DB_HOST=127.0.0.1 DB_PORT=5432 DB_DATABASE=master_data_test DB_USERNAME=master DB_PASSWORD=secret vendor/bin/phpunit

The test case uses SQLite in memory by default. The MySQL and PostgreSQL services use the test-only credentials shown above.

Test Matrix

The CI/CD pipeline excludes incompatible combinations:

Laravel 10.x is excluded because it does not support PHP 8.4 or 8.5

🤝 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

turahe / master-data

Package info

Security

Statistics