enadabuzaid/country-data
| Install | |
|---|---|
composer require enadabuzaid/country-data |
|
| Latest Version: | 2.2.0 |
| PHP: | ^8.2 |
| Laravel: | 11 · 12 · 13 |
| License: | MIT |
| Last Updated: | Sep 30, 2026 |
| Links: | GitHub · Packagist |
Laravel Country Data
A full-featured Laravel geography package with countries, cities, and areas — backed by a database with caching, geospatial helpers, validation rules, a Livewire cascading dropdown, and an optional REST API.
Built with multilingual support (English & Arabic), region filters, and a clean Geography facade — ideal for any application that needs structured location data.
Features
- DB-backed geography — countries, cities, and areas as Eloquent models
- Selective seeding — choose which countries to seed interactively or via CLI flags
- Transparent caching — all reads cached, one-command flush
- Geography facade — clean API for countries, cities, areas, search, and select helpers
- Currency & timezone helpers — typed
CurrencyDatavalue object, dial-code lookup, continent grouping - Geospatial helpers — Haversine distance, cities/areas near a coordinate
- Validation rules —
ValidCountryCode,ValidCityForCountry,ValidAreaForCity - Livewire component — cascading Country → City → Area dropdowns, RTL-aware
- Optional REST API — 12 JSON endpoints, opt-in via
.env - Artisan commands — setup, cache-clear, stats
- Multilingual (EN + AR), region filters, and frontend select helpers
Requirements
- PHP
^8.2 - Laravel
^11.0or^12.0
Installation
composer require enadstack/laravel-country-data
Publish the config files:
php artisan vendor:publish --tag=country-data
Geography System Setup
1. Run the interactive setup command
php artisan country-data:setup
The command will ask three things:
Geography Setup
┌ Run migrations? ──────────────────────┐
│ Yes │
└───────────────────────────────────────┘
┌ Seed geography data? ─────────────────┐
│ Yes │
└───────────────────────────────────────┘
┌ Countries to seed ────────────────────┐
│ > ◼ All countries (22) │
│ ◻ Bahrain (BH) │
│ ◼ Jordan (JO) │
│ ◼ Saudi Arabia (SA) │
│ ... │
└───────────────────────────────────────┘
2. Non-interactive / CI options
# Migrate only, seed later
php artisan country-data:setup --migrate
# Seed all countries without prompts
php artisan country-data:setup --seed --all
# Seed specific countries by ISO-2 code
php artisan country-data:setup --seed --countries=JO,SA,AE
# Drop tables + migrate + seed (destructive — confirms before drop)
php artisan country-data:setup --fresh --all
What gets created
| Table | Content |
|---|---|
countries |
22 Arab League countries with currency, dial code, timezone, geo coordinates |
cities |
136 cities across all 22 countries (Jordan: all 12 governorates) |
areas |
276 areas. Amman is fully covered and two-level: 27 Greater Amman Municipality districts, each with its neighborhoods and major streets (207 Amman rows). Other cities remain flat. |
Seeders are idempotent — safe to re-run, they use updateOrInsert.
Geography Facade
use Enadstack\CountryData\Facades\Geography;
Countries
// All active countries (ordered by name_en)
Geography::countries();
// Filter by tag: arab | gulf | middle-east | africa | asia …
Geography::countries('gulf');
// Single country by ISO-2 code (case-insensitive)
$jordan = Geography::country('JO');
$jordan->code; // 'JO'
$jordan->name_en; // 'Jordan'
$jordan->name_ar; // 'الأردن'
$jordan->flag; // '🇯🇴'
$jordan->dial; // '+962'
$jordan->timezones; // ['Asia/Amman']
$jordan->currency_code; // 'JOD'
// All capital cities
Geography::capitals();
// For select dropdowns
Geography::countriesForSelect(locale: 'en', filter: 'arab');
// [['value' => 'JO', 'label' => 'Jordan', 'flag' => '🇯🇴', 'dial' => '+962'], ...]
Cities
// All cities for a country
Geography::cities('JO');
// Single city by country + English name
Geography::city('JO', 'Amman');
// Capital city of a country
Geography::capital('JO');
// Search cities by partial name (EN or AR), optionally scoped to a country
Geography::searchCities('am');
Geography::searchCities('am', 'JO');
// For select dropdowns
Geography::citiesForSelect('JO', locale: 'ar');
// [['value' => 3, 'label' => 'عمان'], ...]
Areas
// All areas for a city (accepts City model or int ID)
Geography::areas($amman);
Geography::areas(3);
// Filter by type: governorate | district | neighborhood | zone
Geography::areas($amman, 'neighborhood');
// Grouped by type
Geography::areasByType($amman);
// Collection keyed by type: ['neighborhood' => [...], 'district' => [...]]
// Search areas within a city
Geography::searchAreas('down', $amman);
// For select dropdowns
Geography::areasForSelect($amman, locale: 'en', type: 'neighborhood');
// [['value' => 12, 'label' => 'Downtown', 'type' => 'neighborhood'], ...]
Area hierarchy
Areas are a two-level tree. A root has parent_id = null (a district, a zone,
or any area in a city that has not been broken down yet); a child points at its
district. Amman is the first city modelled this way — every other city's areas are
roots, exactly as before.
// Roots with their children eager-loaded
$tree = Geography::areaTree($amman);
foreach ($tree as $district) {
echo $district->name_en; // 'Zahran'
foreach ($district->children as $a) {
echo ' '.$a->name_en; // 'Abdoun', 'Sweifieh', …
}
}
// Roots only (e.g. to populate a district dropdown)
Geography::areaRoots($amman, 'district');
// Children of one district
Geography::areaChildren($districtId);
// Grouped for an <optgroup> select
Geography::areasForSelectGrouped($amman, locale: 'ar');
On the model:
$area->parent; // the district, or null for a root
$area->children; // neighborhoods + streets under a district
Area::roots()->get(); // parent_id IS NULL
Area::nested()->get(); // parent_id IS NOT NULL
Area::districts()->get(); // type = district
Area types: governorate, district, neighborhood, zone, and street.
street is used for major named streets (شارع المدينة المنورة, شارع مكة) — in
Jordanian addresses people locate themselves by street as readily as by
neighborhood, so these are selectable areas. A street is a line rather than a
polygon, so its parent_id is the district holding most of its length.
Amman's districts and localities are derived from OpenStreetMap (Amman Governorate, retrieved 2026-08-27). Neighborhoods are assigned to the district whose centre they are nearest, with well-known assignments pinned explicitly; a handful near district boundaries may warrant correction.
Country → Areas (HasManyThrough)
$jordan = Country::where('code', 'JO')->first();
// All areas across all of Jordan's cities
$jordan->areas;
// Filtered
$jordan->areas()->where('type', 'neighborhood')->get();
Currency & Timezone Helpers
Currency
$currency = Geography::currencyOf('JO');
// Returns a CurrencyData value object
$currency->code; // 'JOD'
$currency->nameEn; // 'Jordanian Dinar'
$currency->nameAr; // 'دينار أردني'
$currency->symbolEn; // 'JD'
$currency->symbolAr; // 'د.أ'
// Locale-aware display values
$currency->name(); // 'Jordanian Dinar' (en)
$currency->symbol(); // 'JD' (en)
// Switch locale — returns a new immutable copy
$currency->in('ar')->name(); // 'دينار أردني'
$currency->in('ar')->symbol(); // 'د.أ'
// Serialize
$currency->toArray();
// Countries sharing a currency
Geography::countriesByCurrency('USD');
Timezones
// All IANA timezone identifiers for a country
Geography::timezonesOf('JO'); // ['Asia/Amman']
Geography::timezonesOf('AE'); // ['Asia/Dubai']
// Timezone of a specific city (accepts City model or int ID)
Geography::timezoneForCity($amman); // 'Asia/Amman'
Geography::timezoneForCity(3); // 'Asia/Amman'
Dial Codes
Geography::dialCodeOf('JO'); // '+962'
Geography::countryByDialCode('+962'); // Country model for Jordan
Geography::countryByDialCode('962'); // also works (without +)
Continents
// All distinct continent names
Geography::continents();
// Collection: ['Africa', 'Asia', ...]
// Countries on a continent (flat collection)
Geography::countriesByContinent('Asia');
// All countries grouped by continent
Geography::groupedByContinent();
// Collection keyed by continent name, each value a Collection of Countries
Geospatial Helpers
All distance calculations use the Haversine formula (PHP-level, works with SQLite and all DB drivers).
// Straight-line distance in km between two country centres
Geography::distanceBetween('JO', 'SA'); // ~1,400.0
// Cities within a radius — each result has a `distance` (float, km) attribute
$cities = Geography::citiesNear(lat: 31.9566, lng: 35.9457, radiusKm: 100, countryCode: 'JO');
$cities->first()->distance; // e.g. 0.42
// All cities of a country sorted by distance from a point
$cities = Geography::sortCitiesByDistance(31.9566, 35.9457, 'JO');
$cities->first()->name_en; // 'Amman'
// Areas near a coordinate within a city
$areas = Geography::areasNear(lat: 31.9566, lng: 35.9457, city: $amman, radiusKm: 10);
$areas->first()->distance; // km from the given point
Validation Rules
use Enadstack\CountryData\Rules\ValidCountryCode;
use Enadstack\CountryData\Rules\ValidCityForCountry;
use Enadstack\CountryData\Rules\ValidAreaForCity;
$request->validate([
// Must be an active ISO-2 country code
'country_code' => ['required', new ValidCountryCode()],
// Scoped to a filter (arab, gulf, etc.)
'country_code' => ['required', new ValidCountryCode(filter: 'arab')],
// City must exist and belong to the given country
'city_id' => ['required', new ValidCityForCountry($request->country_code)],
// Area must exist and belong to the given city
'area_id' => ['required', new ValidAreaForCity($request->city_id)],
// Area must also be of a specific type
'area_id' => ['required', new ValidAreaForCity($request->city_id, type: 'neighborhood')],
]);
Phone Input (React)
A searchable dial-code picker (flag + +962) joined to a national-number
input. The selected country's ISO-2 code is kept in a hidden field; users only
see the flag and dial code. Pasting an international number (+962 772 432 330)
selects the country automatically.
🇯🇴 +962 ▾ │ 772432330
1. Pass the countries from the server
use Enadstack\CountryData\Facades\Geography;
return Inertia::render('users/create', [
// [{ value: 'JO', label: 'Jordan', flag: '🇯🇴', flag_svg: '…', dial: '+962' }, …]
'phoneCountries' => Geography::phoneCountriesForSelect(app()->getLocale()),
]);
2. Use the component — import it straight from the package (updates arrive
with composer update) or publish a copy to customise it:
// vite.config.ts → resolve.alias
'@country-data': path.resolve(__dirname, 'vendor/enadstack/laravel-country-data/src/resources/js'),
// tsconfig.json → compilerOptions.paths
"@country-data/*": ["./vendor/enadstack/laravel-country-data/src/resources/js/*"]
/* app.css (Tailwind v4) — let Tailwind see the component's classes */
@source '../../vendor/enadstack/laravel-country-data/src/resources/js/react';
import { PhoneInput } from '@country-data/react/PhoneInput';
<PhoneInput
countries={phoneCountries}
countryCode={data.phone_country_code}
phone={data.phone}
defaultCountry="JO"
invalid={!!errors.phone}
onChange={({ countryCode, phone }) =>
setData((d) => ({ ...d, phone_country_code: countryCode, phone }))
}
/>
Or publish a copy: php artisan country-data:publish-component --component=phone-input --type=react
(→ resources/js/components/custom/PhoneInput.tsx).
The component only depends on React and Tailwind utility classes using
shadcn/ui theme tokens (border-input, bg-popover, ring-ring, …).
| Prop | Type | Description |
|---|---|---|
countries |
PhoneCountryOption[] |
Output of Geography::phoneCountriesForSelect() |
countryCode / phone |
string | null |
Controlled values (ISO-2 / national digits) |
onChange |
({ countryCode, dial, phone, e164 }) => void |
Fired on country or number change |
defaultCountry |
string |
Used while countryCode is empty |
countryCodeName / phoneName |
string |
Input names for native/<Form> posts (phone_country_code / phone) |
invalid, disabled, required, placeholder, searchPlaceholder, emptyText, id, className |
Presentation |
3. Validate and normalise on the server
use Enadstack\CountryData\Rules\ValidCountryCode;
use Enadstack\CountryData\Rules\ValidPhoneNumber;
// "0772 432 330" → "772432330"
$request->merge(['phone' => ValidPhoneNumber::normalize($request->input('phone'))]);
$request->validate([
'phone_country_code' => ['nullable', 'required_with:phone', new ValidCountryCode],
'phone' => ['nullable', new ValidPhoneNumber('phone_country_code')],
]);
ValidPhoneNumber checks digits only, at least 6 digits, and that dial code +
number fit E.164 (15 digits).
Livewire Cascading Dropdown
Requires Livewire 3. The component is auto-registered when Livewire is installed.
Basic usage
<livewire:geography-select />
With options
<livewire:geography-select
locale="ar"
filter="gulf"
:show-areas="true"
:required="true"
country-field="country_code"
city-field="city_id"
area-field="area_id"
/>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
locale |
string |
'en' |
Display language (en or ar) |
filter |
?string |
null |
Country filter tag (e.g. arab, gulf) |
showAreas |
bool |
false |
Show the third area dropdown |
required |
bool |
false |
Mark all selects as required |
countryField |
string |
'country_code' |
Hidden input name for country |
cityField |
string |
'city_id' |
Hidden input name for city |
areaField |
string |
'area_id' |
Hidden input name for area |
Events emitted
| Event | Payload |
|---|---|
country-selected |
['code' => 'JO'] |
city-selected |
['id' => 3] |
area-selected |
['id' => 12] |
Publish the view to customise
php artisan vendor:publish --tag=country-data-livewire
Published to: resources/views/vendor/country-data/livewire/geography-select.blade.php
REST API
The API is disabled by default. Enable it in .env:
COUNTRY_DATA_API=true
COUNTRY_DATA_API_PREFIX=api/geography # default
Or in config/country-data.php:
'api' => [
'enabled' => true,
'prefix' => 'api/geography',
'middleware' => ['api'],
],
Endpoints
Countries
| Method | URL | Description |
|---|---|---|
| GET | /api/geography/countries |
All countries (?filter=gulf&locale=ar) |
| GET | /api/geography/countries/{code} |
Single country by ISO-2 code |
| GET | /api/geography/countries/{code}/cities |
Cities for a country |
Cities & Areas
| Method | URL | Description |
|---|---|---|
| GET | /api/geography/cities/{id} |
Single city by ID |
| GET | /api/geography/cities/{id}/areas |
Areas for a city (?type=neighborhood) |
| GET | /api/geography/cities/{id}/areas/tree |
Districts for a city with their children nested |
| GET | /api/geography/areas/{id}/children |
Areas belonging to one district |
Currency & Continents
| Method | URL | Description |
|---|---|---|
| GET | /api/geography/currencies |
All unique currencies (?locale=ar) |
| GET | /api/geography/currencies/{code}/countries |
Countries using a currency |
| GET | /api/geography/continents |
All distinct continents |
| GET | /api/geography/continents/{name}/countries |
Countries on a continent |
Geospatial
| Method | URL | Description |
|---|---|---|
| GET | /api/geography/near/cities |
Cities near a coordinate (?lat=&lng=&radius=&country=) |
Search
| Method | URL | Description |
|---|---|---|
| GET | /api/geography/search/cities |
Search cities (?q=amman&country=JO) |
| GET | /api/geography/search/areas |
Search areas (?q=down&city_id=3) |
Response shape
{
"data": [ { "code": "JO", "name": "Jordan", "name_en": "Jordan", "name_ar": "الأردن", ... } ],
"meta": { "total": 1 }
}
Artisan Commands
| Command | Description |
|---|---|
php artisan country-data:setup |
Interactive migrate + selective seed |
php artisan country-data:setup --migrate |
Run migrations only |
php artisan country-data:setup --seed --all |
Seed all countries without prompting |
php artisan country-data:setup --seed --countries=JO,SA |
Seed specific countries |
php artisan country-data:setup --fresh --all |
Drop tables, migrate, seed all |
php artisan country-data:cache-clear |
Flush all geography cache entries |
php artisan country-data:stats |
Display seeded counts, cache status |
php artisan country-data:configure |
Choose config-based country dataset |
php artisan country-data:publish-component --component=phone-input --type=react |
Publish a Blade/Vue/React component (country-select, phone-input) |
country-data:stats output
Geography Data Statistics
Countries (active / total) ............. 22 / 22
Cities (active / total) ............. 136 / 136
Capital cities ........................... 22
Areas (active / total) ............... 276 / 276
Countries by continent:
Africa .................................. 5
Asia ................................... 17
Areas by type:
neighborhood ........................... 82
zone ................................... 16
district ................................ 3
Top cities by area count:
Amman (JO) ...................... 207 areas
Riyadh (SA) ..................... 12 areas
Cache:
Enabled ............................. yes
Driver .............................. file
TTL ........................ 86400s (24:00:00)
Tracked keys ......................... 14
Cache Configuration
// config/country-data.php
'cache' => [
'enabled' => true,
'ttl' => 86400, // seconds (24 h)
'prefix' => 'geography',
],
Flush manually:
Geography::flush();
Or via artisan:
php artisan country-data:cache-clear
The cache is also flushed automatically after seeding.
Config Reference
// config/country-data.php
return [
// Config-based country dataset (used by CountryData facade)
'source' => 'all', // 'all' | 'arab' | 'gulf' | 'europe'
'cache' => [
'enabled' => env('COUNTRY_DATA_CACHE', true),
'ttl' => env('COUNTRY_DATA_CACHE_TTL', 86400),
'prefix' => 'geography',
],
'api' => [
'enabled' => env('COUNTRY_DATA_API', false),
'prefix' => env('COUNTRY_DATA_API_PREFIX', 'api/geography'),
'middleware' => ['api'],
],
'livewire' => [
'register' => true,
'locale' => 'en',
'show_areas' => false,
],
'frontend' => [
'component' => 'none', // 'none' | 'blade' | 'vue' | 'react'
'publish_components' => true,
],
];
Config-Based Facade (v1 — still available)
For lightweight use without a database, the original CountryData facade works from config:
use Enadstack\CountryData\Facades\CountryData;
CountryData::getArabCountries();
CountryData::getGulfCountries();
CountryData::getByCode('JO');
CountryData::getByFilter('muslim-majority');
CountryData::searchByName('Jordan');
CountryData::searchByName('الأردن', 'ar');
CountryData::getName('SA', 'ar'); // 'المملكة العربية السعودية'
CountryData::getFlag('JO'); // '🇯🇴'
CountryData::getDialCodes(withFlag: true);
CountryData::getSelectOptions('ar');
File Structure
laravel-country-data/
├── config/
│ ├── countries.php # Config-based country dataset
│ └── country-data.php # Package settings
│
├── data/
│ ├── countries.json # 22 Arab countries (source for DB seeder)
│ ├── cities.json # 136 cities
│ └── areas.json # 276 areas
│
├── database/
│ ├── migrations/
│ │ ├── ..._create_countries_table.php
│ │ ├── ..._create_cities_table.php
│ │ ├── ..._create_areas_table.php
│ │ └── ..._add_parent_id_to_areas_table.php
│ └── Seeders/
│ ├── GeographySeeder.php
│ ├── CountrySeeder.php
│ ├── CitySeeder.php
│ └── AreaSeeder.php
│
├── routes/
│ └── api.php
│
└── src/
├── Commands/
│ ├── GeographySetup.php
│ ├── CacheClear.php
│ ├── Stats.php
│ ├── ConfigureCountryData.php
│ └── PublishFrontendComponent.php
├── Data/
│ └── CurrencyData.php
├── Facades/
│ ├── Geography.php
│ └── CountryData.php
├── Http/Controllers/
│ └── GeographyController.php
├── Livewire/
│ └── GeographySelect.php
├── Models/
│ ├── Country.php
│ ├── City.php
│ └── Area.php
├── Rules/
│ ├── ValidCountryCode.php
│ ├── ValidCityForCountry.php
│ └── ValidAreaForCity.php
├── Services/
│ └── GeographyService.php
└── resources/views/livewire/
└── geography-select.blade.php
Testing
composer test # all tests
composer test:unit # unit tests only
composer test:feature # feature tests only
The test suite runs on an SQLite in-memory database — no external DB needed.
License
MIT — built by @enadabuzaid
Related Packages
Powerful PHP database abstraction layer (DBAL) with many features for database s...
Laravel Serializable Closure provides an easy and secure way to serialize closur...
Cli error handling for console/command-line PHP applications.
Version History
| Version | Released | PHP | Laravel | License |
|---|---|---|---|---|
| 2.2.0 | ^8.2 | ^11.0 || | MIT | |
| 2.1.0 | ^8.2 | ^11.0 || | MIT | |
| 2.0.2 | ^8.2 | ^11.0 || | MIT | |
| 2.0.1 | ^8.2 | ^11.0 || | MIT | |
| 2.0.0 | ^8.2 | ^11.0 || | MIT | |
| 1.0.0 | ^8.2 | ^11.0 || | MIT |