PHPackages                             opheus2/laravel-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. opheus2/laravel-countries

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

opheus2/laravel-countries
=========================

Get informations about countries and their currency.

v3.1.0(2mo ago)07.7k↓70.4%1MITPHPCI passing

Since Jun 1Pushed 2mo agoCompare

[ Source](https://github.com/opheus2/laravel-countries)[ Packagist](https://packagist.org/packages/opheus2/laravel-countries)[ Docs](https://github.com/opheus2/laravel-countries)[ RSS](/packages/opheus2-laravel-countries/feed)WikiDiscussions master Synced today

READMEChangelog (5)Dependencies (8)Versions (6)Used By (0)

Laravel Countries
=================

[](#laravel-countries)

[![Latest Version on Packagist](https://camo.githubusercontent.com/27afe6559eba68f969208bad97f98569d6fa9e1cf7d15dc1dbafdda4e5490ab8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f4f7270686575732f6c61726176656c2d636f756e74726965732e737667)](https://packagist.org/packages/opheus2/laravel-countries)[![Software License](https://camo.githubusercontent.com/6f2a409d4eef5d73a65689d6f9bcdd47b068349260a43105e16c4cbd1f9fcc9e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f4f7270686575732f6c61726176656c2d636f756e74726965732e737667)](LICENSE.md)[![Build Status](https://github.com/opheus2/laravel-countries/workflows/Run%20Tests%20-%20Current/badge.svg?branch=master)](https://github.com/opheus2/laravel-countries/workflows/Run%20Tests%20-%20Current/badge.svg?branch=master)[![Total Downloads](https://camo.githubusercontent.com/4e95b808c1fef983d501542dbb9403f8d496e3727af7428f16307329ab5edec8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f4f7270686575732f6c61726176656c2d636f756e74726965732e737667)](https://packagist.org/packages/opheus2/laravel-countries)

A Laravel package that provides comprehensive data for every country — codes, names, currencies, languages, capitals, regions, demonyms, translations, and more. Laravel 11+ supported.

What's New in v3.0.0
--------------------

[](#whats-new-in-v300)

- **Updated data source** — Country data is now compiled from the [REST Countries v3.1](https://gitlab.com/restcountries/restcountries) dataset.
- **New search methods** — Search by name, language, capital, demonym, translation, and independence status.
- **Unified code lookup** — New `getByCode()` method auto-detects cca2, cca3, ccn3, or cioc codes.
- **Deprecations** — `getByAlpha2Code()`, `getByAlpha3Code()`, and `getByNumericCode()` are deprecated in favor of `getByCode()`. They still work but will trigger `E_USER_DEPRECATED` notices.
- **PHPUnit 12 compatibility** — Test suite updated.

Install
-------

[](#install)

```
composer require opheus2/laravel-countries
```

Upgrading from v2.x
-------------------

[](#upgrading-from-v2x)

Replace deprecated method calls:

```
use Orpheus\LaravelCountries\Facades\Countries;

// Before (deprecated)
$country = Countries::getByAlpha2Code('CA');
$country = Countries::getByAlpha3Code('CAN');
$country = Countries::getByNumericCode(124);

// After
$country = Countries::getByCode('CA');
$country = Countries::getByCode('CAN');
$country = Countries::getByCode(124);
```

The deprecated methods still function but will emit `E_USER_DEPRECATED` warnings and will be removed in a future major release.

Usage
-----

[](#usage)

### Lookup by Code

[](#lookup-by-code)

The `getByCode()` method auto-detects the code type:

```
use Orpheus\LaravelCountries\Facades\Countries;

$country = Countries::getByCode('CA');    // 2-letter (cca2)
$country = Countries::getByCode('CAN');   // 3-letter (cca3) or CIOC
$country = Countries::getByCode(124);     // Numeric (ccn3)
$country = Countries::getByCode('124');   // Numeric as string
```

### Search by Name

[](#search-by-name)

```
use Orpheus\LaravelCountries\Facades\Countries;

// Partial match (searches common, official, and native names)
$countries = Countries::getByName('united');

// Exact match on common or official name
$countries = Countries::getByFullName('Canada');
$countries = Countries::getByFullName('United States of America');
```

### Search by Language

[](#search-by-language)

```
use Orpheus\LaravelCountries\Facades\Countries;

// By language code
$countries = Countries::getByLanguage('fra');

// By language name (partial match)
$countries = Countries::getByLanguage('French');
$countries = Countries::getByLanguage('Spanish');
```

### Search by Capital

[](#search-by-capital)

```
use Orpheus\LaravelCountries\Facades\Countries;

$countries = Countries::getByCapital('Ottawa');
$countries = Countries::getByCapital('Wash');   // Partial match
```

### Search by Demonym

[](#search-by-demonym)

```
use Orpheus\LaravelCountries\Facades\Countries;

$countries = Countries::getByDemonym('Canadian');
$countries = Countries::getByDemonym('peruvian');  // Case-insensitive
```

### Search by Translation

[](#search-by-translation)

```
use Orpheus\LaravelCountries\Facades\Countries;

$countries = Countries::getByTranslation('Alemania');   // Germany in Spanish
$countries = Countries::getByTranslation('Saksamaa');    // Germany in Estonian
```

### Search by Currency

[](#search-by-currency)

```
use Orpheus\LaravelCountries\Facades\Countries;

$countries = Countries::getByCurrency('CAD');              // By currency code
$countries = Countries::getByCurrency('Canadian dollar');  // By currency name
```

### Filter by Region / Subregion

[](#filter-by-region--subregion)

```
use Orpheus\LaravelCountries\Facades\Countries;

$countries = Countries::getByRegion(Countries::$REGION_AFRICA);
$countries = Countries::getByRegion(Countries::$REGION_AMERICAS);
$countries = Countries::getByRegion(Countries::$REGION_ANTARCTIC);
$countries = Countries::getByRegion(Countries::$REGION_ASIA);
$countries = Countries::getByRegion(Countries::$REGION_EUROPE);
$countries = Countries::getByRegion(Countries::$REGION_OCEANIA);

$countries = Countries::getBySubregion('Northern Europe');
```

### Filter by Independence Status

[](#filter-by-independence-status)

```
use Orpheus\LaravelCountries\Facades\Countries;

$independent    = Countries::getIndependent(true);
$nonIndependent = Countries::getIndependent(false);
```

### Get All Countries

[](#get-all-countries)

```
use Orpheus\LaravelCountries\Facades\Countries;

$all = Countries::getAll();

// As a Laravel Collection
$collection = Countries::getAll([], true);

// Filtered by codes (mixed types supported)
$filtered = Countries::getAll(['CA', 'USA', '276']);
```

### Dropdown List Helper

[](#dropdown-list-helper)

```
use Orpheus\LaravelCountries\Facades\Countries;

// Default: keyed by cca3, common name
$list = Countries::getListForDropdown();

// Custom key, official name, translated
$list = Countries::getListForDropdown('cca2', true, 'fra');

// Returns: ['CA' => 'Canada', 'US' => "Les états-unis d'Amérique", ...]
```

### Country Object

[](#country-object)

```
use Orpheus\LaravelCountries\Facades\Countries;

$country = Countries::getByCode('CAN');

$country->getAlpha2Code();      // 'CA'
$country->getAlpha3Code();      // 'CAN'
$country->getNumericCode();     // '124'
$country->getOfficialName();    // 'Canada'
$country->getCommonName();      // 'Canada'
$country->getCurrency();        // Currency object (first currency)
$country->getCurrencies();      // Collection of Currency objects
$country->getAttributes();      // Raw attributes array

// Dynamic property access to any attribute
$country->capital;              // ['Ottawa']
$country->region;               // 'Americas'
$country->languages;            // ['eng' => 'English', 'fra' => 'French']
$country->independent;          // true
$country->demonyms;             // ['eng' => ['f' => 'Canadian', 'm' => 'Canadian'], ...]
```

### Currency Object

[](#currency-object)

```
$currency = $country->getCurrency();

$currency->getCode();           // 'CAD'
$currency->getName();           // 'Canadian dollar'
$currency->getSymbol();         // '$'
```

### Eloquent Cast

[](#eloquent-cast)

Store country references in your database and cast them automatically:

```
use Orpheus\LaravelCountries\Casts\CountryCast;

class Order extends Model
{
    protected $casts = [
        'country' => CountryCast::class,           // Default: alpha2
        'country' => CountryCast::class . ':alpha3',
        'country' => CountryCast::class . ':numeric',
    ];
}
```

### Macros

[](#macros)

The `Country` class implements Laravel's `Macroable` trait:

```
use Orpheus\LaravelCountries\Country;
use Orpheus\LaravelCountries\Facades\Countries;

Country::macro('getFlag', fn () => sprintf(
    'https://flagcdn.com/w320/%s.png',
    strtolower($this->getAlpha2Code())
));

$country = Countries::getByCode('CAN');
$country->getFlag(); // 'https://flagcdn.com/w320/ca.png'
```

### Mixins

[](#mixins)

```
use Orpheus\LaravelCountries\Country;
use Orpheus\LaravelCountries\Facades\Countries;

class CustomCountry
{
    public function getFlag(): \Closure
    {
        return fn () => sprintf(
            'https://flagcdn.com/w320/%s.png',
            strtolower($this->getAlpha2Code())
        );
    }
}

Country::mixin(new CustomCountry);

$country = Countries::getByCode('CAN');
$country->getFlag(); // 'https://flagcdn.com/w320/ca.png'
```

### Raw Data Access

[](#raw-data-access)

```
use Orpheus\LaravelCountries\Facades\Countries;

$rawData = Countries::getRawData(); // Full array of all country data
```

Configuration
-------------

[](#configuration)

Publish the config file to customize the data source:

```
php artisan vendor:publish --provider="Orpheus\LaravelCountries\ServiceProvider"
```

This creates `config/laravel-countries.php` where you can point to a custom JSON file:

```
return [
    'countries_json_path' => null, // null = use built-in data
];
```

Data Source
-----------

[](#data-source)

Country data is compiled from the [REST Countries v3.1 JSON](https://gitlab.com/restcountries/restcountries) dataset using the included compile script (`scripts/compile-data-source.php`).

### Differences from upstream REST Countries v3.1

[](#differences-from-upstream-rest-countries-v31)

- **Field mapping** — `nativeName` is stored as `native` under the `name` key.
- **Computed field** — `callingCodes` is computed from `idd.root` + `idd.suffixes` for convenience.
- **Translation subset** — Only 26 translation languages are included (ara, bre, ces, cym, deu, est, fin, fra, hrv, hun, ind, ita, jpn, kor, nld, per, pol, por, rus, slk, spa, srp, swe, tur, urd, zho).
- **Currency overrides** — The following corrections are applied to upstream data:
    - **Cuba (CU)** — CUC removed (convertible peso eliminated Jan 1, 2021), CUP only.
    - **Bouvet Island (BV)** — NOK added (uninhabited Norwegian territory).
    - **Heard Island (HM)** — AUD added (uninhabited Australian territory).
    - **Micronesia (FM)** — USD added (sometimes missing upstream).
    - **Antarctica (AQ)** — USD, GBP, EUR added (used at research stations).

### Recompiling Data

[](#recompiling-data)

To regenerate the data source from the latest upstream JSON:

```
composer compile-data-source
```

API Reference
-------------

[](#api-reference)

MethodReturnsDescription`getByCode($code)``Country|null`Lookup by cca2, cca3, ccn3, or cioc`getByName($name)``array`Partial match on common/official/native names`getByFullName($name)``array`Exact match on common or official name`getByLanguage($language)``array`Search by language code or name`getByCapital($capital)``array`Search by capital city (partial)`getByDemonym($demonym)``array`Search by demonym (exact, case-insensitive)`getByTranslation($translation)``array`Search any translation name (partial)`getByCurrency($currency)``array`Search by currency code or name`getByRegion($region)``array`Filter by region`getBySubregion($subregion)``array`Filter by subregion`getIndependent($status)``array`Filter by independence status`getAll($codes, $asCollection)``array|Collection`Get all or filtered countries`getListForDropdown($key, $official, $locale)``array`Key-value pairs for dropdowns`getRawData()``array`Raw country data array### Deprecated Methods (v3.0.0)

[](#deprecated-methods-v300)

Deprecated MethodReplacement`getByAlpha2Code($code)``getByCode($code)``getByAlpha3Code($code)``getByCode($code)``getByNumericCode($code)``getByCode($code)`Credits
-------

[](#credits)

- [Orpheus](https://github.com/opheus2) — Maintainer and fork author.
- [Patrick Samson](https://github.com/patricksamson) — Original [laravel-countries](https://github.com/patricksamson/laravel-countries) package.
- [REST Countries](https://gitlab.com/restcountries/restcountries) — v3.1 country data source (compiled and adapted with overrides).
- [Mohammed Le Doze](https://github.com/mledoze) — Previous data source via [mledoze/countries](https://github.com/mledoze/countries).
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

44

—

FairBetter than 90% of packages

Maintenance86

Actively maintained with recent releases

Popularity25

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity45

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 77.1% 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.

###  Release Activity

Cadence

Every ~172 days

Total

5

Last Release

73d ago

Major Versions

v1.0.1 → v2.0.02025-04-14

v2.0.0 → v3.0.02026-02-12

### Community

Maintainers

![](https://www.gravatar.com/avatar/199954407017ca2b3302d302356617dc43f405b593c798ca11849fa3e6938bd1?d=identicon)[orpheusohms](/maintainers/orpheusohms)

---

Top Contributors

[![patricksamson](https://avatars.githubusercontent.com/u/1416027?v=4)](https://github.com/patricksamson "patricksamson (81 commits)")[![opheus2](https://avatars.githubusercontent.com/u/31169044?v=4)](https://github.com/opheus2 "opheus2 (24 commits)")

---

Tags

laravelcountries

###  Code Quality

TestsPHPUnit

### Embed Badge

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

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

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)[renatomarinho/laravel-page-speed

Laravel Page Speed

2.5k1.7M11](/packages/renatomarinho-laravel-page-speed)[vinkius-labs/laravel-page-speed

Laravel Page Speed

2.5k12.5k1](/packages/vinkius-labs-laravel-page-speed)[emargareten/inertia-modal

Inertia Modal is a Laravel package that lets you implement backend-driven modal dialogs for Inertia apps.

90142.9k](/packages/emargareten-inertia-modal)[wearepixel/laravel-cart

A cart implementation for Laravel

1374.8k](/packages/wearepixel-laravel-cart)[tomshaw/electricgrid

A feature-rich Livewire package designed for projects that require dynamic, interactive data tables.

119.4k](/packages/tomshaw-electricgrid)

PHPackages © 2026

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