PHPackages nnjeim/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. nnjeim/world ActiveLaravel-package[Localization & i18n](/categories/localization) nnjeim/world ============ Laravel countries, states, cities, currencies, languages and IP geolocation 1.1.38(3mo ago)970361.2k↑10.9%138[4 issues](https://github.com/nnjeim/world/issues)3MITPHPPHP >=7.4 Since Feb 8Pushed 3mo ago17 watchersCompare [ Source](https://github.com/nnjeim/world)[ Packagist](https://packagist.org/packages/nnjeim/world)[ Docs](https://github.com/nnjeim/world.git)[ RSS](/packages/nnjeim-world/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (7)Dependencies (3)Versions (10)Used By (3) [![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, languages and IP geolocation. You can access the data using the **World Facade** or through defined API routes. --- [![New: IP Geolocation](./geolocate-badge.svg)](./geolocate-badge.svg) **🌍 New in v1.1.38: IP Geolocation Module** Detect user location from IP address with automatic fallback to free API. `World::geolocate()` Β· `GET /api/geolocate` [Learn more β†’](#geolocate-action) --- Table of Contents ----------------- [](#table-of-contents) - [Installation](#installation) - [Automated Installation](#automated-installation) - [Manual Installation](#manual-installation) - [What's New in v1.1.38](#whats-new-in-v1138-) - [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) - [Geolocate](#geolocate) - [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) > **⚠️ 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.38? [](#whats-new-in-v1138) - **New Geolocate Module**: IP-based geolocation using MaxMind GeoLite2 database - Facade support: `World::geolocate()` to detect location from client IP - API endpoint: `GET /api/geolocate` with automatic IP detection from headers - Fallback to ip-api.com when GeoLite2 database is not installed (no setup required) - Automatic IP detection from proxy headers (Cloudflare, X-Forwarded-For, etc.) - Returns linked Country, State, City models with database IDs - New artisan command: `php artisan world:geoip` to download GeoLite2 database - Fixed seeder compatibility with non-seedable modules > **⚠️ Required:** After upgrading, run `php artisan vendor:publish --tag=world --force` to update your configuration file. ### 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 languagesgeolocategeolocates an IP addressAn 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. #### Geolocate action [](#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 [](#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#### Geolocate [](#geolocate) MethodGETRoute`/{prefix}/geolocate`Parameters\*ip (optional - auto-detects from request)Example`/api/geolocate` or `/api/geolocate?ip=8.8.8.8`responsesuccess, message, data (ip, country, state, city, coordinates, timezone, postal\_code)### 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 58 β€” FairBetter than 98% of packages Maintenance80 Actively maintained with recent releases Popularity61 Solid adoption and visibility Community37 Small or concentrated contributor base Maturity47 Maturing project, gaining track record Bus Factor1 Top contributor holds 69.3% 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 ~91 days Recently: every ~84 days Total 9 Last Release 103d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/8c7c0bbf68a5085c71eb582298250ac2ffe5b4a971bd4fda304a1a6e3ec3bd02?d=identicon)[nnjeim](/maintainers/nnjeim) --- Top Contributors [![nnjeim](https://avatars.githubusercontent.com/u/78922079?v=4)](https://github.com/nnjeim "nnjeim (124 commits)")[![rinodrummer](https://avatars.githubusercontent.com/u/6603220?v=4)](https://github.com/rinodrummer "rinodrummer (9 commits)")[![Ivanshamir](https://avatars.githubusercontent.com/u/29983451?v=4)](https://github.com/Ivanshamir "Ivanshamir (3 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)")[![emiliopedrollo](https://avatars.githubusercontent.com/u/6577541?v=4)](https://github.com/emiliopedrollo "emiliopedrollo (3 commits)")[![elnurvl](https://avatars.githubusercontent.com/u/7970970?v=4)](https://github.com/elnurvl "elnurvl (3 commits)")[![aeq-dev](https://avatars.githubusercontent.com/u/81385994?v=4)](https://github.com/aeq-dev "aeq-dev (3 commits)")[![ades4827](https://avatars.githubusercontent.com/u/27701869?v=4)](https://github.com/ades4827 "ades4827 (2 commits)")[![alkoumi](https://avatars.githubusercontent.com/u/10585943?v=4)](https://github.com/alkoumi "alkoumi (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)")[![mefenlon](https://avatars.githubusercontent.com/u/30707325?v=4)](https://github.com/mefenlon "mefenlon (1 commits)")[![mehedijaman](https://avatars.githubusercontent.com/u/8464835?v=4)](https://github.com/mehedijaman "mehedijaman (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)")[![alnahian2003](https://avatars.githubusercontent.com/u/61485238?v=4)](https://github.com/alnahian2003 "alnahian2003 (1 commits)") --- Tags citiescountriescountries-apicountrycurrenciesgeoipgeolocationgeolocation-apilanguagelanguageslaravellaravel-packagestatestimezoneslaravelgeoiplanguageslumengeolocationmaxmindcountriesstatescurrenciestimezonescitiesip-location ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/nnjeim-world/health.svg) ``` [![Health](https://phpackages.com/badges/nnjeim-world/health.svg)](https://phpackages.com/packages/nnjeim-world) ``` ### Alternatives [pragmarx/countries PHP Countries and Currencies 1.9k3.3M18](/packages/pragmarx-countries)[pragmarx/countries-laravel Countries for Laravel 1471.1M2](/packages/pragmarx-countries-laravel)[juanparati/iso-codes A PHP library that provides ISO codes, currencies, languages, timezones and additional geopolitical information 17146.4k](/packages/juanparati-iso-codes)[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)