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 (فارسی).

Table of contents

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.