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

4.0.0 2026-07-02 19:25 UTC

Requires

• php: ^8.3
• illuminate/console: ^13.0
• illuminate/database: ^13.0
• illuminate/filesystem: ^13.0
• illuminate/support: ^13.0

Requires (Dev)

• orchestra/testbench: ^11.0
• phpunit/phpunit: ^11.5

MIT

• Salar Bahador

• laravel
• city
• locations
• province
• regions
• iran
• county
• village
• salibhdr
• city-district
• rural-district

Published on Packagist.org on 2026-07-02 19:35 UTC

README

English · فارسی

A Laravel package that imports Iran's administrative divisions — provinces, counties, sectors, cities, city districts, rural districts, and villages — into your database with Artisan commands. Includes Eloquent models, relationships, and optional city coordinates.

composer require salibhdr/typhoon-iran-cities
php artisan iran:init --no-interaction --force

Requires Laravel 13 and PHP 8.3+ on the latest release. Older Laravel apps should use ^3.1 — see the version matrix.

Documentation

Full documentation lives in docs/ — available in English and Persian (فارسی).

	English	فارسی
Start here	English docs	مستندات فارسی
Hub / TOC	docs/README.md	same

Table of contents

Topic	EN	FA
Introduction	→	→
Requirements & versioning	→	→
Installation	→	→
Quick start	→	→
Storage modes (separate / unite)	→	→
Commands reference	→	→
Models & relationships	→	→
Status field	→	→
City coordinates	→	→
Upgrade guide	→	→
FAQ & troubleshooting	→	→
Testing & contributing	→	→

Features at a glance

• All seven official division levels with relational data and codes
• Separate tables (default) or unite mode (single iran_regions table)
• Selective import with --target (e.g. cities only)
• Published migrations and models — you own the schema
• Active/inactive status with hierarchy-aware scopes
• City latitude/longitude via --with-city-coordinates
• Re-import with --fresh when upstream data updates

Quick example

use App\Models\IranCity;

IranCity::active()
    ->with('county.province')
    ->orderBy('name')
    ->get();

Testing

composer test
composer test:coverage   # requires PCOV

Coverage runs in CI on every push and PR — Codecov.

Package dependency

Published models extend SaliBhdr\TyphoonIranCities\Models\* — keep this package installed after iran:publish:models.

Published migrations are self-contained and do not reference the package namespace.

Changelog & upgrades

See CHANGELOG.md and the upgrade guide (EN) / راهنمای ارتقا (FA).

License & credits

MIT License — Salar Bahador.

Data based on ahmadazizi/iran-cities v3.

Issues: GitHub · Contributions welcome.

Built with ❤ for you.