PHPackages                             stellarwhale/world - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Localization & i18n](/categories/localization)
4. /
5. stellarwhale/world

ActiveLaravel-package[Localization & i18n](/categories/localization)

stellarwhale/world
==================

Laravel countries, states, cities and currencies

v1.0.2(3mo ago)06MITPHPPHP >=7.4

Since Jan 26Pushed 3mo agoCompare

[ Source](https://github.com/stellarwhale/world)[ Packagist](https://packagist.org/packages/stellarwhale/world)[ Docs](https://github.com/stellarwhale/world.git)[ RSS](/packages/stellarwhale-world/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (2)Versions (4)Used By (0)

[![Laravel world](./logo.jpg)](./logo.jpg)

[![Total Downloads](https://camo.githubusercontent.com/b9bf1746b1d0d31dcb23c07dabd205783f98c03391d4b935b9f8559a04778639/68747470733a2f2f706f7365722e707567782e6f72672f7374656c6c61727768616c652f776f726c642f642f746f74616c2e737667)](https://packagist.org/packages/stellarwhale/world)[![Latest Stable Version](https://camo.githubusercontent.com/23facf03b6063ef3d8d802930db9e6e6d99316920c49f81552eebeb47560fe37/68747470733a2f2f706f7365722e707567782e6f72672f7374656c6c61727768616c652f776f726c642f762f737461626c652e737667)](https://packagist.org/packages/stellarwhale/world)[![License](https://camo.githubusercontent.com/236ee602be0edc64c13ae1ff0799b9cae6b9535d6fd090a10e0d819ae89d248d/68747470733a2f2f706f7365722e707567782e6f72672f7374656c6c61727768616c652f776f726c642f6c6963656e73652e737667)](https://packagist.org/packages/stellarwhale/world)

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 the **World Facade** or through defined API routes.

Table of Contents
-----------------

[](#table-of-contents)

- [Installation](#installation)
    - [Automated Installation](#automated-installation)
    - [Manual Installation](#manual-installation)
- [What's New in v1.1.36](#whats-new-in-v1136-)
- [Changelog](#changelog)
- [Contributing](#contributing)
- [Examples](#examples)
- [Usage](#usage)
    - [List All Countries](#list-all-countries)
    - [Fetch Country with States & Cities](#fetch-country-with-states--cities)
    - [List All Cities by Country ID](#list-all-cities-by-country-id)
- [Available Actions](#available-actions)
- [Available API Routes](#available-api-routes)
    - [Countries](#countries)
    - [States](#states)
    - [Cities](#cities)
    - [Timezones](#timezones)
    - [Currencies](#currencies)
    - [Languages](#languages)
- [Localization](#localization)
- [Schema](#schema)
- [Configuration](#configuration)
- [Testing](#testing)
-

### Installation

[](#installation)

First, set your application environment to local:

```
set APP_ENV=local
```

Then, install the package via composer:

```
composer require stellarwhale/world

```

Optionally, set the WORLD\_DB\_CONNECTION environment variable to your desired database connection.

#### Automated Installation

[](#automated-installation)

Run the following Artisan command to automate the installation process:

```
php artisan world:install

```

#### Manual Installation

[](#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
```

2. Run the migrations:

```
php artisan migrate
```

3. Seed the database:

```
php artisan db:seed --class=WorldSeeder
```

### Upgrading

[](#upgrading)

If you're upgrading from a previous version, you may want to re-publish the config file:

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

### What's new in v1.1.36?

[](#whats-new-in-v1136)

- added Armenian locale support by @vahan
- added Nepali locale support by @sagautam5
- added Sawahili locale support by @ludanadeodatus
- Available php memory check by @sorrowflufloyd

### Changelog

[](#changelog)

For detailed information on recent changes, please see the [CHANGELOG](CHANGELOG.md).

### Contributing

[](#contributing)

We welcome contributions! For details on how to get started, please review our [CONTRIBUTING](CONTRIBUTING.md) guidlines.

Examples
--------

[](#examples)

Explore the API examples on our live site:

List all countries: Search for a country: Get states by country code: [https://world.bmbc.cloud/api/states?filters\[country\_code\]=RO&fields=cities](https://world.bmbc.cloud/api/states?filters%5Bcountry_code%5D=RO&fields=cities)

### Usage

[](#usage)

#### List all the countries

[](#list-all-the-countries)

Use the `World` facade:

```
use StellarWhale\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.

[](#fetch-a-country-with-its-states-and-cities)

Use the `World` facade:

```
use StellarWhale\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

[](#list-all-the-cities-by-country-id)

```
use StellarWhale\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

[](#available-actions)

NameDescriptioncountrieslists all the world countriesstateslists all the statescitieslists all the citiestimezoneslists all the timezonescurrencieslists all the currencieslanguageslists all the languagesAn action response is formed as below:

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

#### Countries action

[](#countries-action)

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

#### States action

[](#states-action)

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

#### Cities action

[](#cities-action)

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

#### Timezones action

[](#timezones-action)

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

#### Currencies action

[](#currencies-action)

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

#### Languages action

[](#languages-action)

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

### Available API routes

[](#available-api-routes)

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

#### Countries

[](#countries)

MethodGETRoute`/{prefix}/countries`Parameters\*comma seperated fields (countries table fields in addition to states, cities, currency and timezones), array filters, string searchExample`/api/countries?fields=iso2,cities&filters[phone_code]=44  `responsesuccess, message, data#### States

[](#states)

MethodGETRoute`/{prefix}/states`Parameters\*comma seperated fields (states table fields in addition to country and cities), array filters, string searchExample`/api/states?fields=country,cities&filters[country_code]=RO`responsesuccess, message, data#### Cities

[](#cities)

MethodGETRoute`/{prefix}/cities`Parameters\*comma seperated fields (cities table fields in addition to country and state), array filters, string searchExample`/api/cities?fields=country,state&filters[country_code]=RO`responsesuccess, message, data#### Timezones

[](#timezones)

MethodGETRoute`/{prefix}/timezones`Parameters\*comma seperated fields (timezones table fields in addition to the country), array filters, string searchExample`/api/timezones?fields=country&filters[country_code]=RO`responsesuccess, message, data#### Currencies

[](#currencies)

MethodGETRoute`/{prefix}/currencies`Parameters\*comma seperated fields (currencies table fields in addition to the country), array filters, string searchExample`/api/currencies?fields=code&filters[country_code]=RO`responsesuccess, message, data#### Languages

[](#languages)

MethodGETRoute`/{prefix}/languages`Parameters\*comma seperated fields, string searchExample`/api/languages?fields=dir`responsesuccess, message, data### Localization

[](#localization)

The available locales are

```
ar, az, bn, br, de, en, es, fr, 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

[](#schema)

[![](./schema.jpg)](./schema.jpg)

### Configuration

[](#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

[](#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.

### Countries restrictions

[](#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

[](#supported-locales)

A list of the accepted locales which relate to the localized [`lang/` files](/resources/lang).

#### Modules enablement

[](#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

[](#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

[](#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.

### Testing

[](#testing)

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`

###  Health Score

35

—

LowBetter than 80% of packages

Maintenance79

Regular maintenance activity

Popularity5

Limited adoption so far

Community19

Small or concentrated contributor base

Maturity36

Early-stage or recently created project

 Bus Factor1

Top contributor holds 66.7% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~2 days

Total

3

Last Release

109d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/123b3154152346b47b7116d3bcc555fdfdae7820fe305bc096045c78835db5b8?d=identicon)[yangcaiop](/maintainers/yangcaiop)

---

Top Contributors

[![nnjeim](https://avatars.githubusercontent.com/u/78922079?v=4)](https://github.com/nnjeim "nnjeim (110 commits)")[![rinodrummer](https://avatars.githubusercontent.com/u/6603220?v=4)](https://github.com/rinodrummer "rinodrummer (9 commits)")[![mbanusic](https://avatars.githubusercontent.com/u/694907?v=4)](https://github.com/mbanusic "mbanusic (3 commits)")[![aeq-dev](https://avatars.githubusercontent.com/u/81385994?v=4)](https://github.com/aeq-dev "aeq-dev (3 commits)")[![elnurvl](https://avatars.githubusercontent.com/u/7970970?v=4)](https://github.com/elnurvl "elnurvl (3 commits)")[![emiliopedrollo](https://avatars.githubusercontent.com/u/6577541?v=4)](https://github.com/emiliopedrollo "emiliopedrollo (3 commits)")[![Ivanshamir](https://avatars.githubusercontent.com/u/29983451?v=4)](https://github.com/Ivanshamir "Ivanshamir (3 commits)")[![yangcaiop](https://avatars.githubusercontent.com/u/37070477?v=4)](https://github.com/yangcaiop "yangcaiop (3 commits)")[![kminek](https://avatars.githubusercontent.com/u/373962?v=4)](https://github.com/kminek "kminek (3 commits)")[![ades4827](https://avatars.githubusercontent.com/u/27701869?v=4)](https://github.com/ades4827 "ades4827 (2 commits)")[![DevNull-IR](https://avatars.githubusercontent.com/u/97373457?v=4)](https://github.com/DevNull-IR "DevNull-IR (2 commits)")[![gdevlugt](https://avatars.githubusercontent.com/u/1107080?v=4)](https://github.com/gdevlugt "gdevlugt (2 commits)")[![ludanadeodatus](https://avatars.githubusercontent.com/u/91781189?v=4)](https://github.com/ludanadeodatus "ludanadeodatus (2 commits)")[![sagautam5](https://avatars.githubusercontent.com/u/10434281?v=4)](https://github.com/sagautam5 "sagautam5 (2 commits)")[![VahanMargaryan](https://avatars.githubusercontent.com/u/176320?v=4)](https://github.com/VahanMargaryan "VahanMargaryan (2 commits)")[![misusonu18](https://avatars.githubusercontent.com/u/52093984?v=4)](https://github.com/misusonu18 "misusonu18 (1 commits)")[![mrmmg](https://avatars.githubusercontent.com/u/30490118?v=4)](https://github.com/mrmmg "mrmmg (1 commits)")[![cloudchristoph](https://avatars.githubusercontent.com/u/204027?v=4)](https://github.com/cloudchristoph "cloudchristoph (1 commits)")[![OzanKurt](https://avatars.githubusercontent.com/u/8682003?v=4)](https://github.com/OzanKurt "OzanKurt (1 commits)")[![parth391](https://avatars.githubusercontent.com/u/4966579?v=4)](https://github.com/parth391 "parth391 (1 commits)")

---

Tags

laravellumencountriesstatescurrenciestimezonescities

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/stellarwhale-world/health.svg)

```
[![Health](https://phpackages.com/badges/stellarwhale-world/health.svg)](https://phpackages.com/packages/stellarwhale-world)
```

###  Alternatives

[nnjeim/world

Laravel countries, states, cities, currencies, languages and IP geolocation

970361.2k3](/packages/nnjeim-world)[pragmarx/countries

PHP Countries and Currencies

1.9k3.3M18](/packages/pragmarx-countries)[pragmarx/countries-laravel

Countries for Laravel

1471.1M2](/packages/pragmarx-countries-laravel)[pharaonic/laravel-locations

Laravel - Countries\[States/Cities, Currency, Phone Code, Languages, Capital\] & Continents & Timezones.

102.4k1](/packages/pharaonic-laravel-locations)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)