PHPackages                             mohamedahmed00/countries - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. mohamedahmed00/countries

ActiveLibrary[Utility & Helpers](/categories/utility)

mohamedahmed00/countries
========================

PHP Countries and Currencies

02PHP

Since Sep 24Pushed 1y agoCompare

[ Source](https://github.com/mohamedAhmed00/countries)[ Packagist](https://packagist.org/packages/mohamedahmed00/countries)[ RSS](/packages/mohamedahmed00-countries/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

 Countries
===========

[](#----countries)

[![World Map](docs/world-map-political-of-the-2013-nations-online-project-best.jpg)](docs/world-map-political-of-the-2013-nations-online-project-best.jpg)

 [![Latest Stable Version](https://camo.githubusercontent.com/144d6fbf1534090339b2b3660bc98d65e49c75709c9c2681157a6dadcd570594/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d6f68616d656461686d656430302f636f756e74726965732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/mohamedahmed00/countries) [![License](https://camo.githubusercontent.com/55c0218c8f8009f06ad4ddae837ddd05301481fcf0dff8e0ed9dadda8780713e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](/antonioribeiro/countries/blob/master/LICENSE.md) [![Code Quality](https://camo.githubusercontent.com/7f4a45062a76c8ae29a1ff1809554635d37c00b8560ef7dcc3900a6df81e5afb/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f672f616e746f6e696f7269626569726f2f636f756e74726965732e7376673f7374796c653d666c61742d737175617265)](https://scrutinizer-yaml.com/g/antonioribeiro/countries/?branch=master) [![Build](https://camo.githubusercontent.com/0951d6ebf1164d852fbcad8a7936b547ae83330e99d8e1d069ddb9c4bb85f151/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f6275696c642f672f616e746f6e696f7269626569726f2f636f756e74726965732e7376673f7374796c653d666c61742d737175617265)](https://scrutinizer-yaml.com/g/antonioribeiro/countries/?branch=master)

 [![Coverage](https://camo.githubusercontent.com/1ffb44eacfa814868bd031e0eb63230c86eecc08de471eafed7b383aeefdad4e/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f636f7665726167652f672f616e746f6e696f7269626569726f2f636f756e74726965732e7376673f7374796c653d666c61742d737175617265)](https://scrutinizer-yaml.com/g/antonioribeiro/countries/?branch=master) [![PHP](https://camo.githubusercontent.com/4221181dfe389cd3d24e350bc3246a391d8cdfe279df596ecefbdee1e9c4a5d7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d372e30253230253743253230372e31253230253743253230372e32253230253743253230372e332d677265656e2e7376673f7374796c653d666c6174)](https://travis-ci.org/antonioribeiro/countries) [![Downloads](https://camo.githubusercontent.com/cbf5fdde3d80d5738d798e08c1c512b3aabb34a3204860573471128d3365dd8e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d6f68616d656461686d656430302f636f756e74726965732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/mohamedahmed00/countries) [![StyleCI](https://camo.githubusercontent.com/d160e41b84e7dd9920b66f2cd4254bdbf8d96df3faa8dbe2f5f474432d53956f/68747470733a2f2f7374796c6563692e696f2f7265706f732f37343832393234342f736869656c64)](https://styleci.io/repos/74829244)

### What does it gives you?

[](#what-does-it-gives-you)

This package has all sorts of information about countries:

infoitemstaxes32geometry maps248topology maps248currencies256countries266timezones423borders649flags1,570states4,526cities7,376timezones times81,153### Geology and topology maps

[](#geology-and-topology-maps)

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

[![Switzerland](docs/switzerland-geo.png)](docs/switzerland-geo.png)

Requirements
------------

[](#requirements)

- PHP 7.0+

Installing
----------

[](#installing)

Use Composer to install it:

```
composer require mohamedahmed00/countries

```

Instantiating
-------------

[](#instantiating)

```
use Mohamedahmed00\Countries\Package\Countries;

$countries = new Countries();

echo $countries->where('cca2', 'IT')->first()->hydrateCurrencies()->currencies->EUR->coins->frequent->first();

// or calling it statically

echo Countries::where('cca2', 'IT')->first()->hydrateCurrencies()->currencies->EUR->coins->frequent->first();
```

Should both return

```
€1

```

Overloading the default configuration:

```
use Mohamedahmed00\Countries\Package\Services\Config;

$countries = new Countries(new Config([
    'hydrate' => [
        'elements' => [
            'currencies' => true,
            'flag' => true,
            'timezones' => true,
        ],
    ],
]));
```

Usage
-----

[](#usage)

This package is not tied to Laravel and doesn't require it to be installed (we have a [bridge](https://github.com/antonioribeiro/countries-laravel) for this purpose), but it has [Laravel Collections](https://laravel.com/docs/5.6/collections) in its core, all methods in Collections are available, this way you can do things like filter, map, reduce, search, sort, reject, and a lot more. It, actually, uses [Coollection](https://github.com/antonioribeiro/coollection), which is Laravel Collections with a fluent syntax, allowing us to have access to array keys (and values) as object properties.

To get all countries in the data base you just have to:

```
use Mohamedahmed00\Countries\Package\Countries;

$countries = new Countries();

$all = $countries->all();
```

To get a json you:

```
return $countries->toJson();
```

Filter by keys and values:

```
$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()->hydrateStates()->states->pluck('name', 'postal')->toArray();
```

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

[](#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('name.common', 'United States')->first()->hydrate('timezones')->timezones->first()->zone_name;

$countries->where('name.common', 'United States')->first()->hydrate('timezones')->timezones->first()->zone_name;
```

Those are some of the hydratable properties:

- Borders
- Cities
- Currencies
- Flag
- Geometry
- Languages
- States
- Taxes
- Timezone
- Topology

### Extra where rules

[](#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

[](#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
---------------------------------------------------------------------

[](#some-other-examples-from-laravel-news-and-some-other-contributors)

#### Generate a list of all countries with code, using native name and common

[](#generate-a-list-of-all-countries-with-code-using-native-name-and-common)

```
app(Mohamedahmed00\Countries\Package\Countries::class)
->all()
->map(function ($country) {
    $commonName = $country->name->common;

    $languages = $country->languages ?? collect();

    $language = $languages->keys()->first() ?? null;

    $nativeNames = $country->name->native ?? null;

    if (
        filled($language) &&
            filled($nativeNames) &&
            filled($nativeNames[$language]) ?? null
    ) {
        $native = $nativeNames[$language]['common'] ?? null;
    }

    if (blank($native ?? null) && filled($nativeNames)) {
        $native = $nativeNames->first()['common'] ?? null;
    }

    $native = $native ?? $commonName;

    if ($native !== $commonName && filled($native)) {
        $native = "$native ($commonName)";
    }

    return [$country->cca2 => $native];
})
->values()
->toArray();
```

Should give you 267 (or so) countries like:

```
"AW" => "Aruba"
"AF" => "افغانستان (Afghanistan)"
"AO" => "Angola"
"AI" => "Anguilla"
"AX" => "Åland (Åland Islands)"
"AL" => "Shqipëria (Albania)"
"AD" => "Andorra"
"AE" => "دولة الإمارات العربية المتحدة (United Arab Emirates)"
"AR" => "Argentina"
"AM" => "Հայաստան (Armenia)"
"AS" => "American Samoa"
"AQ" => "Antarctica"
"TF" => "Terres australes et antarctiques françaises (French Southern and Antarctic Lands)"
"AG" => "Antigua and Barbuda"
"AU" => "Australia"
"AT" => "Österreich (Austria)"
"AZ" => "Azərbaycan (Azerbaijan)"
"BI" => "Burundi"
"BE" => "Belgien (Belgium)"
"BJ" => "Bénin (Benin)"
"BF" => "Burkina Faso"
"BD" => "বাংলাদেশ (Bangladesh)"
"BG" => "България (Bulgaria)"
"BH" => "‏البحرين (Bahrain)"
"BS" => "Bahamas"
"BA" => "Bosna i Hercegovina (Bosnia and Herzegovina)"
"BL" => "Saint-Barthélemy (Saint Barthélemy)"
"SH" => "Saint Helena, Ascension and Tristan da Cunha"
"BY" => "Белару́сь (Belarus)"
"BZ" => "Belize"
"BM" => "Bermuda"
"BO" => "Wuliwya (Bolivia)"
"BQ" => "Caribisch Nederland (Caribbean Netherlands)"
"BR" => "Brasil (Brazil)"
"BB" => "Barbados"
"BN" => "Negara Brunei Darussalam (Brunei)"
"BT" => "འབྲུག་ཡུལ་ (Bhutan)"
"BV" => "Bouvetøya (Bouvet Island)"
"BW" => "Botswana"
"CF" => "République centrafricaine (Central African Republic)"
"CA" => "Canada"
"CC" => "Cocos (Keeling) Islands"
"CH" => "Suisse (Switzerland)"
"CL" => "Chile"
"CN" => "中国 (China)"
"CI" => "Côte d'Ivoire (Ivory Coast)"
"CM" => "Cameroon"
"CD" => "RD Congo (DR Congo)"
"CG" => "République du Congo (Republic of the Congo)"
"CK" => "Cook Islands"
"CO" => "Colombia"
"KM" => "القمر‎ (Comoros)"
"CV" => "Cabo Verde (Cape Verde)"
...

```

#### Generate a list of countries

[](#generate-a-list-of-countries)

```
$countries->all()->pluck('name.common')->toArray();
```

returns

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

#### Generate a list of currencies

[](#generate-a-list-of-currencies)

```
$countries->all()->pluck('currencies')->toArray();
```

returns

```
[
  [
    "AWG",
  ],
  [
    "AFN",
  ],
  [
    "AOA",
  ],
  [
    "XCD",
  ],
  [
    "EUR",
  ],
  ....
```

#### Get the currency symbol

[](#get-the-currency-symbol)

```
$countries->where('name.common', 'Brazil')->first()->hydrate('currencies')->currencies->BRL->units->major->symbol;
```

#### Generate a list of States

[](#generate-a-list-of-states)

```
$countries->where('name.common', 'United States')
    ->first()
    ->hydrateStates()
    ->states
    ->sortBy('name')
    ->pluck('name', 'postal');
```

returns

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

#### Hydrate and get a cities

[](#hydrate-and-get-a-cities)

```
$countries->where('cca3', 'FRA')
    ->first()
    ->hydrate('cities')
    ->cities
    ->paris
    ->timezone;
```

Should return

```
Europe/Paris

```

#### Get a countries currencies

[](#get-a-countries-currencies)

```
$countries->where('name.common', 'United States')->first()->currencies;
```

returns

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

#### Get all currencies

[](#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"
    ....
```

#### Get the timezone for a State

[](#get-the-timezone-for-a-state)

```
return $countries->where('name.common', 'United States')->first()->timezone->NC;
```

returns

```
America/New_York
```

#### Get all timezones for a country

[](#get-all-timezones-for-a-country)

```
$countries->where('name.common', 'Brazil')
  ->first()
  ->hydrateTimezones()
  ->timezones
  ->map(function ($timezone) {
      return $timezone->zone_name;
  })->values()
  ->unique()
  ->toArray();
```

#### Get all times for a timezone

[](#get-all-times-for-a-timezone)

```
return $countries->where('name.common', 'United States Virgin Islands')->first()->hydrate('timezones_times')->timezones->first()->times;
```

returns

```
"times" => [
    "abbreviation" => "LMT"
    "dst" => "0"
    "gmt_offset" => "-14764"
    "time_start" => "-1825098837"
    "zone_id" => "415"
    1 => [
        "abbreviation" => "AST"
        "dst" => "0"
        "gmt_offset" => "-14400"
        "time_start" => "-1825098836"
        "zone_id" => "415"
    ]
]
```

Flags
-----

[](#flags)

Countries provides many different flag sources, including SVG flags. This is how you use one of the available sources:

### Install [flag-icon](https://github.com/lipis/flag-icon-css)

[](#install-flag-icon)

```
npm install --save-dev flag-icon-css

```

### Import it to your project

[](#import-it-to-your-project)

```
@import '~flag-icon-css/sass/flag-icon.scss';

```

### Use Countries to get the flag span

[](#use-countries-to-get-the-flag-span)

```
$unitedStatesFlag =
    $this->countries->where('cca3', 'USA')
    ->first()
    ->flag
    ->flag_icon;

```

### Render it in your blade template

[](#render-it-in-your-blade-template)

```
{!! $unitedStatesFlag !!}

```

Publishing assets
-----------------

[](#publishing-assets)

You can publish configuration by doing:

```
php artisan vendor:publish --provider=Mohamedahmed00\\Countries\\ServiceProvider

```

Data
----

[](#data)

### Sources

[](#sources)

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](https://github.com/mledoze/countries/blob/master/README.md) and how to use it on this fantastic [Laravel News article](https://laravel-news.com/countries-and-currencies).

Please check the [copyright](#copyright) section for a complete list of packages used by this one.

### Updating

[](#updating)

#### **WARNING**

[](#warning)

No data files (JSON, images, icons...) on this project can be updated manually. **We will close all pull requests requiring manual updates** to those files will be closed, because the update script will delete them anyway.

If you find something wrong with data, you, please, have to ask the package managers (listed data sources and on the copyright section) to fix them, and then you can yourself run the update script to properly update them on this repository.

#### update.php

[](#updatephp)

This package comes with the `update.php` script, which you MUST use to update the data files. It will download all info from all packages and automatically build the `.json` (and some others like `.svg` too). This is how you do it:

```
cd vendor/mohamedahmed00/countries
composer install
php update.php
```

And wait for a *very long time*\* (sometimes it looks like stuck but it's not) until it finishes rebuilding everything, then it's just a matter of staging, commit, push all regenerated files, and draft a new PR.

Cache
-----

[](#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.

Framework bridges
-----------------

[](#framework-bridges)

- [Laravel](https://github.com/antonioribeiro/countries-laravel)

Sample files
------------

[](#sample-files)

- [sample-partial.json](src/data/sample-partial.json): example of a country with no borders hydrated.
- [sample-full.json](src/data/sample-full.json): example of a fully hydrated country.

Author
------

[](#author)

[Antonio Carlos Ribeiro](http://twitter.com/iantonioribeiro)[All contributors](https://github.com/antonioribeiro/countries-laravel/graphs/contributors)

Copyright
---------

[](#copyright)

To build the countries database and relations, this package make use of those sources and packages:

- [mledoze/countries](https://github.com/mledoze/countries)
- [Natural Earth Vector](https://github.com/nvkelso/natural-earth-vector)
- [rinvex/country](https://github.com/rinvex/country)
- [commerceguys/tax](https://github.com/commerceguys/tax)
- [timezonedb](https://timezonedb.com/)
- [wiredmax/world-currencies](https://github.com/wiredmax/world-currencies)

License
-------

[](#license)

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

Contributing
------------

[](#contributing)

Pull requests and issues are more than welcome.

###  Health Score

15

—

LowBetter than 3% of packages

Maintenance29

Infrequent updates — may be unmaintained

Popularity2

Limited adoption so far

Community17

Small or concentrated contributor base

Maturity17

Early-stage or recently created project

 Bus Factor1

Top contributor holds 90.5% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/095ee77df4acbc191a1f199c7c2cf07162249480b459bb839193dccb7915793e?d=identicon)[engmohamedahmed00](/maintainers/engmohamedahmed00)

---

Top Contributors

[![antonioribeiro](https://avatars.githubusercontent.com/u/3182864?v=4)](https://github.com/antonioribeiro "antonioribeiro (316 commits)")[![olivernybroe](https://avatars.githubusercontent.com/u/5870441?v=4)](https://github.com/olivernybroe "olivernybroe (6 commits)")[![b00f](https://avatars.githubusercontent.com/u/8073510?v=4)](https://github.com/b00f "b00f (3 commits)")[![KKSzymanowski](https://avatars.githubusercontent.com/u/13980973?v=4)](https://github.com/KKSzymanowski "KKSzymanowski (3 commits)")[![amirasyraf](https://avatars.githubusercontent.com/u/15522007?v=4)](https://github.com/amirasyraf "amirasyraf (2 commits)")[![olimortimer](https://avatars.githubusercontent.com/u/1190115?v=4)](https://github.com/olimortimer "olimortimer (2 commits)")[![evrard-c](https://avatars.githubusercontent.com/u/23173851?v=4)](https://github.com/evrard-c "evrard-c (2 commits)")[![mohamedAhmed00](https://avatars.githubusercontent.com/u/17501169?v=4)](https://github.com/mohamedAhmed00 "mohamedAhmed00 (2 commits)")[![Omranic](https://avatars.githubusercontent.com/u/406705?v=4)](https://github.com/Omranic "Omranic (1 commits)")[![ralbear](https://avatars.githubusercontent.com/u/3120856?v=4)](https://github.com/ralbear "ralbear (1 commits)")[![reinierkors](https://avatars.githubusercontent.com/u/1042387?v=4)](https://github.com/reinierkors "reinierkors (1 commits)")[![StyleCIBot](https://avatars.githubusercontent.com/u/11048387?v=4)](https://github.com/StyleCIBot "StyleCIBot (1 commits)")[![0ly](https://avatars.githubusercontent.com/u/10458787?v=4)](https://github.com/0ly "0ly (1 commits)")[![vortechron](https://avatars.githubusercontent.com/u/22893960?v=4)](https://github.com/vortechron "vortechron (1 commits)")[![amenk](https://avatars.githubusercontent.com/u/1087128?v=4)](https://github.com/amenk "amenk (1 commits)")[![artem-schander](https://avatars.githubusercontent.com/u/1243826?v=4)](https://github.com/artem-schander "artem-schander (1 commits)")[![ChrisThompsonTLDR](https://avatars.githubusercontent.com/u/348801?v=4)](https://github.com/ChrisThompsonTLDR "ChrisThompsonTLDR (1 commits)")[![coding-sunshine](https://avatars.githubusercontent.com/u/3206025?v=4)](https://github.com/coding-sunshine "coding-sunshine (1 commits)")[![grrnikos](https://avatars.githubusercontent.com/u/3323561?v=4)](https://github.com/grrnikos "grrnikos (1 commits)")[![iasjennen](https://avatars.githubusercontent.com/u/12272672?v=4)](https://github.com/iasjennen "iasjennen (1 commits)")

### Embed Badge

![Health badge](/badges/mohamedahmed00-countries/health.svg)

```
[![Health](https://phpackages.com/badges/mohamedahmed00-countries/health.svg)](https://phpackages.com/packages/mohamedahmed00-countries)
```

###  Alternatives

[nzedb/nzedb

A Usenet Indexer

6415.4k](/packages/nzedb-nzedb)[carica/io

Non blocking I/O for PHP

241.1k4](/packages/carica-io)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)