A Laravel package providing a list of the countries, states, cities, currencies and timezones

Related tags

Laravel laravel countries laravel-package states cities currencies timezones countries-api
Overview

A Laravel package to provide a list of the countries, 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)

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 array* containing (string) fields* and (array) filters*
states lists all the states array* containing (string) fields* and (array) filters*
cities lists all the cities array* containing (string) fields* and (array) filters*
timezones lists all the timezones array* containing (string) fields* and (array) filters*
currencies lists all the currencies array* containing (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

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 test

Changelog

Please see CHANGELOG for more information what has changed recently.

* optional

Comments
  • Make routes optional

    Make routes optional

    Honestly I don't think it makes sense on a package like that to define routes. Maybe I'm just misunderstanding what this project is supposed to be.

    Relates to #16.

    opened by emiliopedrollo 7
  • Lang directory path changed

    Lang directory path changed

    when i run php artisan vendor:publish --tag=world the lang directory goes under resources but after laravel 9 it should be in the root this make bug of all trans or __() not working unless i deleted resources/lang

    help wanted 
    opened by a-j-na 6
  • Question about the SeedAction

    Question about the SeedAction

    Is there a reason that you removed the fields before you seeded the database?

    $this->forgetFields($countryFields, ['id']);

    I find this completed redundant since the ids in the json resource match already.

    opened by OzanKurt 5
  • Add ability to load only some countries based on config loadedCountries

    Add ability to load only some countries based on config loadedCountries

    Is your feature request related to a problem? Please describe. No

    Describe the solution you'd like Sometimes we may need only some countries for our application, so no need to insert the whole World DB, and later we may append other countries

    opened by aeq-dev 5
  • Contribute to the project

    Contribute to the project

    I want to contribute to the project. I've some implementations that I want to share.

    First of all, the origin of the data, I think that you get the data from https://www.geonames.org/, is correct?

    I've some projects where I use geonames, I know its database structure very well.

    I'd like to add to your world project more admin levels, including more villages, not only cities.

    I also have support for coordinates and geospatial searches, nearest cities from x for example.

    Are you interested in these features?

    enhancement 
    opened by robertosanval 4
  • cannot migrate on first install

    cannot migrate on first install

    hi i just stated to download package and do install iam still on laravel 8 i got this message

    php artisan migrate Migrating: 2020_07_07_055656_create_countries_table

    ErrorException

    foreach() argument must be of type array|object, null given

    at vendor/nnjeim/world/src/Database/Migrations/2020_07_07_055656_create_countries_table.php:22 18▕ $table->string('iso2', 2); 19▕ $table->string('name'); 20▕ $table->tinyInteger('status')->default(1); 21▕ ➜ 22▕ foreach (config('world.migrations.countries.optional_fields') as $field => $value) { 23▕ if ($value['required']) { 24▕ $table->string($field, $value['length'] ?? null); 25▕ } 26▕ }

      +27 vendor frames

    28 artisan:37 Illuminate\Foundation\Console\Kernel::handle(Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))

    Process finished with exit code 1.

    this might be related to the other issue today - please have a look

    help wanted 
    opened by rogerad 4
  • Stuck at 40%, I see some countries are not seeded.

    Stuck at 40%, I see some countries are not seeded.

    Describe the bug A clear and concise description of what the bug is.

    To Reproduce Steps to reproduce the behaviour:

    1. Go to 'Terminal'
    2. Click on 'Run db:seed'
    3. After waiting for 2 minutes
    4. See error 'Stuck at 40%, I see some countries are not seeded.'

    Seeding start

    101/250 [▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░░░░░░░░] 40%

    Expected behaviour A clear and concise description of what you expected to happen.

    Screenshots If applicable, add screenshots to help explain your problem.

    Desktop (please complete the following information):

    • OS: [e.g. iOS]
    • Browser [e.g. chrome, safari]
    • Version [e.g. 22]

    Smartphone (please complete the following information):

    • Device: [e.g. MacBook]
    • OS: [e.g. MacOS Monterey]
    • Terminal [e.g. iTerm2]
    • Version [e.g. laravel 9]

    Additional context I tried truncating tables, Still no luck.

    help wanted 
    opened by ahaneef29 4
  • Some city strings are malformed

    Some city strings are malformed

    While exploring your package I came across this anomaly - there is no space between words in data on the database tables. All country, state, and city names are like this.

    bug 
    opened by kabacs 4
  • On db:seed truncate problem with foreignId on models

    On db:seed truncate problem with foreignId on models

    Describe the bug If you create a model and have a foreignId in a for example countries id, when try to db:seed and error about truncate happend.

    To Reproduce Create a model with a foreignId $table->foreignId('country_id')->references('id')->on('countries');

    php artisan db:seed --class=WorldSeeder

    ** Error **

    Syntax error or access violation: 1701 Cannot truncate a table referenced in a foreign key constraint (fer.taxes, CONSTRAINT taxes_country_id_foreign FOREIGN KEY (country_id) REFERENCES fer.countries (id)) (SQL: truncate table countries)

    ** Possible solution **

    Schema::disableForeignKeyConstraints(); <- before truncate Schema::enableForeignKeyConstraints(); <- after truncate

    help wanted 
    opened by dgironella 3
  • Incomplete database structure

    Incomplete database structure

    When I see your JSON resource files, you have many informations that are not present in the database structure. For example in the countries.json you have missing data like numeric_code, tld, languages, emoji. Same for timezone table which lack of information, also states

    Is there any update you are working on ?

    enhancement 
    opened by jmatike 3
  • Language is not loading

    Language is not loading

    opened by wasiqaftab 3
Releases(1.1.18)
Owner
Najm Njeim
Najm Njeim
GitHub
Laravel Countries is a bundle for Laravel, providing Almost ISO 3166_2, 3166_3, currency, Capital and more for all countries.

Laravel Countries Laravel Countries is a bundle for Laravel, providing Almost ISO 3166_2, 3166_3, currency, Capital and more for all countries. Please

Christoph Kempen 695 Dec 30, 2022
Laravel countries and currencies

Countries What does it gives you? This package has all sorts of information about countries: info items taxes 32 geometry maps 248 topology maps 248 c

Antonio Carlos Ribeiro 1.7k Dec 29, 2022
The list of all Algerian provinces and cities according to the official division in different formats: csv, xlsx, php, json, etc.

algeria-cities This repository contains the list of all the administrative provinces and cities in Algeria. The data is up-to-date according to the of

Ramtani Othmane 393 Jan 2, 2023
Enable user Timezones in your application.

Laravel Timezone An easy way to set a timezone for a user in your application and then show date/times to them in their local timezone. How does it wo

James Mills 573 Jan 1, 2023
Laravel package to convert currencies to/from Ghana Cedis(GHS).

Kudi About A Laravel package to convert currencies to/from Ghana Cedis(GHS). Installation composer require iamkarsoft\kudi Publishing config files php

Kofi Ramos 3 Jun 28, 2022
oman cities package for laravel app

Seed oman governorates and cities This repo can be used to scaffold Oman Governorates and cities. Installation You can install the package via compose

Gheith Alrawahi 4 Jul 26, 2022
States allows you to create PHP classes following the State Pattern in PHP.

States allows you to create PHP classes following the State Pattern in PHP. This can be a cleaner way for an object to change its behavior at runtime without resorting to large monolithic conditional statements and this improve maintainability and workflows writing.

Teknoo Software 10 Nov 20, 2022
Countries for Laravel

Countries for Laravel What does it gives you? This package has all sorts of information about countries: info items taxes 32 geometry maps 248 topolog

Antonio Carlos Ribeiro 140 Jan 5, 2023
Library for getting countries info from restcountries.com

librestcountries Library for getting countries info from restcountries.com Description Library for getting countries info from restcountries.com Getti

null 4 Sep 18, 2022
A package that uses blade templates to control how markdown is converted to HTML inside Laravel, as well as providing support for markdown files to Laravel views.

Install Install via composer. $ composer require olliecodes/laravel-etched-blade Once installed you'll want to publish the config. $ php artisan vendo

Ollie Codes 19 Jul 5, 2021
List of 77 languages for Laravel Framework 4, 5, 6, 7 and 8, Laravel Jetstream , Laravel Fortify, Laravel Breeze, Laravel Cashier, Laravel Nova and Laravel Spark.

Laravel Lang In this repository, you can find the lang files for the Laravel Framework 4/5/6/7/8, Laravel Jetstream , Laravel Fortify, Laravel Cashier

Laravel Lang 6.9k Jan 2, 2023
This Laravel package merges staudenmeir/eloquent-param-limit-fix and staudenmeir/laravel-adjacency-list to allow them being used in the same model.

This Laravel package merges staudenmeir/eloquent-param-limit-fix and staudenmeir/laravel-adjacency-list to allow them being used in the same model.

Jonas Staudenmeir 5 Jan 6, 2023
Providing some testing functionality for Laravel

Laravel TestBench Laravel TestBench was created by, and is maintained by Graham Campbell, and provides some testing functionality for Laravel. It util

Graham Campbell 50 Dec 20, 2022
A simple drop-in solution for providing UUID support for the IDs of your Eloquent models.

Introduction A simple drop-in solution for providing UUID support for the IDs of your Eloquent models. Both v1 and v4 IDs are supported out of the box

GoldSpec Digital 501 Jan 4, 2023
Create a downloads list - quick and easy. With categories and mobile friendly design

Simple downloads list plugin for wordpress Create a downloads list - quick and easy. With categories and mobile friendly design What is Simple downloa

Neofix 2 Dec 4, 2022
Merge of staudenmeir/eloquent-eager-limit and staudenmeir/laravel-adjacency-list

This Laravel package merges staudenmeir/eloquent-eager-limit and staudenmeir/laravel-adjacency-list to allow them being used in the same model.

Jonas Staudenmeir 7 Nov 1, 2022
A simple laravel state machine to handle model transitions, based on a pre-defined list of rules

A simple state machine that allows transitioning model states based on pre-defined rules. Installation You can install the package via composer: compo

Jack Mollart 18 Apr 2, 2022
Turn any Eloquent model into a list!

Listify Turn any Eloquent model into a list! Description Listify provides the capabilities for sorting and reordering a number of objects in a list. T

Travis Vignon 138 Nov 28, 2022
Ani Cast - Anime List & Trending App. (Powered by Jikan API)

(Under Development) Ani Cast - Anime Shows App.

Noval 2 Jun 15, 2022