Skip to content

Latest commit

 

History

History
499 lines (382 loc) · 10.7 KB

README.md

File metadata and controls

499 lines (382 loc) · 10.7 KB
Raw

Countries

A Laravel Countries package, with lots of information

Latest Stable Version License Code Quality Coverage Build StyleCI Downloads PHP

Geoology and Topology for countries

Amongst many other information you'll be able to plot country maps:

Switzerland

What does it gives you?

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:

  • Validation

Requirements

  • PHP 7.0+
  • Laravel 5.3+

Installing

Use Composer to install it:

composer require pragmarx/countries

Installing on Laravel

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,
];

Usage

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
         ->official

Should 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
         ->common

Should return

Ireland

Hydration

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()->timezone

Those are some of the hydratable properties:

  • Country
  • Countries
  • Currency
  • Timezone
  • States
  • Topology
  • Geometry
  • Flag
  • Borders
  • Timezone

Extra where rules

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()

Mapping

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')

Some other examples from Laravel News and some other contributors

Generate a list of countries

Countries::all()->pluck('name.common');

returns

[
    "Aruba",
    "Afghanistan",
    "Angola",
    "Anguilla",
    "Åland Islands",
    ....

Generate a list of currencies

Countries::all()->pluck('currency');

returns

Countries::all()->pluck('currency')

Generate a list of States

Countries::where('name.common', 'United States')
    ->first()
    ->states
    ->sortBy('name')
    ->pluck('name', 'postal')

returns

[
    "AL": "Alabama",
    "AK": "Alaska",
    "AZ": "Arizona",
    "AR": "Arkansas",
    "CA": "California",
    ....
    ....

Hydrate and get a cities

Countries::where('cca3', 'FRA')
    ->first()
    ->hydrate('cities')
    ->cities
    ->paris
    ->timezone

Should return

Europe/Paris

Get the timezone for a State

return Countries::where('name.common', 'United States')->first()->timezone->NC;

returns

America/New_York

Get a countries currency

Countries::where('name.common', 'United States')->first()->currency;

returns

[{
    "alternativeSigns": [],
    "ISO4217Code": "USD",
    "ISO4217Number": "840",
    "sign": "$",
    "subunits": 100,
    "title": "U.S. dollar",
    ....

Get all currencies

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"
    ....

Validation

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',
]

Publishing assets

You can publish configuration by doing:

php artisan vendor:publish --provider=PragmaRX\\Countries\\ServiceProvider

Data

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.

Cache

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 files

Author

Antonio Carlos Ribeiro

Copyrights

This package make use of those library/packages:

License

Countries is licensed under the BSD 3-Clause License - see the LICENSE file for details

Contributing

Pull requests and issues are more than welcome.