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

ActiveLibrary

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

Get informations about countries and their currency.

v3.0.0(3mo ago)06.8k↓50%1MITPHPCI passing

Since Jun 1Pushed 3mo 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 1mo ago

READMEChangelog (4)Dependencies (4)Versions (5)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

42

—

FairBetter than 90% of packages

Maintenance82

Actively maintained with recent releases

Popularity24

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity44

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 77.9% 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 ~207 days

Total

4

Last Release

95d 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 (23 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

[dougsisk/laravel-country-state

Country & state helper for Laravel.

1681.7M](/packages/dougsisk-laravel-country-state)[monarobase/country-list

List of all countries with names and ISO 3166-1 codes in all languages and data formats for Laravel

2672.7M7](/packages/monarobase-country-list)[galahad/laravel-addressing

Laravel package providing addressing functionality

70316.6k](/packages/galahad-laravel-addressing)[dipeshsukhia/laravel-country-state-city-data

Country State City Data Provider

8230.8k](/packages/dipeshsukhia-laravel-country-state-city-data)[io238/laravel-iso-countries

Ready-to-use Laravel models and relations for country (ISO 3166), language (ISO 639-1), and currency (ISO 4217) information with multi-language support.

5462.3k](/packages/io238-laravel-iso-countries)[stidges/laravel-country-flags

A Laravel wrapper for the stidges/country-flags package

28134.6k](/packages/stidges-laravel-country-flags)

PHPackages © 2026

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