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).

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

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

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',
        'iso3',
        'iso2',
        'numeric_code',
        'phonecode',
        'currency',
        'currency_name',
        'currency_symbol',
        'tld',
        'native_name',
        'latitude',
        'longitude',
        'is_activated',
        'emoji',
        'emojiU',
        'translations',
    ];

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

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

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

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

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

City model

class City extends Model
{
    protected $fillable = [
        'name',
        'country_id',
        'city_code',
        'latitude',
        'longitude',
        'is_activated',
    ];

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

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

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

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

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

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

Area model

class Area extends Model
{
    protected $fillable = [
        'name',
        'city_id',
        'country_id',
        'latitude',
        'longitude',
        'is_activated',
    ];

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

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

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

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

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

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

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.