PHPackages                             zarbinco/laravel-iran-locations - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. zarbinco/laravel-iran-locations

ActiveLibrary[Utility & Helpers](/categories/utility)

zarbinco/laravel-iran-locations
===============================

Iran provinces, cities, neighborhoods, safe sync, and Persian normalization for Laravel.

v0.1.0(3d ago)00MITPHP ^8.2

Since Jul 5Compare

[ Source](https://github.com/zarbinco/laravel-iran-locations)[ Packagist](https://packagist.org/packages/zarbinco/laravel-iran-locations)[ Docs](https://github.com/zarbinco/laravel-iran-locations)[ RSS](/packages/zarbinco-laravel-iran-locations/feed)WikiDiscussions Synced today

READMEChangelog (1)Dependencies (10)Versions (2)Used By (0)

Laravel Iran Locations
======================

[](#laravel-iran-locations)

زبان‌ها: فارسی | [English](README.en.md)

[![Tests](https://github.com/zarbinco/laravel-iran-locations/actions/workflows/tests.yml/badge.svg)](https://github.com/zarbinco/laravel-iran-locations/actions/workflows/tests.yml)[![Latest Version on Packagist](https://camo.githubusercontent.com/64ae5a9fe3217cb9b45062e1a6cda87a81a811ffe8e509ef8131c9d2647824ce/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7a617262696e636f2f6c61726176656c2d6972616e2d6c6f636174696f6e732e7376673f7374796c653d666c61742d737175617265266c6f676f3d7061636b6167697374)](https://packagist.org/packages/zarbinco/laravel-iran-locations)[![Total Downloads](https://camo.githubusercontent.com/b73c62a7bc7fca75ed8037f5e26e21be60ae60157824f46b5dd006e068735c40/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7a617262696e636f2f6c61726176656c2d6972616e2d6c6f636174696f6e732e7376673f7374796c653d666c61742d737175617265266c6f676f3d7061636b6167697374)](https://packagist.org/packages/zarbinco/laravel-iran-locations)[![License](https://camo.githubusercontent.com/74d3baad3e9bf93eb6d91741733198eab38e3131ae475e69e54e0186eaca5887/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7a617262696e636f2f6c61726176656c2d6972616e2d6c6f636174696f6e732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/zarbinco/laravel-iran-locations)

این پکیج داده‌های مکانی ایران را برای پروژه‌های Laravel آماده می‌کند؛ از استان و شهرستان تا بخش، دهستان، شهر، منطقه شهری و محله. اگر فقط لیست آماده برای select، API خواندنی یا اعتبارسنجی می‌خواهید، می‌توانید از `JSON driver` استفاده کنید و هیچ migration یا sync اجرا نکنید. اگر لازم دارید داده‌ها وارد دیتابیس شوند، رکورد سفارشی داشته باشید، admin CRUD فعال کنید یا با رابطه‌های Eloquent کار کنید، `database driver` برای همین سناریو است.

> وضعیت انتشار: پکیج هنوز منتشر نشده و برای فاز beta/pre-release آماده می‌شود. نسخه داده فعلی `0.2.0-dev` است. برای release پایدار، وضعیت منبع داده، مجوز بازنشر و کامل‌بودن داده‌ها باید جداگانه بررسی شود.

قابلیت‌ها
---------

[](#قابلیت‌ها)

- داده‌های آماده برای استان، شهرستان، بخش، دهستان، شهر، مناطق شهری تهران و محله‌های تهران
- دو حالت ذخیره‌سازی: `database` برای sync و رکوردهای سفارشی، و `json` برای استفاده read-only بدون migration
- کدهای عمومی و پایدار مثل `p.01` و `s.01.01.01.01` به‌جای تکیه بر id دیتابیس
- نرمال‌سازی متن فارسی با `zarbinco/laravel-persian-core`
- sync امن دیتابیس با `--dry-run`، حفظ رکوردهای custom و منسوخ‌کردن رکوردهای package که از داده جدید حذف شده‌اند
- مدل‌ها، رابطه‌های Eloquent، query builder و فیلترهای آماده
- API خواندنی اختیاری
- Blade component ساده برای selectها، بدون نیاز به JavaScript
- admin UI اختیاری برای حالت database
- تست‌های کیفیت داده برای شمارش‌ها، checksum، رابطه‌های والد/فرزند، متن فارسی و مراکز استان‌ها

نیازمندی‌ها
-----------

[](#نیازمندی‌ها)

LaravelPHP11PHP 8.2+12PHP 8.2+13PHP 8.3+- `zarbinco/laravel-persian-core` با نسخه `^0.1` یا `^1.0`
- اکستنشن PHP `zip` فقط برای توسعه خود پکیج و release/archive check لازم است؛ مصرف‌کننده پکیج برای runtime معمولی به آن نیاز ندارد.

نصب
---

[](#نصب)

```
composer require zarbinco/laravel-iran-locations
```

پکیج به‌صورت پیش‌فرض با `database driver` بالا می‌آید:

```
IRAN_LOCATIONS_DRIVER=database
```

اگر فقط داده آماده و read-only می‌خواهید، driver را روی `json` بگذارید:

```
IRAN_LOCATIONS_DRIVER=json
```

انتخاب driver
-------------

[](#انتخاب-driver)

### JSON driver؛ بدون migration

[](#json-driver-بدون-migration)

در این حالت پکیج مستقیماً از فایل‌های `data/*.json` داخل package می‌خواند:

```
IRAN_LOCATIONS_DRIVER=json
```

در `JSON driver` این‌ها لازم نیست:

- publish کردن migrationهای پکیج
- اجرای `php artisan migrate` برای جدول‌های پکیج
- اجرای `iran-locations:sync`

این حالت برای dropdown، لیست‌های خواندنی، API options/search، validation list و پروژه‌هایی مناسب است که نمی‌خواهند جدول جدید داشته باشند.

محدودیت‌های مهم JSON mode:

- read-only است.
- sync ندارد.
- admin CRUD ندارد.
- رکورد custom ندارد.
- رابطه‌های دیتابیسی Eloquent ندارد.
- مقدار select و API، `code` است نه database id.
- فیلترها و propهای id مثل `province_id` یا `provinceId` فقط برای `database driver` هستند. در JSON mode باید از `province_code`، `city_code`، `provinceCode`، `cityCode` و propهای code استفاده کنید.

Cache بین requestها در JSON mode به‌صورت پیش‌فرض خاموش است. اگر خودتان فعال کنید، cache key شامل data version و manifest checksum می‌شود:

```
IRAN_LOCATIONS_JSON_CACHE=true
```

### Database driver؛ sync و رکورد سفارشی

[](#database-driver-sync-و-رکورد-سفارشی)

در این حالت داده‌ها وارد جدول‌های برنامه می‌شوند و می‌توانید از مدل‌ها، relationها، admin، رکوردهای custom و queryهای دیتابیسی استفاده کنید:

```
IRAN_LOCATIONS_DRIVER=database
```

مسیر معمول راه‌اندازی:

```
php artisan vendor:publish --tag=iran-locations-config
php artisan vendor:publish --tag=iran-locations-migrations
php artisan migrate
php artisan iran-locations:sync --dry-run
php artisan iran-locations:sync
```

برای بررسی وضعیت:

```
php artisan iran-locations:status
php artisan iran-locations:doctor
```

`sync` جدول‌ها را truncate نمی‌کند. رکوردهای `source = custom` حفظ می‌شوند. رکوردهای package که دیگر در داده فعلی نیستند، به‌صورت پیش‌فرض deprecated می‌شوند و hard delete نمی‌شوند.

نمونه config
------------

[](#نمونه-config)

```
return [
    'storage' => [
        'driver' => env('IRAN_LOCATIONS_DRIVER', 'database'),

        'json' => [
            'cache' => env('IRAN_LOCATIONS_JSON_CACHE', false),
            'cache_key' => 'iran_locations.json_data',
        ],
    ],

    'admin' => [
        'enabled' => false,
        'prefix' => 'admin/iran-locations',
        'middleware' => ['web', 'auth'],
    ],

    'api' => [
        'enabled' => false,
        'prefix' => 'iran-locations/api',
        'middleware' => ['api'],
    ],
];
```

استفاده خواندنی با Facade
-------------------------

[](#استفاده-خواندنی-با-facade)

این API با driver فعلی کار می‌کند؛ یعنی همین کد هم در JSON mode و هم در database mode قابل استفاده است:

```
use Zarbin\IranLocations\Facades\IranLocations;

$provinces = IranLocations::all('provinces');

$tehran = IranLocations::find('city', 's.01.01.01.01');

$cityOptions = IranLocations::options('cities', [
    'province_code' => 'p.01',
]);

$matches = IranLocations::search('تهران');
```

استفاده با read repository
--------------------------

[](#استفاده-با-read-repository)

اگر dependency injection را ترجیح می‌دهید، contract خواندنی پکیج را inject کنید:

```
use Zarbin\IranLocations\Contracts\LocationReadRepository;

final class LocationController
{
    public function __construct(
        private readonly LocationReadRepository $locations,
    ) {}

    public function cities()
    {
        return $this->locations->options('cities', [
            'province_code' => 'p.01',
        ]);
    }
}
```

متدهای اصلی repository:

- `all(string $type, array $filters = [])`
- `find(string $type, string $code)`
- `options(string $type, array $filters = [], ?int $limit = null)`
- `search(string $term, array $types = [], ?int $limit = null)`

استفاده Eloquent در database mode
---------------------------------

[](#استفاده-eloquent-در-database-mode)

مدل‌های Eloquent فقط وقتی معنا دارند که داده‌ها در دیتابیس sync شده باشند:

```
use Zarbin\IranLocations\Models\City;
use Zarbin\IranLocations\Models\CityRegion;
use Zarbin\IranLocations\Models\Neighborhood;
use Zarbin\IranLocations\Models\Province;

$province = Province::query()->byCode('p.01')->first();

$cities = City::query()
    ->forProvince($province)
    ->active()
    ->ordered()
    ->get();

$regions = CityRegion::query()
    ->forCityCode('s.01.01.01.01')
    ->orderedByNumber()
    ->get();

$neighborhoods = Neighborhood::query()
    ->forRegionCode('r.01.01.01.01.05')
    ->ordered()
    ->get();
```

Blade componentها
-----------------

[](#blade-componentها)

Componentها زیر namespace `iran-locations` ثبت می‌شوند. مقدار optionها `code` است:

```

```

Propهای code مثل `province-code` و `city-code` در هر دو driver کار می‌کنند. Propهای id مثل `province-id` فقط برای database mode هستند و در JSON mode نباید برای گرفتن فرزندها استفاده شوند.

API خواندنی
-----------

[](#api-خواندنی)

API به‌صورت پیش‌فرض خاموش است. برای فعال‌سازی:

```
'api' => [
    'enabled' => true,
],
```

Endpointها زیر prefix پیش‌فرض `iran-locations/api` قرار می‌گیرند:

```
curl "https://example.test/iran-locations/api/status"
curl "https://example.test/iran-locations/api/options/cities?province_code=p.01"
curl "https://example.test/iran-locations/api/search?q=تهران"
curl "https://example.test/iran-locations/api/cities/s.01.01.01.01/regions"
```

API فقط خواندنی است. در JSON mode مقدارها و route parentها بر اساس `code` هستند. اگر فیلتر database id مثل `province_id=1` بفرستید، پاسخ `422` می‌گیرید و باید فیلتر code متناظر را استفاده کنید.

کدهای عمومی داده
----------------

[](#کدهای-عمومی-داده)

`code` مقدار عمومی و پایدار پکیج است. این مقدار را در فرم‌ها، URLها، API و تنظیمات خودتان نگه دارید؛ نه id جدول دیتابیس را. idهای دیتابیس محلی هستند و بعد از sync در هر برنامه می‌توانند متفاوت باشند.

نمونه کدها:

- استان: `p.01`
- شهرستان: `c.01.01`
- بخش: `b.01.01.01`
- دهستان: `d.01.01.01.01`
- شهر: `s.01.01.01.01`
- منطقه شهری: `r.01.01.01.01.05`
- محله: `n.01.01.01.01.05.001`

کدها با scheme کوتاه و fixed-width خود پکیج ساخته شده‌اند. مقدارهای شبیه کد در فایل‌های منبع به‌عنوان `source_id` نگه داشته می‌شوند و public `code` نیستند. چون پکیج هنوز public نشده، کدهای قدیمی pre-release مثل `ir.*` حفظ نشده‌اند و compatibility map هم برای آن‌ها وجود ندارد.

محدوده داده
-----------

[](#محدوده-داده)

داده فعلی package شامل این تعداد رکورد است:

- 31 استان
- 484 شهرستان
- 1087 بخش
- 73 دهستان
- 1456 شهر
- 22 منطقه شهری تهران
- 0 ناحیه شهری
- 568 محله یا مکان شهری تهران
- 568 رابطه محله-منطقه
- 0 alias

ساختار رسمی داده شامل استان، شهرستان، بخش، شهر و دهستان است. ساختار شهری جدا نگه داشته شده: منطقه شهری، ناحیه شهری و محله. ناحیه شهری و alias در schema پشتیبانی می‌شوند، ولی در داده package نسخه `0.2.0-dev` فعلاً خالی هستند مگر اینکه برنامه شما رکورد custom اضافه کند.

نام‌های فارسی public از `ك/ي` عربی به `ک/ی` فارسی نرمال شده‌اند. مرکز استان‌ها هم در داده علامت‌گذاری شده‌اند.

شفافیت منبع و مجوز داده
-----------------------

[](#شفافیت-منبع-و-مجوز-داده)

داده package از فایل‌های spreadsheet وارد و curate شده است. این پکیج ادعا نمی‌کند که داده‌ها همیشه کامل، رسمی، به‌روز یا مناسب استفاده حقوقی، لجستیکی، مقرراتی یا حساس هستند.

قبل از استفاده production که به خود داده وابسته است، وضعیت منبع، مجوز بازنشر، نیازهای attribution و کامل‌بودن داده‌ها را بررسی کنید:

- [DATA-SOURCES.md](DATA-SOURCES.md)
- [DATA-LICENSE.md](DATA-LICENSE.md)

چیزی که فعلاً در scope نیست
---------------------------

[](#چیزی-که-فعلاً-در-scope-نیست)

- پوشش کامل روستاها
- boundary، routing، postal code یا مختصات کامل
- به‌روزرسانی تضمینی روزنامه رسمی یا تقسیمات کشوری
- تضمین مناسب‌بودن برای کاربردهای حقوقی، مقرراتی، لجستیکی یا high-stakes

Admin UI
--------

[](#admin-ui)

Admin UI پیش‌فرض خاموش است و فقط در `database driver` ثبت می‌شود:

```
'admin' => [
    'enabled' => true,
],
```

برای محیط واقعی، routeهای admin را پشت middleware احراز هویت و در صورت نیاز gate برنامه خودتان نگه دارید. به‌صورت پیش‌فرض، ویرایش مستقیم رکوردهای `source = package` محدود است و رکوردهای custom برای تغییرات برنامه شما در نظر گرفته شده‌اند.

تست و release gate
------------------

[](#تست-و-release-gate)

```
composer validate --strict
composer test
composer run-script format:test
composer analyse
composer run-script release:check
```

`release:check` validation، تست‌ها، Pint، PHPStan، ساخت Composer archive و archive hygiene را اجرا می‌کند.

مستندات بیشتر
-------------

[](#مستندات-بیشتر)

- [English README](README.en.md)
- [Data](docs/data.md)
- [Query examples with Tehran city](docs/query-examples.md)
- [Sync](docs/sync.md)
- [Admin UI](docs/admin.md)
- [API](docs/api.md)
- [Blade components](docs/components.md)
- [Extending](docs/extending.md)
- [Consumer smoke test](docs/consumer-smoke-test.md)
- [Release checklist](docs/release-checklist.md)
- [Changelog](CHANGELOG.md)

License
-------

[](#license)

کد پکیج با مجوز [MIT](LICENSE.md) منتشر می‌شود. درباره وضعیت داده‌های package، [DATA-LICENSE.md](DATA-LICENSE.md) را جداگانه بخوانید.

###  Health Score

36

—

LowBetter than 79% of packages

Maintenance99

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity35

Early-stage or recently created project

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

3d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/b3f772fb52747f8a5886d060e6da693a7aef6952200c2227d49c68ff4a1b4bfe?d=identicon)[zarbinco](/maintainers/zarbinco)

---

Tags

laraveliranpersiancitieslocationsprovincesiranianmunicipalneighborhoods

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/zarbinco-laravel-iran-locations/health.svg)

```
[![Health](https://phpackages.com/badges/zarbinco-laravel-iran-locations/health.svg)](https://phpackages.com/packages/zarbinco-laravel-iran-locations)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)[api-platform/laravel

API Platform support for Laravel

58173.9k16](/packages/api-platform-laravel)[laravel/cashier

Laravel Cashier provides an expressive, fluent interface to Stripe's subscription billing services.

2.6k30.1M148](/packages/laravel-cashier)[laravel/pulse

Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application.

1.7k15.1M134](/packages/laravel-pulse)[laravel/ai

The official AI SDK for Laravel.

1.0k3.2M205](/packages/laravel-ai)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9762.4M133](/packages/roots-acorn)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)