/typhoon-iran-cities

A Laravel package for importing regions of Iran such as provinces, counties, sectors, cities, city districts, rural districts, and villages of Iran into your database accurately. پکیج لاراول برای افزودن شهرها و استان ها و تمام مناطق روستایی و بخش های ایران

Primary LanguagePHPMIT LicenseMIT

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

SaliBhdr|typhoon

Total Downloads Required Laravel Version Required PHP Version Latest Versions License Today Downloads

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

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

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

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

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:

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

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:

Method Type Usage
getAll($paginate = true/false) static Get all
getAllActive($paginate = true/false) static Get all active
getAllNotActive($paginate = true/false) static Get all not active
active() static/dynamic Query for get active records
notActive() static/dynamic Query for get not active records
activate() dynamic Activates a record
deactivate() dynamic Deactivates a record
isActive() dynamic Returns bool for record status
isNotActive() dynamic Get all the counties of a province

Unite Mode

IranRegion Model:

Method Type Usage
parent() dynamic belongsTo() relation method for the direct parent of a region
children() dynamic hasMany() relation method for all the direct children of a region
province() dynamic belongsTo() relation method for the province of a region if available
provinceChildren() dynamic hasMany() relation method for all the children of a province if available
county() dynamic belongsTo() relation method for the county of a region if available
countyChildren() dynamic hasMany() relation method for all the children of a county if available
sector() dynamic belongsTo() relation method for the sector of a region if available
sectorChildren() dynamic hasMany() relation method for all the children of a sector if available
city() dynamic belongsTo() relation method for the city of a region if available
cityChildren() dynamic hasMany() relation method for all the children of a city if available
ruralDistrict() dynamic belongsTo() relation method for the rural district of a region if available
ruralDistrictChildren() dynamic hasMany() relation method for all the children of a rural district if available

Separate Mode

IranProvince Model:

Method Type Usage
counties() dynamic hasMany() relation method for all the counties of a province
sectors() dynamic hasMany() relation method for all the sectors of a province
cities() dynamic hasMany() relation method for all the cities of a province
cityDistricts() dynamic hasMany() relation method for all the city districts of a province
ruralDistricts() dynamic hasMany() relation method for all the rural districts of a province
villages() dynamic hasMany() relation method for all the villages of a province
getCounties() dynamic Get all the counties of a province
getActiveCounties() dynamic Get all the active counties of a province
getNotActiveCounties() dynamic Get all the not active counties of a province
getSectors() dynamic Get all the sectors of a province
getActiveSectors() dynamic Get all the active sectors of a province
getNotActiveSectors() dynamic Get all the not active sectors of a province
getCities() dynamic Get all the cities of a province
getActiveCities() dynamic Get all the active cities of a province
getNotActiveCities() dynamic Get all the not active cities of a province
getCityDistricts() dynamic Get all the city districts of a province
getActiveCityDistricts() dynamic Get all the active city districts of a province
getNotActiveCityDistricts() dynamic Get all the not active city districts of a province
getRuralDistricts() dynamic Get all the rural districts of a province
getActiveRuralDistricts() dynamic Get all the active rural districts of a province
getNotActiveRuralDistricts() dynamic Get all the not active rural districts of a province
getVillages() dynamic Get all the villages of a province
getActiveVillages() dynamic Get all the active villages of a province
getNotActiveVillages() dynamic Get all the not active villages of a province

IranCounty Model:

Method Type Usage
province() dynamic belongsTo() relation method for the province of a county
sectors() dynamic hasMany() relation method for all the sectors of a county
cities() dynamic hasMany() relation method for all the cities of a county
cityDistricts() dynamic hasMany() relation method for all the city districts of a county
ruralDistricts() dynamic hasMany() relation method for all the rural districts of a county
villages() dynamic hasMany() relation method for all the villages of a county
getProvince() dynamic Get the parent province of a county
getSectors() dynamic Get all the sectors of a county
getActiveSectors() dynamic Get all the active sectors of a county
getNotActiveSectors() dynamic Get all the not active sectors of a county
getCities() dynamic Get all the cities of a county
getActiveCities() dynamic Get all the active cities of a county
getNotActiveCities() dynamic Get all the not active cities of a county
getCityDistricts() dynamic Get all the city districts of a county
getActiveCityDistricts() dynamic Get all the active city districts of a county
getNotActiveCityDistricts() dynamic Get all the not active city districts of a county
getRuralDistricts() dynamic Get all the rural districts of a county
getActiveRuralDistricts() dynamic Get all the active rural districts of a county
getNotActiveRuralDistricts() dynamic Get all the not active rural districts of a county
getVillages() dynamic Get all the villages of a county
getActiveVillages() dynamic Get all the active villages of a county
getNotActiveVillages() dynamic Get all the not active villages of a county

IranSector Model:

Method Type Usage
province() dynamic belongsTo() relation method for the province of a sector
county() dynamic belongsTo() relation method for the county of a sector
cities() dynamic hasMany() relation method for all the cities of a sector
cityDistricts() dynamic hasMany() relation method for all the city districts of a sector
ruralDistricts() dynamic hasMany() relation method for all the rural districts of a sector
villages() dynamic hasMany() relation method for all the villages of a sector
getProvince() dynamic Get the parent province of a sector
getCounty() dynamic Get the parent province of a sector
getCities() dynamic Get all the cities of a sector
getActiveCities() dynamic Get all the active cities of a sector
getNotActiveCities() dynamic Get all the not active cities of a sector
getCityDistricts() dynamic Get all the city districts of a sector
getActiveCityDistricts() dynamic Get all the active city districts of a sector
getNotActiveCityDistricts() dynamic Get all the not active city districts of a sector
getRuralDistricts() dynamic Get all the rural districts of a sector
getActiveRuralDistricts() dynamic Get all the active rural districts of a sector
getNotActiveRuralDistricts() dynamic Get all the not active rural districts of a sector
getVillages() dynamic Get all the villages of a sector
getActiveVillages() dynamic Get all the active villages of a sector
getNotActiveVillages() dynamic Get all the not active villages of a sector

IranCity Model:

Method Type Usage
province() dynamic belongsTo() relation method for the province of a city
county() dynamic belongsTo() relation method for the county of a city
sector() dynamic belongsTo() relation method for the sector of a city
cityDistricts() dynamic hasMany() relation method for all the city districts of a city
getProvince() dynamic Get the parent province of a city
getCounty() dynamic Get the parent county of a city
getSector() dynamic Get the parent sector of a city
getCityDistricts() dynamic Get all the city districts of a city
getActiveCityDistricts() dynamic Get all the active city districts of a city
getNotActiveCityDistricts() dynamic Get all the not active city districts of a city

IranCityDistrict Model:

Method Type Usage
province() dynamic belongsTo() relation method for the province of a city district
county() dynamic belongsTo() relation method for the county of a city district
sector() dynamic belongsTo() relation method for the sector of a city district
city() dynamic belongsTo() relation method for the city of a city district
getProvince() dynamic Get the parent province of a city district
getCounty() dynamic Get the parent county of a city district
getSector() dynamic Get the parent sector of a city district
getCity() dynamic Get the parent city of a city district

IranRuralDistrict Model:

Method Type Usage
province() dynamic belongsTo() relation method for the province of a rural district
county() dynamic belongsTo() relation method for the county of a rural district
sector() dynamic belongsTo() relation method for the sector of a rural district
villages() dynamic hasMany() relation method for all the villages of a rural district
getProvince() dynamic Get the parent province of a rural district
getCounty() dynamic Get the parent county of a rural district
getSector() dynamic Get the parent sector of a rural district
getVillages() dynamic Get all the villages of a rural district
getActiveVillages() dynamic Get all the active villages of a rural district
getNotActiveVillages() dynamic Get all the not active villages of a rural district

IranVillage Model:

Method Type Usage
province() dynamic belongsTo() relation method for the province of a village
county() dynamic belongsTo() relation method for the county of a village
sector() dynamic belongsTo() relation method for the sector of a village
ruralDistrict() dynamic belongsTo() relation method for the rural district of a village
getProvince() dynamic Get the parent province of a village
getCounty() dynamic Get the parent county of a village
getSector() dynamic Get the parent sector of a village
getRuralDistrict() dynamic Get 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

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

Issues

You can report issues in github repository here

License

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

Created by Salar Bahador.

Built with ❤ for you.

Contributing

Contributions, useful comments, and feedback are most welcome!

Reference

Based on ahmadazizi/iran-cities git repository version 3. Take a look For more info.