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

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

woodsandwalker/laravel-countries
================================

Laravel Countries is a bundle for Laravel providing ISO 3166\_2 codes for all countries along with a country model, cast and validation rule.

1.5.0(1y ago)109.5k↑13.3%3MITPHPPHP ^8.0|^8.1|^8.2|^8.3

Since Oct 18Pushed 1y ago1 watchersCompare

[ Source](https://github.com/woodsandwalker/laravel-countries)[ Packagist](https://packagist.org/packages/woodsandwalker/laravel-countries)[ Docs](https://github.com/woodsandwalker/laravel-countries)[ RSS](/packages/woodsandwalker-laravel-countries/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (2)Versions (8)Used By (0)

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

[](#laravel-countries)

[![Packagist Downloads](https://camo.githubusercontent.com/4d46f0af9f259bf7b2e20d63739473aa3929f053fea14fe907a2612d907d2f9d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f776f6f6473616e6477616c6b65722f6c61726176656c2d636f756e74726965733f636f6c6f723d627269676874677265656e3f)](https://packagist.org/packages/woodsandwalker/laravel-countries)[![Packagist Version](https://camo.githubusercontent.com/6c3e2394581817e14e4e5f8de8000c244c7d6a84cc1e8ef4f7f6872143a93cda/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f776f6f6473616e6477616c6b65722f6c61726176656c2d636f756e74726965733f636f6c6f723d627269676874677265656e3f)](https://packagist.org/packages/woodsandwalker/laravel-countries)

Laravel Countries is a bundle for Laravel providing ISO 3166\_2 codes for all countries along with a country model, cast and validation rule.

Getting Stated
--------------

[](#getting-stated)

### Installation

[](#installation)

```
composer require woodsandwalker/laravel-countries
```

### Configuration

[](#configuration)

There is minimal config and the package can be used without any configuration. The only configuration option is an array of countries to exclude. This works by applying a global scope on the Country model.

To publish the configuration you can run this command:

```
php artisan vendor:publish --tag=countries-config
```

To exclude a country simply add its ISO code to the exclude array:

```
[
    'exclude' => ['GB']
]
```

### Model

[](#model)

The package contains a [calebporzio/sushi](https://packagist.org/packages/calebporzio/sushi) model which contains the `iso_code` and `name` for each country. Using this type of model also means there is no database migration required.

This model can be used like any other Laravel model.

```
$countryName = \WW\Countries\Models\Country::whereIsoCode('GB')->first()->name; // United Kingdom
```

### Validation Rule

[](#validation-rule)

The package contains a validation rule which validates the ISO code.

```
$data = $request->validate([
    'country' => ['required', new \WW\Countries\Rules\Country]
]);
```

You can override the default validation error message using the `validation.country` key in your lang files.

### Model Attribute Cast

[](#model-attribute-cast)

The package contains a model attribute cast. The cast expects the ISO code as the original attribute.

You can use the following migration to add a country column to the users table.

```
Schema::table('users', function (Blueprint  $table) {
    $table->char('country', 2);
});
```

Then add the cast to the user model:

```
class User extends Model
{
    /**
     * The attributes that should be cast.
     *
     * @var array
     */
    protected $casts = [
        'country' => \WW\Countries\Casts\Country::class,
    ];
}
```

Store a country against a user:

```
$user = User::find(1);

$user->country = 'GB';
$user->save();
```

You can now access the ISO code and the name on the country attribute on the user model:

```
$user = User::find(1);

$countryIsoCode = $user->country->iso_code; // GB
$countryName = $user->country->name; // United Kingdom
```

Localization
------------

[](#localization)

When accessing a country name the model will look for a translation string of `countries.{ISO_CODE}`, for example, `countries.GB`. If this translation string cannot be found it will fallback to the `en` locale.

### Installing New Locales

[](#installing-new-locales)

A command is included with the package to install new country locales from [umpirsky/country-list](https://github.com/umpirsky/country-list). You can view all the available locales [here](https://github.com/umpirsky/country-list/tree/master/data). This command will create a new file in `lang/{locale}/countries.php`. This command uses the `file_get_contents` function which requires `allow_url_fopen` to be on in your PHP config.

To install a new locale, for example Spanish (es), run the command:

```
php artisan countries:install-translation es
```

License
-------

[](#license)

Laravel Countries is released under the MIT License. See the bundled LICENSE.md file for details.

###  Health Score

42

—

FairBetter than 90% of packages

Maintenance43

Moderate activity, may be stable

Popularity33

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity66

Established project with proven stability

 Bus Factor1

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

Recently: every ~215 days

Total

6

Last Release

447d ago

PHP version history (3 changes)1.1.0PHP ^8.0|^8.1

1.3.0PHP ^8.0|^8.1|^8.2

1.4.0PHP ^8.0|^8.1|^8.2|^8.3

### Community

Maintainers

![](https://www.gravatar.com/avatar/3a0bab1faf265c9d25f9a7d0885369ddb33c0416d29a0ee12dbefb06cb2a53b6?d=identicon)[james\_walker](/maintainers/james_walker)

---

Top Contributors

[![lukas-frey](https://avatars.githubusercontent.com/u/10926334?v=4)](https://github.com/lukas-frey "lukas-frey (1 commits)")[![woodsandwalker](https://avatars.githubusercontent.com/u/35920888?v=4)](https://github.com/woodsandwalker "woodsandwalker (1 commits)")

---

Tags

laravelcountries

### Embed Badge

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

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

###  Alternatives

[barryvdh/laravel-ide-helper

Laravel IDE Helper, generates correct PHPDocs for all Facade classes, to improve auto-completion.

14.9k123.0M687](/packages/barryvdh-laravel-ide-helper)[webpatser/laravel-countries

Modern Laravel Countries package providing ISO 3166-2, ISO 3166-3, currency, capital and more for all countries. Compatible with Laravel 11.x and 12.x.

8272.8M8](/packages/webpatser-laravel-countries)[dougsisk/laravel-country-state

Country & state helper for Laravel.

1681.7M](/packages/dougsisk-laravel-country-state)[matt-daneshvar/laravel-survey

Create surveys inside your Laravel app

28770.3k](/packages/matt-daneshvar-laravel-survey)[bhuvidya/laravel-countries

Laravel Countries is a bundle for Laravel, providing Almost ISO 3166\_2, 3166\_3, currency, Capital and more for all countries. Bug kudos to Christoph Kempen, on whose work this package is heavily based (webpatser/laravel-countries).

3229.9k1](/packages/bhuvidya-laravel-countries)[usamamuneerchaudhary/country-city-state

Country City State Data Provider for Laravel 12+

242.6k](/packages/usamamuneerchaudhary-country-city-state)

PHPackages © 2026

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