README.md

Laravel Countries

This package gives you access effortlessly to data from every country. Laravel 7 above is supported.

Original package by Patrick Samson is not actively maintained anymore, so I decided to fork it.

Features

• Get a country by its 2-letters, 3-letters or 3-digits ISO3166 code.

• Get a list of countries by their region or sub region.

• Get a list of countries by their currency.

• Get a list of countries as a simple PHP array for dropdowns.

• Country

  • Get the 2-letters ISO3166 code.
  • Get the 3-letters ISO3166 code.
  • Get the 3-digits ISO3166 code.
  • Get the official name.
  • Get the common name.
  • Get a Currency object.
  • Get a collection of Currency objects.

• Currency

  • Get the currency code.
  • Get the currency name.
  • Get the currency symbol.

• CountryCast

  • A custom Eloquent cast to store a Country object in the database.

• Coming Soon

  • Get a list of countries by their language.
  • Get a list of countries by their calling code.
  • Get a list of countries by their time zone.
  • Get a list of countries by their top level domain.
  • Get a list of countries by their continent.
  • Get a country flag by its 2-letters ISO3166 code. (size, type, style, etc.)
  • blade components for country dropdowns
  • blade components for country flags
  • Get Google Maps URL for a country

Install

Via Composer

composer require opheus2/laravel-countries

Usage

You can search for a specific country using one of the following unique country codes :

$country = \Countries::getByAlpha2Code('CA'); // 2-letters country code from ISO3166
$country = \Countries::getByAlpha3Code('CAN'); // 3-letters country code from ISO3166
$country = \Countries::getByNumericCode(124); // 3-digits country code from ISO3166

You can retrieve an array of countries using their region of one of their currencies :

$countries = \Countries::getByCurrency('CAD'); /// A 3-letters currency code

// Search by region
$countries = \Countries::getByRegion(\Countries::$REGION_AFRICA);
$countries = \Countries::getByRegion(\Countries::$REGION_AMERICAS);
$countries = \Countries::getByRegion(\Countries::$REGION_ANTARCTICA);
$countries = \Countries::getByRegion(\Countries::$REGION_ASIA);
$countries = \Countries::getByRegion(\Countries::$REGION_EUROPE);
$countries = \Countries::getByRegion(\Countries::$REGION_OCEANIA);

Results will be returned as Country objects. These objects have the following helper methods :

$country = \Countries::getByAlpha3Code('CAN');

$country->getAlpha2Code();      // 'CA'
$country->getAlpha3Code();      // 'CAN'
$country->getNumericCode();     // 124
$country->getOfficialName();    // 'Canada'
$country->getCommonName();      // 'Canada' 
$country->getCurrency();        // The first Currency object
$country->getCurrencies();      // A collection of Currency objects

$currency = $country->getCurrency();
$currency->getCode();           // 'CAD'
$currency->getName();           // 'Canadian dollar'
$currency->getSymbol();         // '$'

$country->getAttributes();      // An array of all the raw attributes.

It is also possible to generate simple PHP array that can be used to generate an HTML select input.

// All parameters are optionnal. These are the defaults.
// $key             The country attribute to use as key. (default: 'cca3', 3-letters country code from ISO3166)
// $official        True for the offical country name, False for the common name. (default: false)
// $localization    A 3-letter locale code to try to translate. Will default to English if it`s missing. (default: null)
$countries = \Countries::getListForDropdown('cca3', false, 'fra');

//This will return the following
[
    'CAN' => 'Canada',
    'USA' => 'États-Unis',
    ...
]

Macros

This package implements the Laravel Macroable trait, allowing macros and mixins on both Country.

Example use case:

use Orpheus\LaravelCountries\Country;

Country::macro(
    'getFlag',
    fn () => sprintf('https://www.countryflags.io/%s/flat/64.png', $this->getAlpha2Code())
);

$country = \Countries::getByAlpha3Code('CAN');
$flag = $country->getFlag();

// Output: https://www.countryflags.io/CA/flat/64.png

Mixins

Along with Macros, Mixins are also supported. This allows merging another classes methods into the Country.

Define the mixin class:

class CustomCountry
{
    public function getFlag(): string
    {
        return sprintf('https://www.countryflags.io/%s/flat/64.png', $this->getAlpha2Code());
    }
}

Register the mixin, by passing an instance of the class:

Country::mixin(new CustomCountry);

The methods from the custom class will be available:

$country = \Countries::getByAlpha3Code('CAN');
$flag = $country->getFlag();

Credits

• Orpheus for the fork.
• Patrick Samson for the initial package.
• Mohammed Le Doze for compiling all this data in this repository.
• All Contributors

License

The MIT License (MIT). Please see License File for more information.