File: README.md

<p><img src="https://eu.ui-avatars.com/api/?name=Najm+Njeim?size=100" width="100"/></p>

A Laravel package to provide a list of the countries, states, cities, timezones, currencies and phone numbers formatting/validation helpers.

The package can be consumed through Facades, Helpers and Api routes.

Installation

composer require nnjeim/world

php artisan vendor:publish --tag=world

php artisan migrate

php artisan db:seed --class=WorldSeeder (requires ~ 5 - 10min)

Changelog

Please see CHANGELOG for more information what has changed recently.

Usage

World Facade

List all the countries.

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"
		},
		.
		.
		.
	],
}

Fetch a country with its states and cities.

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"
			},
			.
			.
			.
		]
	],
}

World Helper Class

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;
}

Available methods

| Name | Description | Argument* | | :--- | :--- |:--- | | countries | lists all the world countries | arraycontaining (string) fields and (array) filters* | | states | lists all the states | arraycontaining (string) fields and (array) filters* | | cities | lists all the cities | arraycontaining (string) fields and (array) filters* | | timezones | lists all the timezones | arraycontaining (string) fields and (array) filters* | | currencies | lists all the currencies | arraycontaining (string) fields and (array) filters* |

The methods' return is structured as below:

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

Countries method

• fields*: comma seperated string(countries table fields in addition to states, cities, currency and timezones).
• filters*: array of keys(countries table fields) and their correspondant values.

States method

• fields*: comma seperated string(states table fields in addition to country and states).
• filters*: array of keys(states table fields) and their correspondant values.

Cities method

• fields*: comma seperated string(cities table fields in addition to country and state).
• filters*: array of keys(cities table fields) and their correspondant values.

Timezones method

• fields*: comma seperated string(timezones table fields in addition to country).
• filters*: array of keys(timezones table fields) and their correspondant values.

Currencies method

• fields*: comma seperated string(currencies table fields in addition to country).
• filters*: array of keys(currencies table fields) and their correspondant values.

Available routes

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

Countries

| | | | :--- | :--- | | Method | GET | | Route | /{prefix}/countries | | Parameters* | comma seperated fields(countries table fields in addition to states, cities, currency and timezones), array filters | | Example | /v1/countries?fields=iso2,cities&filters[phone_code]=44 | | response | success, message, data |

States

| | | | :--- | :--- | | Method | GET | | Route | /{prefix}/states | | Parameters* | comma seperated fields(states table fields in addition to country and cities), array filters | | Example | /v1/states?fields=country,cities&filters[country_id]=182 | | response | success, message, data |

Cities

| | | | :--- | :--- | | Method | GET | | Route | /{prefix}/cities | | Parameters* | comma seperated fields(states table fields in addition to country and state), array filters | | Example | /v1/cities?fields=country,state&filters[country_id]=182 | | response | success, message, data |

Timezones

| | | | :--- | :--- | | Method | GET | | Route | /{prefix}/timezones | | Parameters* | comma seperated fields(states table fields in addition to the country), array filters | | Example | /v1/timezones?fields=country&filters[country_id]=182 | | response | success, message, data |

Currencies

| | | | :--- | :--- | | Method | GET | | Route | /{prefix}/timezones | | Parameters* | comma seperated fields(states table fields in addition to the country), array filters | | Example | /v1/timezones?fields=country&filters[country_id]=182 | | response | success, message, data |

Validate Number

| | | | :--- | :--- | | Method | POST | | Route | /{prefix}/phones/validate | | Parameters | key, value | | Example | /v1/phones/validate?number=060550987&phone_code=33 |

Strip Number

| | | | :--- | :--- | | Method | POST | | Route | /{prefix}/phones/strip | | Parameters | key, value | | Example | /v1/phones/strip?number=060550987&phone_code=33 |

Format Number

| | | | :--- | :--- | | Method | POST | | Route | /{prefix}/phones/format | | Parameters | key, value | | Example | /v1/phones/format?number=060550987&phone_code=33 |

Helpers

formatNumber($number, $phone_code = null);

ex. formatNumber('06 78 909 876', '33')   returns +33 67 890 9876

stripNumber($number, $phone_code = null);

ex. stripNumber('06 78 909 876', '33') return 33678909876

if the argument $phone_code is not passed to the helpers, the used dialling code would be taken from

config('world.default_phone_code') 

Localization

The available locales are ar, 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

Schema

<p><img src="./schema.jpg" width="600px"/></p>

Countries database table fields

id, name, iso2, iso3, phone_code, dialling_pattern, region, sub_region, status

States database table fields

id, name, country_id

Cities database table fields

id, name, state_id, country_id

Timezones database table fields

id, name, country_id

Currencies database table fields

id, country_id, name, code, precision, symbol, symbol_native, symbol_first, decimal_mark, thousands_separator

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