Amongst many other information you'll be able to plot country maps:
This package is a collection of some other packages with information on:
-
Countries
- name (common and native)
- currency
- languages
- states
- timezone
- flags (sprites, flag icons, svg)
- tld
- multiple ISO codes
- calling code
- capital
- alternate spellings
- region & sub region
- translations (country name translated to some other languages)
- latitude and logitude
- borders (countries) - you can hydrate those borders (like relationships)
- area
- topology
- geometry
-
Currencies
- sign
- ISO codes
- title
- subunits
- usage (dates)
-
States
- adm codes
- name & alt name
- type (state, city, province, canton, department, district, etc.)
- latitude & longitude
- language
- (and many more)
-
Cities
- region
- elevation
- latitude
- longitude
- area (km and mi)
- population (from 1950 to 2050)
- is it a "mega city"?
- timezone
- name (translated to several languages)
-
Flags. There are some options available out there, so this package will give you some:
- sprite, based on https://www.flag-sprites.com/
- flag-icon and flag-icon-squared, based on https://github.com/lipis/flag-icon-css
- world-flags-sprite, based on https://github.com/lafeber/world-flags-sprite
- svg, the flag svg file loaded into the json
-
Validation
- Customizable validation fields based on Laravel Validation
- PHP 7.0+
- Laravel 5.3+
Use Composer to install it:
composer require pragmarx/countries
Add the Service Provider and Facade alias to your config/app.php:
// config/app.php
'providers' => [
// ...
PragmaRX\Countries\ServiceProvider::class,
];
'aliases' => [
// ...
'Countries'=> PragmaRX\Countries\Facade::class,
];The package is based on Laravel Collections, so you basically have access to all methods in Collections, like
$all = Countries::all();You, obviously, don't need to use the Facade, you can just get it from the app container:
$countries = app('pragmarx.countries');
\\ then
$all = $countries->all();This filter
Countries::where('name.common', 'Brazil')Will find Brazil by its common name, which is a
#items: array:22 [▼
"name" => array:3 [▼
"common" => "Brazil"
"official" => "Federative Republic of Brazil"
"native" => array:1 [▼
"por" => array:2 [▼
"official" => "República Federativa do Brasil"
"common" => "Brasil"
]
]
]
Or alternatively you can filter like this
Countries::whereNameCommon('Brazil')And, you can go deepeer
Countries::where('name.native.por.common', 'Brasil')Or search by the country top level domain
Countries::where('tld.0', '.ch')To get
"name" => array:3 [▼
"common" => "Switzerland"
"official" => "Swiss Confederation"
"native" => array:4 [▶]
]
"tld" => array:1 [▼
0 => ".ch"
]
And use things like pluck
Countries::where('cca3', 'USA')->first()->states->pluck('name', 'postal')To get
"MA" => "Massachusetts"
"MN" => "Minnesota"
"MT" => "Montana"
"ND" => "North Dakota"
...The package uses a modified Collection which allows you to access properties and methods as objects:
Countries::where('cca3', 'FRA')
->first()
->borders
->first()
->name
->officialShould give
Principality of Andorra
Borders hydration is disabled by default, but you can have your borders hydrated easily by calling the hydrate method:
Countries::where('name.common', 'United Kingdom')
->hydrate('borders')
->first()
->borders
->reverse()
->first()
->name
->commonShould return
Ireland
To improve performance, hydration, which is enabled by default, can be disable on most country properties, and this is how you manually hydrate properties:
Countries::where('cca3', 'FRA')->first()->hydrate('timezone')->timezone
Countries::where('cca3', 'JPN')->first()->hydrateTimezone()->timezoneThose are some of the hydratable properties:
- Country
- Countries
- Currency
- Timezone
- States
- Topology
- Geometry
- Flag
- Borders
- Timezone
Some properties are stored differently and we therefore need special rules for accessing them, these properties are
ISO639_3=> The 3 letter language code.ISO4217=> The 3 letter currency code.
You can of course access them like other properties
Countries::whereISO639_3('por')->count()
Countries::where('ISO639_3', 'por')->count()Sometimes you would like to access a property by a different name, this can be done in settings, this way
'maps' => [
'lca3' => 'ISO639_3'
]Here we bind the language 3 letter short code ISO format to lca3, which is short for language code alpha 3-letter.
So now we can access the property by
Countries::whereLca3('por')Or
Countries::where('lca3', 'por')Countries::all()->pluck('name.common');returns
[
"Aruba",
"Afghanistan",
"Angola",
"Anguilla",
"Åland Islands",
....Countries::all()->pluck('currency');returns
Countries::all()->pluck('currency')Countries::where('name.common', 'United States')
->first()
->states
->sortBy('name')
->pluck('name', 'postal')returns
[
"AL": "Alabama",
"AK": "Alaska",
"AZ": "Arizona",
"AR": "Arkansas",
"CA": "California",
....
....Countries::where('cca3', 'FRA')
->first()
->hydrate('cities')
->cities
->paris
->timezoneShould return
Europe/Paris
return Countries::where('name.common', 'United States')->first()->timezone->NC;returns
America/New_YorkCountries::where('name.common', 'United States')->first()->currency;returns
[{
"alternativeSigns": [],
"ISO4217Code": "USD",
"ISO4217Number": "840",
"sign": "$",
"subunits": 100,
"title": "U.S. dollar",
....Countries::currencies()returns
[
0 => "AED"
1 => "AFN"
2 => "ALL"
3 => "AMD"
4 => "ANG"
5 => "AOA"
6 => "ARS"
7 => "AUD"
8 => "AWG"
9 => "AZN"
10 => "BAM"
....The validation is extending Laravel's validation, so you can use it like any other validation rules, like
/**
* Store a new blog post.
*
* @param Request $request
* @return Response
*/
public function store(Request $request)
{
$this->validate($request, [
'title' => 'required|unique:posts|max:255',
'body' => 'required',
'country' => 'country' //Checks if valid name.common
]);
// The blog post is valid, store in database...
}Which validation rules there is and what there name should be, can all be configured in the configuration file.
'validation' => [
'rules' => [
'countryCommon' => 'name.common'
]
]By changing the configuration like this, we can now access the property name.common, by the validation rule countryCommon
You have to define all the validations rules in settings, only a few is defined by default, the default is
'rules' => [
'country' => 'name.common',
'cca2',
'cca2',
'cca3',
'ccn3',
'cioc',
'currency' => 'ISO4217',
'language',
'language_short' => 'ISO639_3',
]You can publish configuration by doing:
php artisan vendor:publish --provider=PragmaRX\\Countries\\ServiceProvider
This package uses some other open source packages and, until we don't build a better documentation, you can find some more info about data on mledoze/countries and how to use it on this fantastic Laravel News article.
Since this data is not supposed to change, calls are automatically cached.
If you want to change this behaviour, you can edit config/countries.php file once it's published.
- sample-partial.json: example of a country with no borders hydrated.
- sample-full.json: example of a fully hydrated country.
This package make use of those library/packages:
Countries is licensed under the BSD 3-Clause License - see the LICENSE file for details
Pull requests and issues are more than welcome.