{"id":22030949,"url":"https://github.com/nnjeim/world","last_synced_at":"2025-05-15T04:06:32.117Z","repository":{"id":39492204,"uuid":"420875841","full_name":"nnjeim/world","owner":"nnjeim","description":"A Laravel package which provides a list of the countries, states, cities, currencies, timezones and languages.","archived":false,"fork":false,"pushed_at":"2025-05-14T10:38:22.000Z","size":12122,"stargazers_count":909,"open_issues_count":5,"forks_count":124,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-05-14T11:47:37.347Z","etag":null,"topics":["cities","countries","countries-api","country","currencies","language","languages","laravel","laravel-package","states","timezones"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nnjeim.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-10-25T04:19:03.000Z","updated_at":"2025-05-14T10:36:45.000Z","dependencies_parsed_at":"2023-02-08T06:46:11.261Z","dependency_job_id":"7a1a5880-4247-42b0-85c7-5b4e76c95559","html_url":"https://github.com/nnjeim/world","commit_stats":{"total_commits":74,"total_committers":10,"mean_commits":7.4,"dds":"0.32432432432432434","last_synced_commit":"487c66aff67db3ad3e96b626dd79071f00098eb9"},"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nnjeim%2Fworld","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nnjeim%2Fworld/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nnjeim%2Fworld/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nnjeim%2Fworld/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nnjeim","download_url":"https://codeload.github.com/nnjeim/world/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254161345,"owners_count":22024741,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cities","countries","countries-api","country","currencies","language","languages","laravel","laravel-package","states","timezones"],"created_at":"2024-11-30T08:12:35.126Z","updated_at":"2025-05-15T04:06:27.104Z","avatar_url":"https://github.com/nnjeim.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp style=\"text-align: center; padding: 3rem;\"\u003e\u003cimg src=\"./logo.jpg\" width=\"150\" alt=\"Laravel world\"/\u003e\u003c/p\u003e\n\nThe 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.\n\n## Table of Contents\n\n- [Installation](#installation)\n  - [Automated Installation](#automated-installation)\n  - [Manual Installation](#manual-installation)\n- [What's New in v1.1.34](#whats-new-in-v1134)\n- [Changelog](#changelog)\n- [Contributing](#contributing)\n- [Examples](#examples)\n- [Usage](#usage)\n  - [List All Countries](#list-all-countries)\n  - [Fetch Country with States \u0026 Cities](#fetch-country-with-states--cities)\n  - [List All Cities by Country ID](#list-all-cities-by-country-id)\n- [Available Actions](#available-actions)\n- [Available API Routes](#available-api-routes)\n  - [Countries](#countries)\n  - [States](#states)\n  - [Cities](#cities)\n  - [Timezones](#timezones)\n  - [Currencies](#currencies)\n  - [Languages](#languages)\n- [Localization](#localization)\n- [Schema](#schema)\n- [Configuration](#configuration)\n- [Testing](#testing)\n- \n### Installation\n\nFirst, set your application environment to local:\n\n```bash\nset APP_ENV=local\n```\n\nThen, install the package via composer:\n\n```\ncomposer require nnjeim/world\n```\n\nOptionally, set the WORLD_DB_CONNECTION environment variable to your desired database connection.\n\n#### Automated Installation\n\nRun the following Artisan command to automate the installation process:\n\n```\nphp artisan world:install\n```\n#### Manual Installation\nIf you prefer to install the package manually, follow these steps:\n\n1. Publish the package configuration file:\n\n```bash\nphp artisan vendor:publish --tag=world --force\n```\n2. Run the migrations:\n\n```bash\nphp artisan migrate \n```\n3. Seed the database:\n\n```bash\nphp artisan db:seed --class=WorldSeeder\n````\n\n### What's new in v1.1.34?  \n- Tested with Laravel 11 and php 8.3/8.4\n- Tested with Laravel 12 and php 8.3/8.4\n- Minor code improvements\n\n### Changelog\n\nFor detailed information on recent changes, please see the [CHANGELOG](CHANGELOG.md).\n\n### Contributing\n\nWe welcome contributions! For details on how to get started, please review our [CONTRIBUTING](CONTRIBUTING.md) guidlines.\n  \nExamples  \n--------\nExplore the API examples on our live site:\n\nList all countries:  \nhttps://laravel-world.com/api/countries  \nSearch for a country:   \nhttps://laravel-world.com/api/countries?search=rom  \nGet states by country code:  \nhttps://laravel-world.com/api/states?filters[country_code]=RO\u0026fields=cities  \n\n### Usage\n\n#### List all the countries\n\nUse the `World` facade:\n\n```php\nuse Nnjeim\\World\\World;\n\n$action =  World::countries();\n\nif ($action-\u003esuccess) {\n  $countries = $action-\u003edata;\n}\n\nresponse (object)\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": 1,\n      \"name\": \"Afghanistan\"\n    },\n    {\n      \"id\": 2,\n      \"name\": \"Åland Islands\"\n    },\n    .\n    .\n    .\n  ],\n}\n``` \n\nUse the API countries endpoint:\n\n```\nhttps://myDomain.local/api/countries\n```\n\n#### Fetch a country with its states and cities.\n\nUse the `World` facade:\n\n```php\nuse Nnjeim\\World\\World;\n\n$action =  World::countries([\n\t'fields' =\u003e 'states,cities',\n\t'filters' =\u003e [\n\t\t'iso2' =\u003e 'FR',\n\t]\n]);\n\nif ($action-\u003esuccess) {\n\n\t$countries = $action-\u003edata;\n}\n```\n\nResponse: \n```\n(object)\n{\n  \"success\": true,\n  \"data\": [\n    \"id\": 77,\n    \"name\": \"France\",\n    \"states\": [\n        {\n          \"id\": 1271,\n          \"name\": \"Alo\"\n        },\n        {\n          \"id\": 1272,\n          \"name\": \"Alsace\"\n        },\n        .\n        .\n        .\n    ],\n    \"cities\": [\n        {\n          \"id\": 25148,\n          \"name\": \"Abondance\"\n        },\n        {\n          \"id\": 25149,\n          \"name\": \"Abrest\"\n        },\n        .\n        .\n        .\n      ]\n    ],\n}\n```\n\nUse the API countries endpoint:\n\n```\nhttps://myDomain.local/api/countries?fields=states,cities\u0026filters[iso2]=FR\n```\n\n#### List all the cities by country id\n\n```php\nuse Nnjeim\\World\\WorldHelper;\n\nnew class {\n    protected $world;\n    \n    public function __construct(WorldHelper $world) {\n        $this-\u003eworld = $world;\n    }\n    \n    $action = $this-\u003eworld-\u003ecities([\n        'filters' =\u003e [\n            'country_id' =\u003e 182,\n        ],\n    ]);\n    \n    if ($action-\u003esuccess) {\n        $cities = $action-\u003edata;\n    }\n}\n```\n\nUse the API cities endpoint:\n\n```\nhttps://myDomain.local/api/cities?filters[country_code]=RO \n```\n\n### Available actions\n\n| Name       | Description                   |\n|:-----------|:------------------------------|\n| countries  | lists all the world countries |\n| states     | lists all the states          |\n| cities     | lists all the cities          |\n| timezones  | lists all the timezones       |\n| currencies | lists all the currencies      |\n| languages  | lists all the languages       |\n\nAn action response is formed as below:\n\n* `success` (boolean)\n* `message` (string)\n* `data` (instance of `Illuminate\\Support\\Collection`)\n* `errors` (array)\n\n#### Countries action\n\n* `fields`*: comma seperated string (countries table fields in addition to states, cities, currency and timezones).\n* `filters`*: array of keys (countries table fields) and their corresponding values.\n* `search`*: string.\n\n#### States action\n\n* `fields`*: comma seperated string (states table fields in addition to country and states).\n* `filters`*: array of keys (states table fields) and their corresponding values.\n* `search`*: string.\n\n#### Cities action\n\n* `fields`*: comma seperated string (cities table fields in addition to country and state).\n* `filters`*: array of keys (cities table fields) and their corresponding values.\n* `search`*: string.\n\n#### Timezones action\n\n* `fields`*: comma seperated string (timezones table fields in addition to country).\n* `filters`*: array of keys (timezones table fields) and their corresponding values.\n* `search`*: string.\n\n#### Currencies action\n\n* `fields`*: comma seperated string (currencies table fields in addition to country).\n* `filters`*: array of keys (currencies table fields) and their corresponding values.\n* `search`*: string.\n\n#### Languages action\n\n* `fields`*: comma seperated string (languages table fields).\n* `filters`*: array of keys (languages table fields) and their corresponding values.\n* `search`*: string.\n\n### Available API routes\n\nAll routes can be prefixed by any string. Ex.: `admin`, `api`...\n\n#### Countries\n\n|             |                                                                                                                                     |\n|:------------|:------------------------------------------------------------------------------------------------------------------------------------|\n| Method      | GET                                                                                                                                 |\n| Route       | `/{prefix}/countries`                                                                                                               |\n| Parameters* | comma seperated fields (countries table fields in addition to states, cities, currency and timezones), array filters, string search |\n| Example     | `/api/countries?fields=iso2,cities\u0026filters[phone_code]=44  `                                                                        |   \n| response    | success, message, data                                                                                                              |  \n\n#### States\n\n|             |                                                                                                              |\n|:------------|:-------------------------------------------------------------------------------------------------------------|\n| Method      | GET                                                                                                          |\n| Route       | `/{prefix}/states`                                                                                           |\n| Parameters* | comma seperated fields (states table fields in addition to country and cities), array filters, string search |\n| Example     | `/api/states?fields=country,cities\u0026filters[country_code]=RO`                                                 |   \n| response    | success, message, data                                                                                       |   \n\n#### Cities\n\n|             |                                                                                                             |\n|:------------|:------------------------------------------------------------------------------------------------------------|\n| Method      | GET                                                                                                         |\n| Route       | `/{prefix}/cities`                                                                                          |\n| Parameters* | comma seperated fields (cities table fields in addition to country and state), array filters, string search |\n| Example     | `/api/cities?fields=country,state\u0026filters[country_code]=RO`                                                 |   \n| response    | success, message, data                                                                                      | \n\n#### Timezones\n\n|             |                                                                                                          |\n|:------------|:---------------------------------------------------------------------------------------------------------|\n| Method      | GET                                                                                                      |\n| Route       | `/{prefix}/timezones`                                                                                    |\n| Parameters* | comma seperated fields (timezones table fields in addition to the country), array filters, string search |\n| Example     | `/api/timezones?fields=country\u0026filters[country_code]=RO`                                                 |   \n| response    | success, message, data                                                                                   | \n\n#### Currencies\n\n|             |                                                                                                           |\n|:------------|:----------------------------------------------------------------------------------------------------------|\n| Method      | GET                                                                                                       |\n| Route       | `/{prefix}/currencies`                                                                                    |\n| Parameters* | comma seperated fields (currencies table fields in addition to the country), array filters, string search |\n| Example     | `/api/currencies?fields=code\u0026filters[country_code]=RO`                                                    |   \n| response    | success, message, data                                                                                    |\n\n#### Languages\n\n|             |                                       |\n|:------------|:--------------------------------------|\n| Method      | GET                                   |\n| Route       | `/{prefix}/languages`                 |\n| Parameters* | comma seperated fields, string search |\n| Example     | `/api/languages?fields=dir`           |   \n| response    | success, message, data                |\n\n### Localization\n\nThe available locales are \n```\nar, bn, br, de, en, es, fr, it, ja, kr, nl, pl, pt, ro, ru, tr and zh.  \n```\nThe default locale is en.\n\nHeader option\n\n```\naccept-language=locale\n```\n\nAlternatively, you can use specific locale with the `World` Facade `setLocale('locale')` helper method. Example: \n\n```php\nWorld::setLocale('zh')-\u003ecountries();\n```\n\n### Schema\n\n\u003cp\u003e\u003cimg src=\"./schema.jpg\" width=\"800px\" /\u003e\u003c/p\u003e\n\n### Configuration  \nThe configuration for the World package is located in the world.php file.  \nIf you're upgrading from a previous version, you may want to re-publish the config file:\n\n```bash\nphp artisan vendor:publish --tag=world --force\n```\n\n#### Customizing database connection\n\nBy default, this package uses the default database connection, but it's possible to customize it\nusing the `WORLD_DB_CONNECTION` variable in your `.env` file.\n\n### Countries restrictions\nCountries can be restricted while seeding the database either by adding the ISO2 country codes in the `allowed_countries` or `disallowed_countries` array lists.  \n\n#### Supported Locales  \nA list of the accepted locales which relate to the localized [`lang/` files](/resources/lang).\n\n#### Modules enablement  \nThe states, cities, timezones, currencies and languages modules can be optionally disabled.    \nPlease note that the cities module depends on the states module.  \n\n#### Routes  \nIf you don't wish to use the packages as an API service, you can disable all the routes by assigning `false` to `routes`.  \n\n#### Migrations  \nIt offers the ability to enable or disable the database fields.  \nWhen changing this configuration the database should be dropped and the seeder should be re-run.  \n\n### Testing  \n\nRequirements  \n- The database is seeded.\n- The database connection is defined in the .env file. \n\nBrowse to the package root folder and run:\n\n```bash\ncomposer install # installs the package dev dependencies\ncomposer test\n```\n\n`* optional`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnnjeim%2Fworld","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnnjeim%2Fworld","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnnjeim%2Fworld/lists"}