Laravel Locations Documentation

This package provides large database with Countries, Cities, Areas, Languages and Currencies models to your Laravel application

The package is ideal for applications that need:

• Country/region selection dropdowns
• Address validation and normalization
• Multi-language support for location names
• Currency conversion functionality
• Location-based features and filtering

Database Contents

• 250 Countries
• 5038 Cities (States/Regions)
• 149,350 Areas (subdivisions of Cities/States)

You can access this data either via the Eloquent models or directly through the JSON files included in the package.

By default, all records are active (is_activated = 1). You can filter active records using the activated() scope.

Deprecated: getActive() method is deprecated since v1.4.0. Use activated() scope instead.

Requirements

• PHP 8.2 or higher
• Laravel 9.x or higher

Installation

Run the following commands:

• to install the package

composer require milenmk/laravel-locations

• to publish the migrations

php artisan milenmk-locations:install

• to seed the database tables with the data included in the JSON files

php artisan milenmk-locations:seed

When the commands are run, the database tables for the models will be created, and then they will be seeded with the data included in the JSON files.

For version 1.3+

If you have a previous version installed, run this command to update the country table and add the translations:

php artisan milenmk-locations:update-countries-translations

Usage

This document explains how to use the Laravel Locations package in your application.

Accessing Models

All models include common functionality for translations and activation:

• activated() scope: filters only activated records
• scopeByName($term, $locale = 'EN'): filter by name with dynamic locale
• getName($locale = 'EN'): get the translated name, fallback to English
• getRows(): retrieve data from JSON files with caching

Examples

use Milenmk\Locations\Models\Country;

// Get all active countries
$countries = Country::activated()->get();

// Filter by name in a specific language
$germany = Country::byName('Allemagne', 'FR')->first();

// Get name with fallback
echo $germany->getName('FR'); // returns 'Germany' if French missing

// Read data directly from JSON without DB
$countriesData = (new Country)->getRows();

Relations

Country->cities()
City->country()
City->areas()

Examples

Country Dropdown for Forms

use Milenmk\Locations\Models\Country;

// Populate a dropdown in English
$countries = Country::activated()->orderBy('translations->EN')->get();
foreach ($countries as $country) {
    echo "<option value='{$country->id}'>{$country->getName()}</option>";
}

Country → City → Area Dynamic Selects

use Milenmk\Locations\Models\Country;
use Milenmk\Locations\Models\City;
use Milenmk\Locations\Models\Area;

$country = Country::activated()->first();
$cities = $country->cities()->activated()->get();

$city = $cities->first();
$areas = $city->areas()->activated()->get();

Proximity Search for Cities

use Milenmk\Locations\Models\City;

// Latitude/Longitude for Berlin
$nearbyCities = City::activated()->near(52.52, 13.405, 50)->get();

JSON Data Usage

$countries = (new Country)->getRows();
$cities = (new City)->getRows();
$areas = (new Area)->getRows();

Performance

Laravel Locations includes large datasets for production usage.

Recommendations

• Use activated() scope to limit queries to active records.
• Use getRows() if you want to load data from JSON files instead of querying the database for faster performance in read-heavy operations.
• Cache results from getRows() or queries when repeatedly used in forms or APIs.
• Only load relations when needed (cities, areas) using with() or whenLoaded() in resources.

Example

use Milenmk\Locations\Models\Country;

$countries = Country::activated()->with('cities')->get(); // Only load active countries with their cities

For dynamic selects and forms, use getName($locale) to avoid extra joins or queries for translation data.

Pagination

When displaying large datasets, use pagination:

$cities = City::where('country_id', $countryId)->paginate(15);

Country model

- `id`, `name`, `iso3`, `iso2`, `numeric_code`, `phonecode`, `currency`, `currency_name`, `currency_symbol`, `tld`, `native_name`, `latitude`, `longitude`, `is_activated`, `emoji`, `emojiU`, `translations`,
- `activated()` scope
- `scopeByName($term, $locale = 'EN')`
- `getName($locale = 'EN')`
- `cities()` relation
- `getRows()` JSON reader

City model

```php
- `id`, `name`, `country_id`, `city_code`, `latitude`, `longitude`, `is_activated`
- `activated()` scope
- `scopeByName($term, $locale = 'EN')`
- `getName($locale = 'EN')`
- `country()` relation
- `areas()` relation
- `scopeNear($lat, $lng, $radius = 50)` proximity search
- `getRows()` JSON reader

Area model

- `id`, `name`, `city_id`, `country_id`, `latitude`, `longitude`, `is_activated`, `translations`
- `activated()` scope
- `scopeByName($term, $locale = 'EN')`
- `getName($locale = 'EN')`
- `city()` relation
- `getRows()` JSON reader

Currency model

class Currency extends Model
{
    protected $fillable = [
        'translations',
        'exchange_rate',
        'symbol',
        'is_activated',
        'arabic',
        'name',
        'iso',
        'created_at',
        'updated_at',
    ];

    protected $casts = [
        'translations' => 'array',
        'is_activated' => 'boolean',
    ];

    /**
     * Retrieve all model active records from the database
     */
    public function getActive()
    {
        return self::where('is_activated', 1);
    }

    /**
     * @throws FileNotFoundException
     */
    public function getRows()
    {

        $currencyJson = __DIR__ . '/../../database/data/currencies.json';

        $jsonFileExists = File::exists($currencyJson);
        if ($jsonFileExists) {
            return json_decode(File::get($currencyJson), true);
        } else {
            return [];
        }
    }
}

Language model

class Language extends Model
{
    protected $fillable = [
        'iso',
        'name',
        'arabic',
        'created_at',
        'updated_at',
    ];

    protected $casts = [
        'translations' => 'array',
        'is_activated' => 'boolean',
    ];

    /**
     * Retrieve all model active records from the database
     */
    public function getActive()
    {
        return self::where('is_activated', 1);
    }

    /**
     * @throws FileNotFoundException
     */
    public function getRows()
    {
        $languageJson = __DIR__ . '/../../database/data/languages.json';

        $jsonFileExists = File::exists($languageJson);
        if ($jsonFileExists) {
            return json_decode(File::get($languageJson), true);
        } else {
            return [];
        }
    }
}

DISCLAIMER

This package is provided "as is" without warranty of any kind, either express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, or noninfringement.

The author(s) makes no representations or warranties regarding the accuracy, reliability or completeness of the code or its suitability for any specific use case. It is recommended that you thoroughly test this package in your environment before deploying it to production.

By using this package, you acknowledge and agree that the author(s) shall not be held liable for any damages, losses or other issues arising from the use of this software.

Contributing

You can review the source code, report bugs, or contribute to the project by visiting the GitHub repository.

Feel free to open issues or submit pull requests. Contributions are welcome!

License

This package is licensed under the MIT License.