README

Laravel helpers and bundled data for Nepal's provinces, districts, local bodies, local-body types, and city-wise postal codes. It also includes a validation rule that verifies a postal code against the bundled postal-code dataset.

Requirements
Installation
Configuration
Quick start
Address data API
Postal-code validation
Building dependent address fields
Service container usage
Local package development
Data coverage and limitations

Requirements

PHP 8.1 or later
Laravel 10, 11, 12, or 13

Installation

Install with Composer:

composer require khanaldpk/nepali-address

Laravel package discovery registers the service provider and NepaliAddress facade automatically. If your application has package discovery disabled, add the provider manually to config/app.php:

'providers' => [
    Khanaldpk\NepaliAddress\NepaliAddressServiceProvider::class,
],

Clear cached configuration after installation when appropriate:

php artisan optimize:clear

Configuration

Publish the package configuration file:

php artisan vendor:publish --tag=nepali-address-config

This creates config/nepali-address.php:

return [
    'lang' => env('NEPALI_ADDRESS_LANG', 'en'),
];

Language

Set NEPALI_ADDRESS_LANG in .env to control the value returned in each record's name field:

# English names (default)
NEPALI_ADDRESS_LANG=en

# Nepali / Devanagari names
NEPALI_ADDRESS_LANG=ne

Source records include name and nepali_name. When lang=ne, the returned name value is replaced with its corresponding nepali_name value.

After changing .env in a production or config-cached application, run:

php artisan config:clear

Quick start

use Khanaldpk\NepaliAddress\Facades\NepaliAddress;

$provinces = NepaliAddress::getProvinces();
$districts = NepaliAddress::getDistricts(provinceId: 3);
$localBodies = NepaliAddress::getLocalBodies(districtId: 2);

Use the facade in controllers, jobs, commands, Blade views, and any other Laravel code:

namespace App\Http\Controllers;

use Khanaldpk\NepaliAddress\Facades\NepaliAddress;

class AddressController extends Controller
{
    public function index()
    {
        return response()->json([
            'provinces' => NepaliAddress::getProvinces(),
            'districts' => NepaliAddress::getDistricts(),
        ]);
    }
}

Address data API

Import the facade once:

use Khanaldpk\NepaliAddress\Facades\NepaliAddress;

Method	Arguments	Returns
`getProvinces()`	None	All seven provinces.
`getDistricts(?int $provinceId = null)`	Optional `province_id`	All districts, or only districts in one province.
`getLocalBodies(?int $districtId = null)`	Optional `district_id`	All local bodies, or only bodies in one district.
`getLocalBodyTypes()`	None	Metropolitan, sub-metropolitan, municipality, and rural municipality types.
`getPostalCodes()`	None	The complete city-wise postal-code dataset in its source hierarchy.

Provinces

$provinces = NepaliAddress::getProvinces();

// Example record
// [
//     'province_id' => 3,
//     'name' => 'Bagmati Pradesh',
//     'nepali_name' => 'बागमती प्रदेश',
// ]

Districts

// Every district
$districts = NepaliAddress::getDistricts();

// Districts in province ID 3
$bagmatiDistricts = NepaliAddress::getDistricts(3);

Each district includes district_id, province_id, name, and nepali_name.

Local bodies

// Every local body
$localBodies = NepaliAddress::getLocalBodies();

// Local bodies in district ID 2
$chitwanLocalBodies = NepaliAddress::getLocalBodies(2);

Each local body includes municipality_id, district_id, local_level_type_id, name, and nepali_name.

Local-body types

$types = NepaliAddress::getLocalBodyTypes();

Each type includes local_level_type_id, name, and nepali_name. Match local_level_type_id on a local body with this list to display its type.

City-wise postal codes

$postalCodes = NepaliAddress::getPostalCodes();

Postal codes are supplied as the bundled source hierarchy: province → districts → cities. A city record contains city and post_code keys. This preserves the official grouping data for building dropdowns, search, or API responses.

Postal-code validation

NepalPostalCode validates that the supplied value appears in the bundled city-wise postal-code data. It does not merely check whether a value has five digits.

use Khanaldpk\NepaliAddress\Rules\NepalPostalCode;

$request->validate([
    'postal_code' => ['required', new NepalPostalCode()],
]);

Form Request example

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;
use Khanaldpk\NepaliAddress\Rules\NepalPostalCode;

class StoreAddressRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'province_id' => ['required', 'integer'],
            'district_id' => ['required', 'integer'],
            'local_body_id' => ['required', 'integer'],
            'postal_code' => ['required', new NepalPostalCode()],
        ];
    }
}

Validator example

use Illuminate\Support\Facades\Validator;
use Khanaldpk\NepaliAddress\Rules\NepalPostalCode;

$validator = Validator::make(
    ['postal_code' => '44600'],
    ['postal_code' => [new NepalPostalCode()]],
);

if ($validator->fails()) {
    $errors = $validator->errors();
}

Building dependent address fields

For province → district → local-body selectors:

Load provinces with getProvinces().
When a province is selected, load districts with getDistricts($provinceId).
When a district is selected, load local bodies with getLocalBodies($districtId).
Optionally match local_level_type_id to getLocalBodyTypes() to show the local-body type.

Example JSON endpoint:

use Illuminate\Support\Facades\Route;
use Khanaldpk\NepaliAddress\Facades\NepaliAddress;

Route::get('/api/nepali-address/districts/{provinceId}', function (int $provinceId) {
    return NepaliAddress::getDistricts($provinceId);
});

Route::get('/api/nepali-address/local-bodies/{districtId}', function (int $districtId) {
    return NepaliAddress::getLocalBodies($districtId);
});

Service container usage

The package is bound as both its class name and nepali-address. Dependency injection is useful when you prefer not to use facades:

use Khanaldpk\NepaliAddress\NepaliAddress;

class AddressController extends Controller
{
    public function __construct(private NepaliAddress $nepaliAddress)
    {
    }

    public function districts(int $provinceId)
    {
        return $this->nepaliAddress->getDistricts($provinceId);
    }
}

Local package development

To test a local checkout inside another Laravel application, add a path repository to that application's composer.json:

"repositories": [
    {
        "type": "path",
        "url": "D:/laravel-nepal-address",
        "options": {
            "symlink": true
        }
    }
]

Then install the development branch from the Laravel application directory:

composer require khanaldpk/nepali-address:@dev --with-all-dependencies
php artisan optimize:clear

With symlink: true, edits to this package are reflected in the Laravel application immediately. Run composer dump-autoload in the Laravel application after adding new classes.

Data coverage and limitations

The package bundles province, district, local-body, local-body-type, and city-wise postal-code datasets.
It does not include ward-level data or a getWards() method.
The package returns IDs and data as supplied by the bundled JSON files. Validate relationships in your own application when saving an address, such as confirming that a selected district belongs to the selected province.
Postal-code validation checks exact values present in the bundled dataset. Update the package data when authoritative postal-code information changes.

License

This package is released under the MIT License.

khanaldpk / nepali-address

Maintainers

Package info

Statistics

Security