Typhoon Iran Cities

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.