Nepali Address for Laravel

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.

Contents

• 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:

1. Load provinces with getProvinces().
2. When a province is selected, load districts with getDistricts($provinceId).
3. When a district is selected, load local bodies with getLocalBodies($districtId).
4. 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.