PHPackages                             alrez/iran-states - 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. alrez/iran-states

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

alrez/iran-states
=================

A package for managing provinces and cities of Iran in Laravel.

v2.3.2(9mo ago)520MITPHPPHP ^8.2

Since Jan 1Pushed 9mo ago1 watchersCompare

[ Source](https://github.com/allllrez/iranStates)[ Packagist](https://packagist.org/packages/alrez/iran-states)[ RSS](/packages/alrez-iran-states/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (3)Versions (8)Used By (0)

پکیج استان‌ها و شهرهای ایران برای لاراول
========================================

[](#پکیج-استان‌ها-و-شهرهای-ایران-برای-لاراول)

[![License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](https://opensource.org/licenses/MIT)[![PHP Version](https://camo.githubusercontent.com/d840cef9807c8f76051ad687841d67f4d830c84e0d83236968e53124ef6742d5/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344382e322d3838393242462e737667)](https://www.php.net/)[![Laravel Version](https://camo.githubusercontent.com/3aebb9b1ddfbaa83ce4d52280783fa33c90399465e7237cee263f8c4e03a0d94/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c61726176656c2d313125323025374325323031322d4646324432302e737667)](https://laravel.com)

درباره پکیج
-----------

[](#درباره-پکیج)

این پکیج برای مدیریت استان‌ها و شهرهای ایران در فریم‌ورک لاراول طراحی شده است. با استفاده از این پکیج می‌توانید به راحتی به لیست استان‌ها و شهرهای ایران دسترسی داشته باشید.

ویژگی‌های جدید
--------------

[](#ویژگی‌های-جدید)

- سازگار با Laravel 11 و 12
- Seeder بهینه شده با استفاده از chunk(1000)
- دو trait جدید برای مدیریت روابط
- Service بهینه شده با cache بهتر
- Type hints کامل برای PHP 8.2+

نصب
---

[](#نصب)

برای نصب از طریق کامپوزر:

```
composer require alrez/iran-states
```

سپس برای نصب جداول و داده‌های پایه:

```
php artisan iranStates:install
```

این دستور به صورت خودکار مایگریشن‌ها را اجرا کرده و داده‌های پایه را در دیتابیس وارد می‌کند.

انتشار فایل‌های پکیج (اختیاری)
------------------------------

[](#انتشار-فایل‌های-پکیج-اختیاری)

برای انتشار فایل کانفیگ:

```
php artisan vendor:publish --tag=iran-states
```

استفاده
-------

[](#استفاده)

### مدل‌ها با Traits جدید

[](#مدل‌ها-با-traits-جدید)

#### مدل City با InteractWithState

[](#مدل-city-با-interactwithstate)

```
use Alrez\IranStates\Models\City;

$city = City::find(1);

// استفاده از trait methods
$state = $city->getStateById($city->state_id);
$citiesInSameState = $city->getCitiesByState($city->state_id);
$belongsToTehran = $city->belongsToState(8); // تهران
```

#### مدل State با InteractWithStates

[](#مدل-state-با-interactwithstates)

```
use Alrez\IranStates\Models\State;

$state = State::find(1);

// استفاده از trait methods
$allStates = $state->getAllStates();
$statesWithCities = $state->getAllStatesWithCities();
$searchResult = $state->searchStates('تهران');
$specificStates = $state->getStatesByIds([1, 2, 3]);
$citiesFromStates = $state->getCitiesFromStates([1, 2, 3]);
$statesCount = $state->getStatesCount();
```

### استفاده از Traits در مدل‌های شخصی

[](#استفاده-از-traits-در-مدل‌های-شخصی)

#### برای مدل‌هایی که به یک استان تعلق دارند

[](#برای-مدل‌هایی-که-به-یک-استان-تعلق-دارند)

```
use Alrez\IranStates\Traits\InteractWithState;

class User extends Model
{
    use InteractWithState;

    // حالا می‌توانید از متدهای trait استفاده کنید
}

$user = new User();
$userState = $user->getStateById($user->state_id);
$citiesInUserState = $user->getCitiesByState($user->state_id);
```

#### برای مدل‌هایی که با چندین استان کار می‌کنند

[](#برای-مدل‌هایی-که-با-چندین-استان-کار-می‌کنند)

```
use Alrez\IranStates\Traits\InteractWithStates;

class Organization extends Model
{
    use InteractWithStates;

    // حالا می‌توانید از متدهای trait استفاده کنید
}

$org = new Organization();
$allStates = $org->getAllStates();
$statesWithCities = $org->getAllStatesWithCities();
$searchedStates = $org->searchStates('خراسان');
```

### سرویس بهینه شده

[](#سرویس-بهینه-شده)

```
use Alrez\IranStates\Services\CityStateService;

$service = new CityStateService();

// دریافت همه استان‌ها (از cache)
$allStates = $service->getAllStates();

// دریافت استان‌ها با شهرها (برای dropdown ها)
$statesWithCities = $service->getAllStatesWithCities();

// دریافت یک استان خاص
$state = $service->getStateById(8);

// دریافت یک استان با شهرهایش
$stateWithCities = $service->getStateWithCitiesById(8);

// دریافت شهرهای یک استان
$cities = $service->getCitiesByStateId(8);

// دریافت یک شهر خاص
$city = $service->getCityById(1);

// جستجو در شهرها
$searchedCities = $service->searchCities('تهران');

// جستجو در استان‌ها
$searchedStates = $service->searchStates('خراسان');

// عملیات batch برای چندین استان
$multipleStates = $service->getStatesByIds([1, 2, 3]);
$citiesFromMultipleStates = $service->getCitiesByStateIds([1, 2, 3]);

// آمار
$statesCount = $service->getStatesCount();
$citiesCount = $service->getCitiesCount();

// پاک کردن cache
$service->clearCache();
```

### قوانین اعتبارسنجی

[](#قوانین-اعتبارسنجی)

```
use Alrez\IranStates\Traits\ValidationRules;

class YourController
{
    use ValidationRules;

    public function validateState($request)
    {
        $rules = $this->getStateRules();
        // اعتبارسنجی...
    }

    public function validateCity($request)
    {
        $rules = $this->getCityRules();
        // اعتبارسنجی...
    }
}
```

نکات عملکرد
-----------

[](#نکات-عملکرد)

### Cache

[](#cache)

- تمام عملیات اصلی cache شده‌اند (24 ساعت)
- برای پاک کردن cache از `clearCache()` استفاده کنید
- عملیات جستجو cache نمی‌شوند

### انتخاب متد مناسب

[](#انتخاب-متد-مناسب)

- برای dropdown کامل: `getAllStatesWithCities()`
- برای یک استان خاص: `getStateById()`
- برای شهرهای یک استان: `getCitiesByStateId()`
- برای عملیات چندتایی: `getStatesByIds()` یا `getCitiesByStateIds()`

---

Iran States Package for Laravel
===============================

[](#iran-states-package-for-laravel)

[![License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](https://opensource.org/licenses/MIT)[![PHP Version](https://camo.githubusercontent.com/d840cef9807c8f76051ad687841d67f4d830c84e0d83236968e53124ef6742d5/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344382e322d3838393242462e737667)](https://www.php.net/)[![Laravel Version](https://camo.githubusercontent.com/3aebb9b1ddfbaa83ce4d52280783fa33c90399465e7237cee263f8c4e03a0d94/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c61726176656c2d313125323025374325323031322d4646324432302e737667)](https://laravel.com)

About
-----

[](#about)

This package provides a comprehensive solution for managing Iran's states and cities in Laravel applications. It offers easy access to a complete list of Iran's states and their corresponding cities with improved performance and modern Laravel features.

New Features
------------

[](#new-features)

- Compatible with Laravel 11 & 12
- Optimized seeders using chunk(1000)
- Two new traits for relationship management
- Enhanced service with better caching
- Full type hints for PHP 8.2+

Installation
------------

[](#installation)

Install via Composer:

```
composer require alrez/iran-states
```

Then install the tables and seed the data:

```
php artisan iranStates:install
```

This command will automatically run the migrations and seed the database with the initial data using optimized chunked insertion.

Publishing Package Files (Optional)
-----------------------------------

[](#publishing-package-files-optional)

To publish the config file:

```
php artisan vendor:publish --tag=iran-states
```

Usage
-----

[](#usage)

### Models with New Traits

[](#models-with-new-traits)

#### City Model with InteractWithState

[](#city-model-with-interactwithstate)

```
use Alrez\IranStates\Models\City;

$city = City::find(1);

// Using trait methods
$state = $city->getStateById($city->state_id);
$citiesInSameState = $city->getCitiesByState($city->state_id);
$belongsToTehran = $city->belongsToState(8); // Tehran
```

#### State Model with InteractWithStates

[](#state-model-with-interactwithstates)

```
use Alrez\IranStates\Models\State;

$state = State::find(1);

// Using trait methods
$allStates = $state->getAllStates();
$statesWithCities = $state->getAllStatesWithCities();
$searchResult = $state->searchStates('Tehran');
$specificStates = $state->getStatesByIds([1, 2, 3]);
$citiesFromStates = $state->getCitiesFromStates([1, 2, 3]);
$statesCount = $state->getStatesCount();
```

### Using Traits in Your Own Models

[](#using-traits-in-your-own-models)

#### For models that belong to a single state

[](#for-models-that-belong-to-a-single-state)

```
use Alrez\IranStates\Traits\InteractWithState;

class User extends Model
{
    use InteractWithState;

    // Now you can use trait methods
}

$user = new User();
$userState = $user->getStateById($user->state_id);
$citiesInUserState = $user->getCitiesByState($user->state_id);
```

#### For models that work with multiple states

[](#for-models-that-work-with-multiple-states)

```
use Alrez\IranStates\Traits\InteractWithStates;

class Organization extends Model
{
    use InteractWithStates;

    // Now you can use trait methods
}

$org = new Organization();
$allStates = $org->getAllStates();
$statesWithCities = $org->getAllStatesWithCities();
$searchedStates = $org->searchStates('Khorasan');
```

### Enhanced Service

[](#enhanced-service)

```
use Alrez\IranStates\Services\CityStateService;

$service = new CityStateService();

// Get all states (cached)
$allStates = $service->getAllStates();

// Get states with cities (for dropdowns)
$statesWithCities = $service->getAllStatesWithCities();

// Get specific state
$state = $service->getStateById(8);

// Get state with its cities
$stateWithCities = $service->getStateWithCitiesById(8);

// Get cities of a state
$cities = $service->getCitiesByStateId(8);

// Get specific city
$city = $service->getCityById(1);

// Search cities
$searchedCities = $service->searchCities('Tehran');

// Search states
$searchedStates = $service->searchStates('Khorasan');

// Batch operations for multiple states
$multipleStates = $service->getStatesByIds([1, 2, 3]);
$citiesFromMultipleStates = $service->getCitiesByStateIds([1, 2, 3]);

// Statistics
$statesCount = $service->getStatesCount();
$citiesCount = $service->getCitiesCount();

// Clear cache
$service->clearCache();
```

### Validation Rules

[](#validation-rules)

```
use Alrez\IranStates\Traits\ValidationRules;

class YourController
{
    use ValidationRules;

    public function validateState($request)
    {
        $rules = $this->getStateRules();
        // Validation...
    }

    public function validateCity($request)
    {
        $rules = $this->getCityRules();
        // Validation...
    }
}
```

Performance Notes
-----------------

[](#performance-notes)

### Caching

[](#caching)

- All main operations are cached (24 hours)
- Use `clearCache()` to clear cache when needed
- Search operations are not cached

### Choosing the Right Method

[](#choosing-the-right-method)

- For complete dropdown: `getAllStatesWithCities()`
- For specific state: `getStateById()`
- For cities of a state: `getCitiesByStateId()`
- For batch operations: `getStatesByIds()` or `getCitiesByStateIds()`

Requirements
------------

[](#requirements)

- PHP 8.2 or higher
- Laravel 11.x or 12.x

License
-------

[](#license)

MIT License. Please see [License File](LICENSE) for more information.

###  Health Score

35

—

LowBetter than 79% of packages

Maintenance58

Moderate activity, may be stable

Popularity11

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

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

Every ~36 days

Recently: every ~54 days

Total

7

Last Release

280d ago

Major Versions

1.0.1 → 2.0.02025-01-02

PHP version history (3 changes)1.0.0PHP >=8.0

v2.0.2PHP ^8.1

2.3.0PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/1767c09ddf866b71f2bd638162e59738209519ed5ef39dcf8b10ef76d1eb0bf4?d=identicon)[allllrez](/maintainers/allllrez)

---

Top Contributors

[![allllrez](https://avatars.githubusercontent.com/u/59174747?v=4)](https://github.com/allllrez "allllrez (27 commits)")

---

Tags

phplaravellaravel 12iranphp 8.2iran-citiesiran-statesiran-provincesiran-package

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/alrez-iran-states/health.svg)

```
[![Health](https://phpackages.com/badges/alrez-iran-states/health.svg)](https://phpackages.com/packages/alrez-iran-states)
```

###  Alternatives

[gehrisandro/tailwind-merge-laravel

TailwindMerge for Laravel merges multiple Tailwind CSS classes by automatically resolving conflicts between them

341682.2k18](/packages/gehrisandro-tailwind-merge-laravel)[iteks/laravel-enum

A comprehensive Laravel package providing enhanced enum functionalities, including attribute handling, select array conversions, and fluent facade interactions for robust enum management in Laravel applications.

2516.7k](/packages/iteks-laravel-enum)[salmanzafar/laravel-geocode

A Laravel Library to find Lat and Long of a given Specific Address

153.9k](/packages/salmanzafar-laravel-geocode)

PHPackages © 2026

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