PHPackages                             salibhdr/typhoon-iran-cities - 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. [Database & ORM](/categories/database)
4. /
5. salibhdr/typhoon-iran-cities

ActivePackage[Database & ORM](/categories/database)

salibhdr/typhoon-iran-cities
============================

A laravel package for importing all regions such as provinces, counties, cities, city districts, rural districts and villages of iran into database accurately

3.1.0(1y ago)6121.0k↓45.5%3MITPHPPHP >=5.6.0

Since Feb 29Pushed 1y ago1 watchersCompare

[ Source](https://github.com/SaliBhdr/typhoon-iran-cities)[ Packagist](https://packagist.org/packages/salibhdr/typhoon-iran-cities)[ RSS](/packages/salibhdr-typhoon-iran-cities/feed)WikiDiscussions master Synced 1mo ago

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

Iran Regions such as Provinces, Counties, Cities, City Districts, Rural Districts and Villages
==============================================================================================

[](#iran-regions-such-as-provinces-counties-cities-city-districts-rural-districts-and-villages)

[![SaliBhdr|typhoon](https://camo.githubusercontent.com/888a4d4c2e3a42fed2e33f3d3c1e18d93285fb88031ceba881ac9b98f5b06754/68747470733a2f2f64726976652e676f6f676c652e636f6d2f612f646f6d61696e2e636f6d2f7468756d626e61696c3f69643d3132796e744643695949474a7a4939464d55614639635274584b62307258683958)](https://camo.githubusercontent.com/888a4d4c2e3a42fed2e33f3d3c1e18d93285fb88031ceba881ac9b98f5b06754/68747470733a2f2f64726976652e676f6f676c652e636f6d2f612f646f6d61696e2e636f6d2f7468756d626e61696c3f69643d3132796e744643695949474a7a4939464d55614639635274584b62307258683958)

[![Total Downloads](https://camo.githubusercontent.com/1438c67a6908861f76184d32ef0522ba52f864cc6f7b38a293decd7c09241cdb/68747470733a2f2f706f7365722e707567782e6f72672f73616c69626864722f747970686f6f6e2d6972616e2d6369746965732f646f776e6c6f616473)](https://packagist.org/packages/salibhdr/typhoon-iran-cities/stats)[![Required Laravel Version](https://camo.githubusercontent.com/baad04553c786f60fa2c282ed4502be738579b43bec009864be1d69e47fa78a0/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d254532253839254135352e302d6666326432303f7374796c653d666c61742d737175617265266c6f676f3d6c61726176656c)](https://packagist.org/packages/salibhdr/typhoon-iran-cities)[![Required PHP Version](https://camo.githubusercontent.com/ebdc98821b1fb13a1dfcbe8416ed7a30f59642a525b0a83b67d00f401f062067/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d254532253839254135352e362d3838393262663f7374796c653d666c61742d737175617265266c6f676f3d706870)](https://packagist.org/packages/salibhdr/typhoon-iran-cities)[![Latest Versions](https://camo.githubusercontent.com/19c68ff184920971cc9bd69bb07d121a7f3ae916def4f5d8cf734e919bd30cea/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f73616c69626864722f747970686f6f6e2d6972616e2d6369746965732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/salibhdr/typhoon-iran-cities)[![License](https://camo.githubusercontent.com/a3819e9a5c26a1de206b6447a04f46d17793c06797602d82c8a62c186471fcfa/68747470733a2f2f706f7365722e707567782e6f72672f73616c69626864722f747970686f6f6e2d6972616e2d6369746965732f762f756e737461626c65)](https://packagist.org/packages/salibhdr/typhoon-iran-cities)[![Today Downloads](https://camo.githubusercontent.com/201fe83736b0760b1dadd44df0c19e4cb76f6d216d4fb2c5dc997e8b36fe00f4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64642f73616c69626864722f747970686f6f6e2d6972616e2d6369746965732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/salibhdr/typhoon-iran-cities/stats)

Introduction
------------

[](#introduction)

Typhoon Iran Cities is a Laravel package for importing all regions such as provinces, counties, sectors, cities, city districts, rural districts and villages of Iran into your database with just only one console command.

This is the most accurate Laravel package for administrative divisions of Iran without a doubt.

**Attention:** This package allows you to choose whether to use all regions in just one table or divide them in their own separate table, Or even you can select the data that you want.

[![Administrative Divisions and Regions of Iran](./docs/images/administrative_divisions_of_Iran.jpg)](./docs/images/administrative_divisions_of_Iran.jpg)

**Features**

- All provinces of Iran (استان)
- All counties of Iran (شهرستان)
- All sectors of Iran (بخش)
- All cities of Iran (شهر)
- All city districts of Iran (مناطق شهری)
- All rural districts of Iran (دهستان)
- All villages of Iran (آبادی)
- Built-in models of provinces, counties, sectors, cities, city districts, rural districts and villages
- relational database between these tables
- Both all in one region table and separate tables
- Helper methods

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

[](#installation)

Install with composer:

```
 $ composer require salibhdr/typhoon-iran-cities
```

For Laravel < 5.5 Register the Service provider in your config/app.php configuration file:

```
'providers' => [

     # Other service providers...

     SaliBhdr\TyphoonIranCities\IranCitiesServiceProvider::class,
],

```

Getting started
---------------

[](#getting-started)

This package provides a number of commands for you to easily use them to import migrations, models and data of your desired regions.

Before that, you should pay attention to explanation of the 2 options used in the commands:

**`--unite` option:**

This package can be used in 2 separate strategies. Some programmers like to have each region in a separate table, and others like all regions to be in a single table.

To do this, in the version 3 of this package, it is possible to choose one of these strategies depending on your taste.

If you want to have all regions in one table, you must use the `--unite` option in commands.

**`--target` option:**

The `--target` option allows you to select the regions that you want to use.

Suppose you just want to add **cities** to database, and you may not need villages or rural districts. All you have to do is set the `--target` value equal to the cities.

You can Select the target regions that you want to use from one of these options : all, provinces, counties, sectors, cities, city\_districts, rural\_districts, villages

The default value of the `--target` option is set to all. So if you want all regions don't use this option.

Usage
-----

[](#usage)

### Commands

[](#commands)

Here are the list of all commands that are available:

```
  # init command that runs publish and import commands step by step (For ease of use)
  iran:init                    Copies models and migrations then imports data

  # publish commands
  iran:publish:migrations      Copies migrations into migrations directory
  iran:publish:models          Copies related models

  # import commands
  iran:import                  Imports all regions into the database (Can be selected by option)
```

#### Commands Explanations:

[](#commands-explanations)

**The `iran:init` command:**

If you're using this package for the first time or somehow the migrations, models or data is deleted, you can use this command to initialize all three. Under the hood, this command runs below commands step by step:

```
  iran:publish:migrations      Copies migrations into migrations directory
  iran:publish:models          Copies related models
  migrate                      For migrating new migrations of package
  iran:import                  Imports all regions into the database (Can be selected by option)
```

As mentioned before all commands have the `--unite` and the `--target` options.

Remember if you want all regions to be in one `regions` table Use `--unite` option.

In the following section, we examine both of these cases with the target of the city. Do not use this option if you want all regions.

- One `regions` Table :

```
  php artisan iran:init --unite --target=cities
```

This will publish `IranRegion` model, `create_iran_regions_table` migration and import data up to cities level into `iran_regions` table and will ignore city districts, rural districts and villages

- Separate tables :

```
  php artisan iran:init --target=cities
```

This will publish `IranProvince`,`IranCounty`,`IranSector` adn `IranCity` models, related migrations of these models and import data up to cities level into separate tables and will ignore city districts, rural districts and villages

---

**The `iran:import` command:**

This command will only import data. remember to use the `--unite` and the `--target` options right based on your desired approach.

Check the `iran:init` section above to see the usage of these options.

Cities example:

- One `regions` Table :

```
  php artisan iran:import --unite --target=cities
```

This will import data up to cities level into `iran_regions` table and will ignore city districts, rural districts and villages

- Separate tables :

```
  php artisan iran:import --target=cities
```

This will import data up to cities level into separate tables a nd will ignore city districts, rural districts and villages

---

**The `iran:publish:migrations` command:**

This command will publish related migration files. remember to use the `--unite` and the `--target` options right based on your desired approach.

Check the `iran:init` section above to see the usage of these options.

You can use `--force` option to overwrite the existed files.

Cities example:

- One `regions` Table :

```
  php artisan iran:publish:migrations --unite --target=cities
```

This will publish `create_iran_regions_table` migration file.

- Separate tables :

```
  php artisan iran:import --target=cities
```

This will publish related migration files up to cities level.

---

**The `iran:publish:models` command:**

This command will publish related model files. remember to use the `--unite` and the `--target` options right based on your desired approach.

Check the `iran:init` section above to see the usage of these options.

You can use `--force` option to overwrite the existed files.

Cities example:

- One `regions` Table :

```
  php artisan iran:publish:models --unite --target=cities
```

This will publish `IranRegion` model file.

- Separate tables :

```
  php artisan iran:import --target=cities
```

This will publish related model files up to cities level.

---

#### Code

[](#code)

This package uses eloquent models. Some methods are common among these models, and some aren't. Here is the list of all available methods with their usages:

**Common Methods for All models**

All models have these methods:

MethodTypeUsagegetAll($paginate = true/false)staticGet allgetAllActive($paginate = true/false)staticGet all activegetAllNotActive($paginate = true/false)staticGet all not activeactive()static/dynamicQuery for get active recordsnotActive()static/dynamicQuery for get not active recordsactivate()dynamicActivates a recorddeactivate()dynamicDeactivates a recordisActive()dynamicReturns bool for record statusisNotActive()dynamicGet all the counties of a province---

#### Unite Mode

[](#unite-mode)

**IranRegion Model:**

MethodTypeUsageparent()dynamicbelongsTo() relation method for the direct parent of a regionchildren()dynamichasMany() relation method for all the direct children of a regionprovince()dynamicbelongsTo() relation method for the province of a region if availableprovinceChildren()dynamichasMany() relation method for all the children of a province if availablecounty()dynamicbelongsTo() relation method for the county of a region if availablecountyChildren()dynamichasMany() relation method for all the children of a county if availablesector()dynamicbelongsTo() relation method for the sector of a region if availablesectorChildren()dynamichasMany() relation method for all the children of a sector if availablecity()dynamicbelongsTo() relation method for the city of a region if availablecityChildren()dynamichasMany() relation method for all the children of a city if availableruralDistrict()dynamicbelongsTo() relation method for the rural district of a region if availableruralDistrictChildren()dynamichasMany() relation method for all the children of a rural district if available---

#### Separate Mode

[](#separate-mode)

**IranProvince Model:**

MethodTypeUsagecounties()dynamichasMany() relation method for all the counties of a provincesectors()dynamichasMany() relation method for all the sectors of a provincecities()dynamichasMany() relation method for all the cities of a provincecityDistricts()dynamichasMany() relation method for all the city districts of a provinceruralDistricts()dynamichasMany() relation method for all the rural districts of a provincevillages()dynamichasMany() relation method for all the villages of a provincegetCounties()dynamicGet all the counties of a provincegetActiveCounties()dynamicGet all the active counties of a provincegetNotActiveCounties()dynamicGet all the not active counties of a provincegetSectors()dynamicGet all the sectors of a provincegetActiveSectors()dynamicGet all the active sectors of a provincegetNotActiveSectors()dynamicGet all the not active sectors of a provincegetCities()dynamicGet all the cities of a provincegetActiveCities()dynamicGet all the active cities of a provincegetNotActiveCities()dynamicGet all the not active cities of a provincegetCityDistricts()dynamicGet all the city districts of a provincegetActiveCityDistricts()dynamicGet all the active city districts of a provincegetNotActiveCityDistricts()dynamicGet all the not active city districts of a provincegetRuralDistricts()dynamicGet all the rural districts of a provincegetActiveRuralDistricts()dynamicGet all the active rural districts of a provincegetNotActiveRuralDistricts()dynamicGet all the not active rural districts of a provincegetVillages()dynamicGet all the villages of a provincegetActiveVillages()dynamicGet all the active villages of a provincegetNotActiveVillages()dynamicGet all the not active villages of a province---

**IranCounty Model:**

MethodTypeUsageprovince()dynamicbelongsTo() relation method for the province of a countysectors()dynamichasMany() relation method for all the sectors of a countycities()dynamichasMany() relation method for all the cities of a countycityDistricts()dynamichasMany() relation method for all the city districts of a countyruralDistricts()dynamichasMany() relation method for all the rural districts of a countyvillages()dynamichasMany() relation method for all the villages of a countygetProvince()dynamicGet the parent province of a countygetSectors()dynamicGet all the sectors of a countygetActiveSectors()dynamicGet all the active sectors of a countygetNotActiveSectors()dynamicGet all the not active sectors of a countygetCities()dynamicGet all the cities of a countygetActiveCities()dynamicGet all the active cities of a countygetNotActiveCities()dynamicGet all the not active cities of a countygetCityDistricts()dynamicGet all the city districts of a countygetActiveCityDistricts()dynamicGet all the active city districts of a countygetNotActiveCityDistricts()dynamicGet all the not active city districts of a countygetRuralDistricts()dynamicGet all the rural districts of a countygetActiveRuralDistricts()dynamicGet all the active rural districts of a countygetNotActiveRuralDistricts()dynamicGet all the not active rural districts of a countygetVillages()dynamicGet all the villages of a countygetActiveVillages()dynamicGet all the active villages of a countygetNotActiveVillages()dynamicGet all the not active villages of a county---

**IranSector Model:**

MethodTypeUsageprovince()dynamicbelongsTo() relation method for the province of a sectorcounty()dynamicbelongsTo() relation method for the county of a sectorcities()dynamichasMany() relation method for all the cities of a sectorcityDistricts()dynamichasMany() relation method for all the city districts of a sectorruralDistricts()dynamichasMany() relation method for all the rural districts of a sectorvillages()dynamichasMany() relation method for all the villages of a sectorgetProvince()dynamicGet the parent province of a sectorgetCounty()dynamicGet the parent province of a sectorgetCities()dynamicGet all the cities of a sectorgetActiveCities()dynamicGet all the active cities of a sectorgetNotActiveCities()dynamicGet all the not active cities of a sectorgetCityDistricts()dynamicGet all the city districts of a sectorgetActiveCityDistricts()dynamicGet all the active city districts of a sectorgetNotActiveCityDistricts()dynamicGet all the not active city districts of a sectorgetRuralDistricts()dynamicGet all the rural districts of a sectorgetActiveRuralDistricts()dynamicGet all the active rural districts of a sectorgetNotActiveRuralDistricts()dynamicGet all the not active rural districts of a sectorgetVillages()dynamicGet all the villages of a sectorgetActiveVillages()dynamicGet all the active villages of a sectorgetNotActiveVillages()dynamicGet all the not active villages of a sector---

**IranCity Model:**

MethodTypeUsageprovince()dynamicbelongsTo() relation method for the province of a citycounty()dynamicbelongsTo() relation method for the county of a citysector()dynamicbelongsTo() relation method for the sector of a citycityDistricts()dynamichasMany() relation method for all the city districts of a citygetProvince()dynamicGet the parent province of a citygetCounty()dynamicGet the parent county of a citygetSector()dynamicGet the parent sector of a citygetCityDistricts()dynamicGet all the city districts of a citygetActiveCityDistricts()dynamicGet all the active city districts of a citygetNotActiveCityDistricts()dynamicGet all the not active city districts of a city---

**IranCityDistrict Model:**

MethodTypeUsageprovince()dynamicbelongsTo() relation method for the province of a city districtcounty()dynamicbelongsTo() relation method for the county of a city districtsector()dynamicbelongsTo() relation method for the sector of a city districtcity()dynamicbelongsTo() relation method for the city of a city districtgetProvince()dynamicGet the parent province of a city districtgetCounty()dynamicGet the parent county of a city districtgetSector()dynamicGet the parent sector of a city districtgetCity()dynamicGet the parent city of a city district---

**IranRuralDistrict Model:**

MethodTypeUsageprovince()dynamicbelongsTo() relation method for the province of a rural districtcounty()dynamicbelongsTo() relation method for the county of a rural districtsector()dynamicbelongsTo() relation method for the sector of a rural districtvillages()dynamichasMany() relation method for all the villages of a rural districtgetProvince()dynamicGet the parent province of a rural districtgetCounty()dynamicGet the parent county of a rural districtgetSector()dynamicGet the parent sector of a rural districtgetVillages()dynamicGet all the villages of a rural districtgetActiveVillages()dynamicGet all the active villages of a rural districtgetNotActiveVillages()dynamicGet all the not active villages of a rural district---

**IranVillage Model:**

MethodTypeUsageprovince()dynamicbelongsTo() relation method for the province of a villagecounty()dynamicbelongsTo() relation method for the county of a villagesector()dynamicbelongsTo() relation method for the sector of a villageruralDistrict()dynamicbelongsTo() relation method for the rural district of a villagegetProvince()dynamicGet the parent province of a villagegetCounty()dynamicGet the parent county of a villagegetSector()dynamicGet the parent sector of a villagegetRuralDistrict()dynamicGet the parent rural district of a village---

All models have relation methods between themselves.

**Examples:**

- IranCity Model:

```
use App\Models\IranCity;

# Fetching collection of cities
$cities          = IranCity::getAll(); // returns collection of cities
$activeCities    = IranCity::getAllActive(); // returns collection of active cities
$notActiveCities = IranCity::getAllNotActive(); // returns collection of not active cities

# Getting County
$city = IranCity::find(1);

# A city belongs to a county
$county = $city->county()->first(); // returns County model
$county = $city->getCounty(); // returns County model

# A city belongs to one province
$province = $city->province()->first(); // returns Province model
$province = $city->getProvince(); // returns Province model
```

**Status Field**

Each table has a field named `status`. This field is a boolean type field so that `1` stands for active record and `0` stands for not active record. to make sure that you always get active records, use the `active()` method:

```
use App\Models\IranCity;
use App\Models\IranCounty;
use App\Models\IranProvince;

# To get active provinces or an active province:
$provinces = IranProvince::active()->get(); // returns collection of all active provinces
$provinces = IranProvince::notActive()->get(); // returns collection of all not active provinces

# You can even check if the record is active or not
$city = IranCity::find(1);

$city->isActive(); //returns true if the record is active false if is not active
$city->isNotActive(); //returns true if the record is not active false if is active

# You can even activate and deactivate records like so:
$county = IranCounty::find(1);

$county->activate(); // activates record by setting status field in db to 1
$county->deactivate(); // deactivates record by setting status field in db to 0
```

**Notice :**

Deactivation will be applied by the hierarchy of divisions. For example:

- Province deactivation will deactivate all counties and cities and so on.
- County deactivation will deactivate all cities of that county and so on.

Note that the children's records will not change. They only will be unavailable if you try to get them via the `active()` scope.

For Example :

```
use App\Models\IranProvince;
use App\Models\IranCity;

# assume that city with id `1` is belongs to province with id `1'
# if you deactivate province all the cities will be deactivated and not showed in the results.

$province = IranProvince::active()->find(1); // find the active province with id `1`

$province->deactivate(); // deactivate province with id `1`

# now if you try to get city:
$city = IranCity::active()->find(1); // returns null because the province of the city is deactivated

//or

$city = IranCity::find(1); // finds the record because you didn't use active() scope

$city->isActive(); // return false because the province of the city is not active but the status is still 1
```

Todos
-----

[](#todos)

- Write Tests
- Add longitude and latitude of regions
- Add geo locations of regions

Issues
------

[](#issues)

You can report issues in github repository [here](https://github.com/salibhdr/typhoon-iran-cities/issues)

License
-------

[](#license)

Typhoon-Iran-Cities is released under the MIT License.

Created by [Salar Bahador](https://github.com/salibhdr/typhoon-iran-cities/issues).

Built with ❤ for you.

Contributing
------------

[](#contributing)

Contributions, useful comments, and feedback are most welcome!

Reference
---------

[](#reference)

Based on [ahmadazizi/iran-cities](https://github.com/ahmadazizi/iran-cities) git repository version 3. Take a look For more info.

###  Health Score

41

—

FairBetter than 89% of packages

Maintenance42

Moderate activity, may be stable

Popularity37

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity59

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 98.9% 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 ~163 days

Recently: every ~324 days

Total

12

Last Release

470d ago

Major Versions

1.3.1 → 2.0.02021-07-10

2.1.5 → 3.0.02021-08-30

### Community

Maintainers

![](https://www.gravatar.com/avatar/354ba6970d05ad127ba1fb0c1e8a13ed38b8da3189551dbd192680e6699b57eb?d=identicon)[bahador.salar](/maintainers/bahador.salar)

---

Top Contributors

[![SaliBhdr](https://avatars.githubusercontent.com/u/27485366?v=4)](https://github.com/SaliBhdr "SaliBhdr (86 commits)")[![ariaieboy](https://avatars.githubusercontent.com/u/15873972?v=4)](https://github.com/ariaieboy "ariaieboy (1 commits)")

---

Tags

citiescountiesiraniran-citiesiran-countiesiran-provinceslaravellaravel-iran-citiesphpprovincestyphoon-iran-citiesvillageslaravelcityprovinceiranregionslocationscountyvillagesalibhdrcity-districtrural-district

### Embed Badge

![Health badge](/badges/salibhdr-typhoon-iran-cities/health.svg)

```
[![Health](https://phpackages.com/badges/salibhdr-typhoon-iran-cities/health.svg)](https://phpackages.com/packages/salibhdr-typhoon-iran-cities)
```

###  Alternatives

[anourvalar/eloquent-serialize

Laravel Query Builder (Eloquent) serialization

11320.2M21](/packages/anourvalar-eloquent-serialize)[dragon-code/laravel-deploy-operations

Performing any actions during the deployment process

240173.5k2](/packages/dragon-code-laravel-deploy-operations)[woenel/prpcmblmts

Philippines region, province, cities/municipalities and barangays Laravel migration and table seeder.

2818.3k](/packages/woenel-prpcmblmts)[tomatophp/filament-locations

Database Seeds for Countries / Cities / Areas / Languages / Currancy with ready to use resources for FilamentPHP

2320.8k6](/packages/tomatophp-filament-locations)[nevadskiy/laravel-geonames

Populate your database using the GeoNames service.

2715.1k](/packages/nevadskiy-laravel-geonames)[matriphe/laraciproid

Indonesia city and province data migration and seeder for Laravel.

232.5k](/packages/matriphe-laraciproid)

PHPackages © 2026

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