PHPackages                             pollsar/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. [Utility & Helpers](/categories/utility)
4. /
5. pollsar/world

ActiveLaravel-package[Utility & Helpers](/categories/utility)

pollsar/world
=============

Laravel countries, states, cities and currencies

04PHP

Since Jul 14Pushed 10mo agoCompare

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

READMEChangelogDependenciesVersions (1)Used By (0)

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

[![Total Downloads](https://camo.githubusercontent.com/27cb291d62781b1963114a4e700d10368c30e9159f92b9f49c0454bcf658756e/68747470733a2f2f706f7365722e707567782e6f72672f6e6e6a65696d2f776f726c642f642f746f74616c2e737667)](https://packagist.org/packages/nnjeim/world)[![Latest Stable Version](https://camo.githubusercontent.com/75c93cae7360fb388672d8ac4572f286ccfae7a8b0ac8e38f0053557b3d0d759/68747470733a2f2f706f7365722e707567782e6f72672f6e6e6a65696d2f776f726c642f762f737461626c652e737667)](https://packagist.org/packages/nnjeim/world)[![License](https://camo.githubusercontent.com/8a1ec6173b40774ed489a3ff55fc6f413ca93d7e07ebc5e8d3b11e1f4d461f57/68747470733a2f2f706f7365722e707567782e6f72672f6e6e6a65696d2f776f726c642f6c6963656e73652e737667)](https://packagist.org/packages/nnjeim/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.35](#whats-new-in-v1135)
- [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 nnjeim/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.35?

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

- Addition of the azerbaijani localization by @elnurvl.

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

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

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

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

17

—

LowBetter than 6% of packages

Maintenance39

Infrequent updates — may be unmaintained

Popularity3

Limited adoption so far

Community17

Small or concentrated contributor base

Maturity14

Early-stage or recently created project

 Bus Factor1

Top contributor holds 69.8% 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.

### Community

Maintainers

![](https://www.gravatar.com/avatar/3d43fff3afc9e2255cdfde4a3cbf523b1267d223489cd75bf489cf5f4c2a5c9e?d=identicon)[Fastleo](/maintainers/Fastleo)

---

Top Contributors

[![nnjeim](https://avatars.githubusercontent.com/u/78922079?v=4)](https://github.com/nnjeim "nnjeim (104 commits)")[![rinodrummer](https://avatars.githubusercontent.com/u/6603220?v=4)](https://github.com/rinodrummer "rinodrummer (9 commits)")[![kminek](https://avatars.githubusercontent.com/u/373962?v=4)](https://github.com/kminek "kminek (3 commits)")[![mbanusic](https://avatars.githubusercontent.com/u/694907?v=4)](https://github.com/mbanusic "mbanusic (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)")[![aeq-dev](https://avatars.githubusercontent.com/u/81385994?v=4)](https://github.com/aeq-dev "aeq-dev (3 commits)")[![Ivanshamir](https://avatars.githubusercontent.com/u/29983451?v=4)](https://github.com/Ivanshamir "Ivanshamir (3 commits)")[![Camanru](https://avatars.githubusercontent.com/u/484042?v=4)](https://github.com/Camanru "Camanru (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)")[![ades4827](https://avatars.githubusercontent.com/u/27701869?v=4)](https://github.com/ades4827 "ades4827 (2 commits)")[![waadmawlood](https://avatars.githubusercontent.com/u/44348636?v=4)](https://github.com/waadmawlood "waadmawlood (1 commits)")[![AhmedElTabarani](https://avatars.githubusercontent.com/u/69223584?v=4)](https://github.com/AhmedElTabarani "AhmedElTabarani (1 commits)")[![cloudchristoph](https://avatars.githubusercontent.com/u/204027?v=4)](https://github.com/cloudchristoph "cloudchristoph (1 commits)")[![marc31](https://avatars.githubusercontent.com/u/14980392?v=4)](https://github.com/marc31 "marc31 (1 commits)")[![mefenlon](https://avatars.githubusercontent.com/u/30707325?v=4)](https://github.com/mefenlon "mefenlon (1 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)")[![OzanKurt](https://avatars.githubusercontent.com/u/8682003?v=4)](https://github.com/OzanKurt "OzanKurt (1 commits)")

### Embed Badge

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

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

###  Alternatives

[symfony/type-info

Extracts PHP types information.

19951.9M114](/packages/symfony-type-info)[axllent/silverstripe-cms-tweaks

Several CMS usability improvements

1826.2k1](/packages/axllent-silverstripe-cms-tweaks)

PHPackages © 2026

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