Laravel Locations Documentation

About

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

The database contains:

• 250 Countries
• 5038 Cities (States/Regions)
• 149350 Areas (Cities part of a State/Region)

After installation, you can use the Package models to retrieve the data OR directly use the json files.

By default, all records are active (the field is_activated has a value of 1).

Is you want to exclude certain records, change the field value to 0 and use the model method getActive()

Requirements

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

Installation

To install the package, run

composer require milenmk/laravel-locations

Then, to publish the migrations and seed the database tables run:

php artisan milenmk-locations:install

This command will:

• Create the necessary database tables
• Seed the tables with data from the included JSON files
• Set up model relationships

Usage

Basic Usage

Retrieving Countries

use Milenmk\LaravelLocations\Models\Country;

// Get all countries
$countries = Country::all();

// Get only active countries
$activeCountries = Country::where('is_activated', 1)->get();
// OR using the convenience method
$activeCountries = Country::getActive();

// Get countries with their cities
$countriesWithCities = Country::with('cities')->get();

// Find a country by code
$usa = Country::where('code', 'US')->first();

Working with Cities and Areas

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

// Get all cities for a country
$country = Country::find(1); // United States
$cities = $country->cities;

// Get areas (sub-cities) within a city
$city = City::find(1); // e.g., New York
$areas = $city->areas;

// Get a city's country
$city = City::find(1);
$country = $city->country;

// Get an area's city and country
$area = Area::find(1);
$city = $area->city;
$country = $area->city->country;

Working with translations

// Countries, cities, and areas have translations stored as JSON
$country = Country::find(1);
$translations = $country->translations;

// Access a specific translation
$frenchName = $translations['fr'] ?? $country->name;

Advanced Usage

Creating Dropdown Selects

// In your controller
public function createAddressForm()
{
    $countries = Country::getActive()->pluck('name', 'id');
    return view('address-form', compact('countries'));
}

// For dynamic city loading based on country selection
public function getCitiesByCountry($countryId)
{
    $cities = City::where('country_id', $countryId)
                 ->where('is_activated', 1)
                 ->pluck('name', 'id');
    
    return response()->json($cities);
}

Using with Eloquent Relationships

// Example: User model with address relationship
class User extends Model
{
    // ...
    
    public function country()
    {
        return $this->belongsTo(Country::class);
    }
    
    public function city()
    {
        return $this->belongsTo(City::class);
    }
    
    public function area()
    {
        return $this->belongsTo(Area::class);
    }
}

// Usage
$user = User::find(1);
echo $user->country->name;
echo $user->city->name;
echo $user->area->name;

Working with Currencies

use Milenmk\LaravelLocations\Models\Currency;

// Get all currencies
$currencies = Currency::all();

// Get a specific currency
$euro = Currency::where('iso', 'EUR')->first();

// Access currency properties
echo $euro->symbol; // €
echo $euro->name; // Euro
echo $euro->exchange_rate; // Exchange rate relative to base currency

Filtering and Searching

// Search for countries by name
$searchTerm = 'united';
$countries = Country::where('name', 'LIKE', "%{$searchTerm}%")->get();

// Get countries by region
$europeanCountries = Country::where('region', 'Europe')->get();

// Get countries with specific currency
$euroCountries = Country::where('currency', 'EUR')->get();

Address Form with Dependent Dropdowns

<form>
    <div class="form-group">
        <label for="country">Country</label>
        <select id="country" name="country_id" class="form-control">
            <option value="">Select Country</option>
            @foreach($countries as $id => $name)
                <option value="{{ $id }}">{{ $name }}</option>
            @endforeach
        </select>
    </div>
    
    <div class="form-group">
        <label for="city">City/State</label>
        <select id="city" name="city_id" class="form-control" disabled>
            <option value="">Select City</option>
        </select>
    </div>
    
    <div class="form-group">
        <label for="area">Area</label>
        <select id="area" name="area_id" class="form-control" disabled>
            <option value="">Select Area</option>
        </select>
    </div>
</form>

<script>
    // JavaScript for dependent dropdowns
    document.getElementById('country').addEventListener('change', function() {
        const countryId = this.value;
        const citySelect = document.getElementById('city');
        
        if (countryId) {
            // Enable city dropdown and fetch cities
            citySelect.disabled = false;
            
            fetch(`/api/cities/${countryId}`)
                .then(response => response.json())
                .then(data => {
                    citySelect.innerHTML = '<option value="">Select City</option>';
                    
                    Object.entries(data).forEach(([id, name]) => {
                        const option = document.createElement('option');
                        option.value = id;
                        option.textContent = name;
                        citySelect.appendChild(option);
                    });
                });
        } else {
            // Reset and disable dropdowns
            citySelect.disabled = true;
            citySelect.innerHTML = '<option value="">Select City</option>';
            
            const areaSelect = document.getElementById('area');
            areaSelect.disabled = true;
            areaSelect.innerHTML = '<option value="">Select Area</option>';
        }
    });
    
    // Similar event listener for city dropdown to load areas
</script>

Display User's Location with Flag

// In your controller
public function showUserProfile($userId)
{
    $user = User::with(['country', 'city', 'area'])->findOrFail($userId);
    return view('user.profile', compact('user'));
}

// In your view
@if($user->country)
    <div class="user-location">
        <img src="{{ asset('flags/' . strtolower($user->country->code) . '.svg') }}" 
             alt="{{ $user->country->name }} flag" 
             class="country-flag">
        {{ $user->country->name }}
        @if($user->city)
            , {{ $user->city->name }}
            @if($user->area)
                , {{ $user->area->name }}
            @endif
        @endif
    </div>
@endif

Use Eager Loading

When retrieving related models, use eager loading to avoid N+1 query problems:

$countries = Country::with(['cities', 'cities.areas'])->get();

Cache Common Queries

For data that doesn't change often, consider caching:

$countries = Cache::remember('all_countries', 60*24, function () {
    return Country::all();
});

Pagination

When displaying large datasets, use pagination:

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

Country model

class Country extends Model
{
    protected $fillable = [
        'name',
        'code',
        'phone',
        'lat',
        'lng',
        'translations',
        'timezones',
        'numeric_code',
        'is_activated',
        'flag',
        'emojiU',
        'emoji',
        'wikiDataId',
        'currency_symbol',
        'currency_name',
        'currency',
        'region',
        'native',
        'tld',
        'capital',
        'nationality',
        'iso3',
        'created_at',
        'updated_at',
    ];

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

    public function cities(): HasMany
    {
        return $this->hasMany(City::class);
    }
}

City model

class City extends Model
{
    protected $fillable = [
        'name',
        'translations',
        'is_activated',
        'country_id',
        'lat',
        'lng',
        'created_at',
        'updated_at',
    ];

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

    public function country(): BelongsTo
    {
        return $this->belongsTo(Country::class);
    }

    public function areas(): HasMany
    {
        return $this->hasMany(Area::class);
    }
}

Area model

class Area extends Model
{
    protected $fillable = [
        'name',
        'city_id',
        'translations',
        'is_activated',
        'created_at',
        'updated_at',
    ];

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

    public function city(): BelongsTo
    {
        return $this->belongsTo(City::class);
    }
}

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',
    ];
}

Language model

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

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