emiliopedrollo / world
Laravel countries, states, cities and currencies
Installs: 8
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 2
Forks: 104
Type:laravel-package
Requires
- php: >=7.4
Requires (Dev)
- orchestra/testbench: >=v4.0.0
- phpunit/phpunit: >=8.5.8
Replaces
- nnjeim/world: ~1.1
README
The World is a Laravel package which provides a list of the countries, states, cities, timezones, currencies and languages.
It can be consumed with the World Facade or the defined Api routes.
Installation
composer require nnjeim/world
php artisan vendor:publish --tag=world
php artisan migrate
php artisan db:seed --class=WorldSeeder (requires ~15min)
Upgrading to v1.1.6?
- Re-publish the package assets by issuing the command
php artisan vendor:publish --tag=world --force
- If needed, customize the table names and enable or disabled the optional database fields in the
world.php
config file.
Changelog
Please read CHANGELOG for more information of what was changed recently.
Contributing
Please read CONTRIBUTING for more details.
Demo
Please feel free to query https://laravel-world.com
Examples
https://laravel-world.com/api/countries
https://laravel-world.com/api/states?filters[country_id]=182&fields=cities
Usage
List all the countries.
Use the World facade
use Nnjeim\World\World;
$action = World::countries();
if ($action->success) {
$countries = $action->data;
}
response
{
"success": true,
"message": "countries",
"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.
Use the World facade
use Nnjeim\World\World;
$action = World::countries([
'fields' => 'states,cities',
'filters' => [
'iso2' => 'FR',
]
]);
if ($action->success) {
$countries = $action->data;
}
response
{
"success": true,
"message": "countries",
"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.
use Nnjeim\World\WorldHelper;
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_id]=182
Available actions
An action response is formed as below:
- success (boolean)
- message (string)
- data (instance of Illuminate\Support\Collection)
- errors (array)
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.
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.
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.
Timezones action
- fields*: comma seperated string(timezones table fields in addition to country).
- filters*: array of keys(timezones table fields) and their corresponding values.
Currencies action
- fields*: comma seperated string(currencies table fields in addition to country).
- filters*: array of keys(currencies table fields) and their corresponding values.
Languages action
- fields*: comma seperated string(languages table fields).
- filters*: array of keys(languages table fields) and their corresponding values.
Available Api routes
All routes can be prefixed by any string. Ex admin, api, api ...
Countries
States
Cities
Timezones
Currencies
Languages
Localization
The available locales are ar, bn, br, de, en, es, fr, ja, kr, pl, pt, ro, ru and zh.
The default locale is en.
Include in the request header
accept-language=locale
Alternativley, you can use specific locale with the World
Facade setLocale('locale')
helper method. Example:
World::setLocale('zh')->countries();
Schema
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