README

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.

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:

Unite Mode

IranRegion Model:

Separate Mode

IranProvince Model:

IranCounty Model:

IranSector Model:

IranCity Model:

IranCityDistrict Model:

IranRuralDistrict Model:

IranVillage Model:

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.

salibhdr / typhoon-iran-cities

Maintainers

Details

README

Introduction

Installation

Getting started

Usage

Commands

Commands Explanations:

Code

Unite Mode

Separate Mode

Todos

Issues

License

Contributing

Reference