The World is a Laravel package which provides a list of the countries, states, cities, timezones, currencies and languages.

It can be consumed with the World Facade or the defined API routes.

set APP_ENV=local
composer require nnjeim/world

set the ENV variable WORLD_DB_CONNECTION to the desired database connection (optional)

The world:install command is a helper to automate the installation process

php artisan world:install

Optionally you can manually install the package by following the below steps:

php artisan vendor:publish --tag=world

php artisan migrate

php artisan db:seed --class=WorldSeeder # (requires ~15min)

• Tested with Laravel 11 and php 8.4
• Minor code improvements

Please read CHANGELOG for more information of what was changed recently.

Please read CONTRIBUTING for more details.

Examples
https://laravel-world.com/api/countries
https://laravel-world.com/api/countries?search=rom
https://laravel-world.com/api/states?filters[country_code]=RO&fields=cities

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

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

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 

An action response is formed as below:

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

• fields*: comma seperated 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.

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

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

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

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

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

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

The available locales are ar, bn, br, de, en, es, fr, it, ja, kr, nl, pl, pt, ro, ru, tr and zh.
The default locale is en.

Include in the request header:

accept-language=locale

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

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

The configuration of the world package is in the world.php config file.
If you are upgrading from a previous version, you should consider re-publishing the file by issuing:

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

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.

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

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

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

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

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

• The database is seeded.
• The database connection is defined in the .env file.

Browse to the package root folder and run:

composer install # installs the package dev dependencies
composer test

* optional