README

NepalLocations is a Laravel package providing Nepal’s geographical data — provinces, districts, cities, and their hierarchical relationships. It offers a structured way to access and manipulate this data using Laravel's powerful query builder API.

Features

• Eloquent models: Province, District, City
• Collision free table names with configurable prefixes
• Enum support for CityType
• One-command import with:
  • Full or partial import options
  • Smart update/merge of existing data
  • Selective field overriding
• JSON-driven immutable source data
• Useful relationships:
  • Province → Districts & Cities
  • District → Cities

Installation

Require the package via Composer:

composer require novasemantics/nepal-locations-laravel

You can install the package's assets and configuration file using the following artisan command:

php artisan nepal-locations-laravel:install

• The installation command will publish the package's configuration file to config/nepal-locations-laravel.php.
• It will also publish the migration files to database/migrations/.
• Then you will be asked to run the migrations to create the necessary database tables.
• Finally, you will be prompted to run the import command to populate the database with initial data.

How to Get Updated Data

The package is maintained with the latest geographical data of Nepal. To get the most recent data, you can update the package using Composer:

composer update novasemantics/nepal-locations-laravel

Then you can manually run the import command to refresh the data in your database:

php artisan import:geo-data

Fresh Import option will be provided to overwrite existing data with the latest from the package, if you have been using the data in foreign keys or relationships, you can choose to update only the fields you need without affecting the existing relationships. As the ID's for geo tables are immutable, you can safely update without worrying about breaking changes.

⚙️ Models Overview

Province

The Province model represents Nepal's administrative provinces. It contains information about the province's name, area, population, and its districts.

District

The District model represents the districts within a province. It includes details such as the district's name, area, population, and the province it belongs to.

City

The City model represents cities within a district. It includes the city's name, type (e.g., Metropolitan, Sub-Metropolitan), area, population, and the district it belongs to.

Data Structure

📥 Importing Geo Data

Use the following artisan command:

php artisan import:geo-data

What it does:

• Interactive CLI to:
  • Choose which data types to import (provinces, districts, cities)
  • Perform fresh import or update mode
  • Select specific fields to override on update
  • Confirm before execution

Example:

php artisan import:geo-data

You’ll be prompted with interactive options for a safe and flexible import experience.

💡 Example Usage

Get all districts of Province ID 3

use NovaSemantics\NepalLocations\Models\Province;

$province = Province::find(3);
$districts = $province->districts;

// Or directly get cities of the province
$cities = $province->cities;

Get all cities of a district

use NovaSemantics\NepalLocations\Models\District;

$district = District::find(12);
$cities = $district->cities;

Get all metropolitan cities

use NovaSemantics\NepalLocations\Enums\CityType;
use NovaSemantics\NepalLocations\Models\City;

$cities = City::where('type', CityType::Metropolitan)->get();

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• All Contributors

License

The MIT License (MIT). Please see License File for more information.