Download the PHP package dev1191/filament-nepali-address without Composer

Filament Nepali Address

A comprehensive, production-ready Nepali address plugin for Filament (v4 and v5).

Provides cascading form selects, smart searchable table columns, cascading table filters, infolist entries, and relationship validation rules for Nepal's administrative divisions: 7 Provinces, 77 Districts, and 753 Local Bodies (Municipalities & Rural Municipalities).

Features

• ⚡ Filament v4 & v5 Ready: Built exclusively for modern Filament schemas and panels.
• 🔗 Cascading Form Selects: Seamless Province ➔ District ➔ Municipality dependent selects with automatic dependent state reset and searchable preloaded options.
• 🗄️ Optimized Storage: Stores clean, normalized integer IDs (province_id, district_id, municipality_id) directly on Eloquent models.
• 🧬 Eloquent Model Trait (HasNepaliAddress): Formatted address accessors (nepali_address, province_name, etc.), multi-address prefix support, and high-performance query scopes.
• 🏗️ Migration Blueprint Macros: One-line schema helpers $table->nepaliAddress() and $table->dropNepaliAddress() with prefix and optional field toggles.
• 🔍 High-Performance Table Search: Automatically translates user text search queries (in both English and Devanagari script) into fast database whereIn(...) ID queries instead of slow text matches.
• 🎯 Cascading Table Filters: Multi-level cascading filter with bidirectional auto-population (selecting a municipality auto-selects its district and province) and human-readable badges.
• 📄 Infolist Entries: Read-only display components for Filament infolists.
• 🛡️ Built-in Relationship Validation: Ensures submitted districts belong to the selected province and municipalities belong to the selected district.
• 🇳🇵 Bilingual Localization: Instant English and Nepali (नेपाली) language support for administrative names, labels, and validation errors.
• 📮 Ward & Postal Code Extensions: Optional ward number input and validated postal code support.

Requirements

• PHP: ^8.2
• Laravel: ^11.0, ^12.0, or ^13.0
• Filament: ^4.0 or ^5.0

Installation

Install the package via Composer:

Optionally publish the configuration file:

Optionally publish the translation files (English and Nepali):

Recommended Database Schema

You can easily add all necessary columns using the built-in nepaliAddress() Blueprint macro in your Laravel migrations:

To drop the address columns in rollback migrations:

Model Setup (User Model)

Add the HasNepaliAddress trait and include the address columns in your Eloquent model (e.g. App\Models\User):

Usage

1. Form Component (NepaliAddressSelects)

Add cascading address selects into your Filament Form:

Multi-Address Support (Custom Prefixes)

If your model stores multiple addresses (e.g., billing_ and shipping_), pass the prefix to make():

This will automatically bind to:

• billing_province_id, billing_district_id, billing_municipality_id
• shipping_province_id, shipping_district_id, shipping_municipality_id

Including Ward & Postal Code

You can also customize the ward input into a select dropdown:

Individual Field Customizations & Requirements

Territory Restrictions (Restricting Specific Provinces / Districts)

If your business or delivery coverage only serves specific regions (e.g. Kathmandu Valley or Bagmati Province only):

Standalone Field Selects

If you prefer building each field individually rather than using the grouped component:

2. Table Column (NepaliAddressColumn)

Display formatted address strings in your Filament Table:

Single-Level Table Columns

How Smart Search Works

When a user searches "Kathmandu" or "काठमाडौं", the column looks up the matching IDs in-memory and transforms the query into indexed integer constraints:

This avoids slow string matching and full-table scans.

3. Table Filter (NepaliAddressFilter)

Add a cascading address filter to your Filament Table:

Single-Level Table Filters

4. Infolist Entry (NepaliAddressEntry)

Display addresses in read-only Filament Infolists:

5. Eloquent Model Trait (HasNepaliAddress)

With the HasNepaliAddress trait added to your model (such as User or Customer), you get instant accessors, formatted address strings, and powerful query scopes:

Dynamic Model Accessors

The trait provides convenient Eloquent attribute accessors that automatically resolve administrative IDs into human-readable names based on the active locale:

Helper Methods & Multi-Address Prefix Support

When your model stores multiple addresses (e.g. billing_ and shipping_), or when you need custom separators or to exclude ward numbers, call the helper methods directly:

Eloquent Query Scopes

Filter records by province, district, local body, ward, or search terms. All query scopes accept an optional $prefix argument for multi-address models:

[!TIP] How whereNepaliAddress() works: It translates your search text into matching local body, district, and province IDs in-memory and queries the database using indexed integer whereIn(...) statements. If no locations match, it safely produces an empty result (1 = 0) without full-table scans.

6. Standalone Address Helper (AddressData)

You can access the static address helper anywhere in your application:

Localization (English & नेपाली)

The package automatically adapts to your application's active locale (app()->getLocale()).

To force a specific language for address names, publish config/nepali-address.php and set:

When set to 'ne', administrative units and labels render natively:

• Province: प्रदेश (e.g., बागमती प्रदेश)
• District: जिल्ला (e.g., काठमाडौं)
• Local Body: स्थानीय तह / पालिका (e.g., काठमाडौं महानगरपालिका)
• Ward: वडा

Data Source & Limitations

This plugin utilizes administrative data from khanaldpk/nepali-address:

• Administrative Divisions: 7 Provinces, 77 Districts, and 753 Local Bodies (Municipalities, Rural Municipalities, Sub-Metropolitan, Metropolitan cities).
• Ward Numbers: Nepal does not maintain official individual boundary IDs for wards in standard national open datasets. Ward numbers vary between 1 and 35+ per municipality. This package supports ward numbers as direct inputs or configurable selects (->withWard()).
• Postal Codes: In Nepal, postal codes correspond to specific post office branches and major towns rather than 1:1 municipality boundaries. This package provides a dedicated NepaliPostalCodeInput with official postal code format validation.

Testing

Run code styling check:

Run static analysis:

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

• Dev Raj Thapa
• khanaldpk/nepali-address for the underlying dataset
• All Contributors

License

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