leonardofilhogm/eloquent-countries

Sushi-backed Eloquent countries data and validation rules for Laravel.

v1.0.0 2026-06-29 10:17 UTC

Requires

• php: ^8.2
• akaunting/laravel-money: ^5.2|^6.0
• calebporzio/sushi: ^2.5
• illuminate/database: ^11.0|^12.0
• illuminate/support: ^11.0|^12.0
• propaganistas/laravel-phone: ^5.3

Requires (Dev)

• orchestra/testbench: ^9.0|^10.0
• phpunit/phpunit: ^11.0

MIT

• Trato

• laravel
• countries
• eloquent
• iso
• Iso3166
• sushi

README

Sushi-backed Eloquent countries data and validation rules for Laravel. The full country dataset is baked into the package — no migrations, no database table, no seeders required.

Installation

composer require trato/eloquent-countries

The service provider is auto-discovered. Optionally publish the config:

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

Usage

Querying countries

Trato\EloquentCountries\Models\Countries is a standard Eloquent model, so all query-builder methods work:

use Trato\EloquentCountries\Models\Countries;

Countries::all();
Countries::where('iso2', 'CH')->first();
Countries::where('iso3', 'BRA')->first();
Countries::where('region', 'Europe')->get();

Available columns include: name, official_name, native_name, official_native_name, iso2, iso3, numeric_code, dial_code, capital, region, sub_region, continent, tld, languages, borders, flag, zip_code, startOfWeek, emoji_flag.

Validation rules

use Trato\EloquentCountries\Rules\IsValidCountryCode;   // ISO 3166-1 alpha-2
use Trato\EloquentCountries\Rules\IsValidCountryCode3;  // ISO 3166-1 alpha-3

$request->validate([
    'country'      => ['required', new IsValidCountryCode],
    'country_iso3' => ['required', new IsValidCountryCode3],
]);

Data source

Country data is sourced from restcountries.com. Automatic refresh is disabled — the dataset is baked into the package and updated manually on release. To refresh, re-pull from restcountries.com, update src/Models/Countries.php, and tag a new release.

Caching (Sushi)

This package uses Sushi, which caches the country rows in a local SQLite store. After upgrading the package (when the underlying data changes), clear the Sushi cache so the new rows are picked up:

php artisan cache:clear

If rows still look stale, delete the cached SQLite file Sushi generated for the Countries model (in your framework's cache/storage path) and let it rebuild.

Testing

composer install
composer test

License

MIT