Repository files navigation

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

• Installation
  • Automated Installation
  • Manual Installation
• What's New in v1.1.34
• 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
• Localization
• Schema
• Configuration
• Testing

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.

Run the following Artisan command to automate the installation process:

php artisan world:install

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

1. Publish the package configuration file:

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

2. Run the migrations:

php artisan migrate

3. Seed the database:

php artisan db:seed --class=WorldSeeder

• Tested with Laravel 11 and php 8.3/8.4
• Tested with Laravel 12 and php 8.3/8.4
• Minor code improvements

For detailed information on recent changes, please see theCHANGELOG.

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

Explore the API examples on our live site:

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

Use theWorld facade:

useNnjeim\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 theWorld facade:

useNnjeim\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

useNnjeim\World\WorldHelper;newclass {protected$world;publicfunction__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 ofIlluminate\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.

Header option

accept-language=locale

Alternatively, you can use specific locale with theWorld FacadesetLocale('locale') helper method. Example:

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

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

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

Countries can be restricted while seeding the database either by adding the ISO2 country codes in theallowed_countries ordisallowed_countries array lists.

A list of the accepted locales which relate to the localizedlang/ 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 assigningfalse toroutes.

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 dependenciescomposertest

* optional