README

The World is a Laravel package that provides a comprehensive list of countries, states, cities, timezones, currencies, languages and IP geolocation. You can access the data using the World Facade or through defined API routes.

🌍 New in v1.1.39: Laravel 13, Hungarian, and refreshed world data
Laravel 10–13 compatibility, GeoIP2 v3, cache controls, 11 new Algerian wilayas, and Bulgaria's Euro adoption.
Learn more →

Table of Contents

• Installation
  • Automated Installation
  • Manual Installation
• What's New in v1.1.39
• Changelog
• Contributing
• Examples
• Usage
  • List All Countries
  • Fetch Country with States & Cities
  • List All Cities by Country ID
• Available Actions
• Available API Routes
  • Countries
  • States
  • Cities
  • Timezones
  • Currencies
  • Languages
  • Geolocate
• Localization
• Schema
• Configuration
• Testing

Installation

First, set your application environment to local:

set APP_ENV=local

Then, install the package via composer:

composer require nnjeim/world

Optionally, set the WORLD_DB_CONNECTION environment variable to your desired database connection.

Automated Installation

Run the following Artisan command to automate the installation process:

php artisan world:install

Manual Installation

If you prefer to install the package manually, follow these steps:

1. Publish the package configuration file:

php artisan vendor:publish --tag=world --force

1. Run the migrations:

php artisan migrate 

1. Seed the database:

php artisan db:seed --class=WorldSeeder

Upgrading

⚠️ Important: When upgrading to a new version, you must re-publish the configuration file to ensure all new features work correctly:

php artisan vendor:publish --tag=world --force

This command updates the config/world.php file with new configuration options. Failing to run this command may result in missing features or errors.

What's new in v1.1.39?

• Added Laravel 13 support while retaining Laravel 10–12 compatibility.
• Upgraded the MaxMind client to GeoIP2 v3 and raised the minimum PHP version to 8.1.
• Added Hungarian localization and corrected the Bengali name for Kosovo.
• Added the 11 Algerian wilayas created by the 2025–2026 territorial reform and reassigned their cities.
• Updated Bulgaria's currency to the Euro.
• Added configurable and per-action cache controls.
• Fixed runtime locale switching through World::setLocale().
• Added a standalone test suite and a PHP/Laravel CI compatibility matrix.

⚠️ Required: After upgrading, run php artisan vendor:publish --tag=world --force to update your configuration file.

Changelog

For detailed information on recent changes, please see the CHANGELOG.

Contributing

We welcome contributions! For details on how to get started, please review our CONTRIBUTING guidlines.

Examples

Explore the API examples on our live site:

List all countries:
https://world.bmbc.cloud/api/countries
Search for a country:
https://world.bmbc.cloud/api/countries?search=rom
Get states by country code:
https://world.bmbc.cloud/api/states?filters[country_code]=RO&fields=cities

Usage

List all the countries

Use the World facade:

use Nnjeim\World\World;

$action =  World::countries();

if ($action->success) {
  $countries = $action->data;
}

response (object)
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Afghanistan"
    },
    {
      "id": 2,
      "name": "Åland Islands"
    },
    .
    .
    .
  ],
}

Use the API countries endpoint:

https://myDomain.local/api/countries

Fetch a country with its states and cities.

Use the World facade:

use Nnjeim\World\World;

$action =  World::countries([
	'fields' => 'states,cities',
	'filters' => [
		'iso2' => 'FR',
	]
]);

if ($action->success) {

	$countries = $action->data;
}

Response:

(object)
{
  "success": true,
  "data": [
    "id": 77,
    "name": "France",
    "states": [
        {
          "id": 1271,
          "name": "Alo"
        },
        {
          "id": 1272,
          "name": "Alsace"
        },
        .
        .
        .
    ],
    "cities": [
        {
          "id": 25148,
          "name": "Abondance"
        },
        {
          "id": 25149,
          "name": "Abrest"
        },
        .
        .
        .
      ]
    ],
}

Use the API countries endpoint:

https://myDomain.local/api/countries?fields=states,cities&filters[iso2]=FR

List all the cities by country id

use Nnjeim\World\WorldHelper;

new class {
    protected $world;
    
    public function __construct(WorldHelper $world) {
        $this->world = $world;
    }
    
    $action = $this->world->cities([
        'filters' => [
            'country_id' => 182,
        ],
    ]);
    
    if ($action->success) {
        $cities = $action->data;
    }
}

Use the API cities endpoint:

https://myDomain.local/api/cities?filters[country_code]=RO 

Available actions

An action response is formed as below:

• success (boolean)
• message (string)
• data (instance of Illuminate\Support\Collection)
• errors (array)

Countries action

• fields*: comma separated string (countries table fields in addition to states, cities, currency and timezones).
• filters*: array of keys (countries table fields) and their corresponding values.
• search*: string.

States action

• fields*: comma separated string (states table fields in addition to country and states).
• filters*: array of keys (states table fields) and their corresponding values.
• search*: string.

Cities action

• fields*: comma separated string (cities table fields in addition to country and state).
• filters*: array of keys (cities table fields) and their corresponding values.
• search*: string.

Timezones action

• fields*: comma separated string (timezones table fields in addition to country).
• filters*: array of keys (timezones table fields) and their corresponding values.
• search*: string.

Currencies action

• fields*: comma separated string (currencies table fields in addition to country).
• filters*: array of keys (currencies table fields) and their corresponding values.
• search*: string.

Languages action

• fields*: comma separated string (languages table fields).
• filters*: array of keys (languages table fields) and their corresponding values.
• search*: string.

Geolocate action

Geolocate an IP address. Returns country, state, city, coordinates, and timezone information linked to existing World data.

• ip*: string (optional - auto-detects from request if not provided).

Data Sources:

1. MaxMind GeoLite2 (local database, recommended for production)
2. ip-api.com (free fallback, no setup required, 45 req/min limit)

The package automatically falls back to ip-api.com if the GeoLite2 database is not installed. For production use, we recommend downloading the GeoLite2 database:

# Get a free license key at: https://www.maxmind.com/en/geolite2/signup
php artisan world:geoip --license=YOUR_LICENSE_KEY

Or set the MAXMIND_LICENSE_KEY environment variable and run:

php artisan world:geoip

To disable the fallback API, set WORLD_GEOLOCATE_FALLBACK_API=false in your .env file.

Usage:

use Nnjeim\World\World;

// Auto-detect IP from request
$action = World::geolocate();

// Geolocate specific IP
$action = World::geolocate(['ip' => '8.8.8.8']);

if ($action->success) {
    $location = $action->data;
    // $location['country'], $location['state'], $location['city'], etc.
}

How IP Detection Works:

The client IP is automatically detected from request headers in this order:

1. CF-Connecting-IP (Cloudflare)
2. X-Forwarded-For (Standard proxy header)
3. X-Real-IP (Nginx proxy)
4. CLIENT-IP (Generic)
5. Laravel's request()->ip() fallback

Response Format:

{
  "success": true,
  "message": "geolocations",
  "data": {
    "ip": "8.8.8.8",
    "country": {
      "id": 236,
      "iso2": "US",
      "iso3": "USA",
      "name": "United States",
      "phone_code": "1",
      "region": "Americas",
      "subregion": "Northern America"
    },
    "state": {
      "id": 4808,
      "name": "Virginia",
      "state_code": "VA"
    },
    "city": {
      "id": 147562,
      "name": "Ashburn"
    },
    "coordinates": {
      "latitude": 39.03,
      "longitude": -77.5,
      "accuracy_radius": null
    },
    "timezone": {
      "id": 404,
      "name": "America/New_York"
    },
    "postal_code": "20149"
  },
  "response_time": "690 ms"
}

Note: The id fields link to existing records in the World database tables. If a matching record is not found, the id field will be omitted and only the raw geolocation data will be returned.

Available API routes

All routes can be prefixed by any string. Ex.: admin, api...

Countries

States

Cities

Timezones

Currencies

Languages

Geolocate

Localization

The available locales are

ar, az, bn, br, de, en, es, fa, fr, hr, hu, hy, it, ja, kr, ne, nl, pl, pt, ro, ru, sw, tr and zh.

The default locale is en.

Header option

accept-language=locale

Alternatively, you can use specific locale with the World Facade setLocale('locale') helper method. Example:

World::setLocale('zh')->countries();

Schema

Configuration

The configuration for the World package is located in the world.php file.
If you're upgrading from a previous version, you may want to re-publish the config file:

php artisan vendor:publish --tag=world --force

Customizing database connection

By default, this package uses the default database connection, but it's possible to customize it using the WORLD_DB_CONNECTION variable in your .env file.

Cache control

Action results are cached by default. To disable caching globally, set:

WORLD_CACHE_ENABLED=false

You can override the configured default for one action call:

World::withoutCaching()->countries();
World::withCaching()->countries();

The override is reset after that action. Cache keys include Laravel's active locale, so localized results are stored separately.

Countries restrictions

Countries can be restricted while seeding the database either by adding the ISO2 country codes in the allowed_countries or disallowed_countries array lists.

Supported Locales

A list of the accepted locales which relate to the localized lang/ files.

Modules enablement

The states, cities, timezones, currencies and languages modules can be optionally disabled.
Please note that the cities module depends on the states module.

Routes

If you don't wish to use the packages as an API service, you can disable all the routes by assigning false to routes.

Migrations

It offers the ability to enable or disable the database fields.
When changing this configuration the database should be dropped and the seeder should be re-run.

Requirements

• PHP 8.1 or newer
• Laravel 10, 11, 12, or 13

Testing

The test suite is self-contained and uses an in-memory SQLite database:

composer install # installs the package dev dependencies
composer test