Skip to content
locations / 1

Models

Last updated:

On this page

Five models in Javaabu\Locations\Models, one table each:

Model Table Belongs to Has many Key code
Country countries states, cities code: ISO 3166-1 alpha-2 (MV)
State states country cities code: ISO 3166-2 (LK-1), nullable
City cities country, state (nullable) code, nullable
Atoll atolls islands, and capital (has one) code: HA, MLE
Island islands atoll code: the island register's feature code (LD0442)

Atolls and islands are Maldivian, so they have no country column. Countries have states and cities, for addresses outside the Maldives.

Always reach the models through Locations (or your own subclasses, see Custom models), so an app's configured model is used:

use Javaabu\Locations\Locations;

$island_class = Locations::islandModel(); // the configured class
$island = Locations::islandModel()::findByCode('LD0442');

Names in English and Dhivehi

Every location has name (English) and dhivehi_name (Thaana, nullable). localizedName() picks one for a locale:

$atoll = Atoll::findByCode('HA');

$atoll->name;                   // Haa Alifu
$atoll->dhivehi_name;           // ހާ އަލިފު
$atoll->localizedName('dv');    // ހާ އަލިފު
$atoll->localizedName('en');    // Haa Alifu
$atoll->localized_name;         // in app()->getLocale()

Dhivehi locales are the ones in config('locations.dhivehi_locales') (['dv']). A location without a Dhivehi name falls back to its English name. With javaabu/translatable, names can be translated into any language.

Why not `name_dv`?

name_dv is javaabu/translatable's naming for a field's translation. A real name_dv column would collide with it, so the column is dhivehi_name.

Countries

use Javaabu\Locations\Models\Country;

$maldives = Country::findByCode('mv');      // case-insensitive

$maldives->code;                    // MV
$maldives->alpha3_code;             // MDV
$maldives->numeric_code;            // 462
$maldives->official_name;           // Republic of Maldives
$maldives->calling_code;            // 960
$maldives->formattedCallingCode();  // +960
$maldives->flag;                    // 🇲🇻
$maldives->isMaldives();            // true

Country::query()->code('LK')->first();
Country::query()->search('ސިންގަ')->get();   // names, Dhivehi names and codes

States and cities

use Javaabu\Locations\Models\City;
use Javaabu\Locations\Models\State;

State::query()->ofCountry('LK')->ordered()->get();     // a code, an id or a model
City::query()->ofCountry($country)->ofState($state)->get();

$state->type;        // Province (the ISO 3166-2 category)
$city->latitude;     // float|null

Atolls

use Javaabu\Locations\Models\Atoll;

$atoll = Atoll::findByCode('HA');

$atoll->code;                       // HA
$atoll->dhivehi_code;               // ހއ
$atoll->letter_code;                // A
$atoll->iso_code;                   // MV-07
$atoll->official_name;              // Thiladhunmathi Uthuruburi
$atoll->official_dhivehi_name;      // ތިލަދުންމަތީ އުތުރުބުރި
$atoll->is_city;                    // false (true for Malé, Addu and Fuvahmulah)
$atoll->capital;                    // the Island Dhidhdhoo
$atoll->islands;

$atoll->localizedCode('dv');        // ހއ
$atoll->localizedOfficialName('dv');
$atoll->optionLabel();              // HA. Haa Alifu / ހއ. ހާ އަލިފު

Atoll::query()->ordered()->get();   // Malé City, then north to south

Malé City is stored as an atoll (MLE, ISO MV-MLE) holding Malé, Hulhumalé and Vilin'gili, as the island register and ISO 3166-2 have it.

Islands

use Javaabu\Locations\Enums\IslandCategories;
use Javaabu\Locations\Models\Island;

$island = Island::findByCode('LD0568');

$island->name;                  // Dhidhdhoo
$island->dhivehi_name;          // ދިއްދޫ
$island->atoll;                 // Haa Alifu
$island->category;              // IslandCategories::RESIDENTIAL
$island->is_capital;            // true
$island->latitude;              // 6.888…
$island->area;                  // hectares
$island->isInhabited();         // true

$island->formattedName('en');   // HA. Dhidhdhoo
$island->formattedName('dv');   // ހއ. ދިއްދޫ
$island->formatted_name;        // in the current locale; Malé City's islands have no prefix
Scope Islands
ofAtoll('HA') Of an atoll: a code, an id or a model
inhabited() Residential islands
category(IslandCategories::TOURISM) Of one or more categories (enums or values)
capitals() Atoll capitals
named() With a name (the register also lists unnamed features)
search('ދިއް') Matching a name, a Dhivehi name or a code
ordered() By name in the current locale's language

IslandCategories has RESIDENTIAL, TOURISM, INDUSTRIAL, INSTITUTIONAL and UNINHABITED, with label() (translated), isInhabited() and labels() for selects:

IslandCategories::labels(); // ['residential' => 'Residential', 'tourism' => 'Tourism', …]

On every model

Method Returns
localizedName(?string $locale = null) The name for the locale
localized_name The same, in the current locale
optionLabel() What selects show: the localized name (HA. Haa Alifu for atolls)
toOption() ['id' => …, 'name' => optionLabel()], as the options endpoint returns
scopeSearch(?string $search) Matches names, Dhivehi names and codes
scopeOrdered(?string $locale = null) Sorted by name in the locale's language (atolls: north to south)
findByCode(string $code) Country, atoll and island only

Factories

Each model has a factory, for tests:

Country::factory()->maldives()->create();
Atoll::factory()->haaAlifu()->create();
Atoll::factory()->male()->create();
Island::factory()->for($atoll)->capital()->create(['name' => 'Dhidhdhoo', 'dhivehi_name' => 'ދިއްދޫ']);
Island::factory()->category(IslandCategories::TOURISM)->create();
State::factory()->for($country)->create();
City::factory()->for($country)->create();

Migrations

The package migrates its tables automatically. To change them, publish the migration first:

php artisan vendor:publish --tag=locations-migrations

Then stop the package from loading its own, in a service provider's register():

use Javaabu\Locations\Locations;

Locations::ignoreMigrations();

To use other table names (an app that already has a countries table), set config('locations.tables') before migrating. Every table also has nullable translations and lang columns for javaabu/translatable, which do nothing without it.

Documentation
All packages

javaabu/locations

Source on GitHub