laravel-countries: a country list that lands in your database

Installation is a Composer command and a seeding command

laravel-countries is a Laravel package for handling country data, and the installation is a standard Composer require:

composer require webpatser/laravel-countries

Then there is a second step that is worth noticing, because it says something about the design. The package asks you to run an installation command to set up the database:

php artisan countries:install

So this is not a static array shipped in the package and loaded on demand. The country data is written into your application's database, which means it is queryable with the tools you already have, that it can be joined against your own tables, and that it can be extended with columns of your own without forking the package.

The cost of that choice is a schema, and the repository carries a stubs/ directory, which is where a package like this keeps the migration or the model stub it publishes for the application to use. The presence of stubs is also a hint about the upgrade path, since the data is versioned in your database and the package has to reconcile the two.

The supported platform range is in the badges, PHP 8.2 and above, and Laravel 11, 12 or 13, so the package tracks current Laravel majors rather than striding them, and the licence is MIT.

A record has a short name and a formal one

The quick usage section shows the shape of the data in about six lines.

use Webpatser\Countries\Countries;

$countries = new Countries();
$usa = $countries->getOne('US');
// $usa['name']      => 'United States'
// $usa['full_name'] => 'United States of America'
$allCountries = $countries->getList();
$euroCountries = $countries->getByCurrency('EUR');

The first thing to notice is that a record has two names. The short name is the everyday one, and the full name is the formal one, and they differ for a lot of countries. That single pair of fields is the reason this kind of package exists at all, because a form that shows a country's formal name and a report that shows its common name are different requirements, and hardcoding two columns in your own table means maintaining the list yourself.

The lookup is by the two-letter code, and the class is instantiated directly rather than resolved from the container, so the usage reads like a small utility object. getList returns everything, and getByCurrency returns the set of countries that use a given currency, which is the kind of query that comes up whenever you have a price or an address form.

The repository listing also shows an Eloquent model in the src/ directory, which is the other half of the design. The package does not only offer a query interface, it also publishes a model you can use in your own relations, which means a country can be a foreign key on an order or a subscription record and be eager loaded with everything else.

The query helpers are the reason to use a package at all

The feature list in the README is short, and the interesting items are the ones that are not just data.

There is the data itself, all 249 countries with complete information. There are the two names. There are flag emojis for every country, which saves shipping an image set. There is currency information with filtering by currency, and regional grouping with filtering by region.

Then there are the parts that make it a Laravel package rather than a JSON file. There are Laravel validation rules, so a form field can validate a country against the table without you writing the rule list. There are Collection and String macros, which means the helpers join the collection and string APIs that the framework already exposes everywhere else. And there is Eloquent model support, so a country can be related to your own models rather than looked up by hand.

The list also mentions search and query capabilities in general terms, which is a fair description of a package that gives you both a flat accessor and a queryable table.

Taken together, the design is coherent. The data lives in your database, so the parts of your application that need to join, filter or validate against countries use SQL, and the parts that just need to show a name use the small helper class. The documentation site is listed separately and is not in this repository, which is worth noting for anyone looking for the API reference.

Almost ISO is a warning, and a useful one

The repository description calls the package a bundle providing almost ISO 3166_2, 3166_3, currency, capital and more for all countries, and the README calls it a broad package. The word almost is doing real work there, and it is the most important thing in the description for an evaluator.

The ISO 3166 parts named are the subdivision codes, the two-letter and three-letter country codes, and the numeric codes. A package that claims to cover almost all of them is saying that its coverage is close but not identical, which is exactly what you would expect from a hand-maintained list assembled to match how real applications behave rather than to match a standard exactly.

That difference is not academic. Countries and territories are the classic problem, because a list of countries that satisfies a payment provider is not the same as a list that satisfies a tax authority, and both differ from the list a shipping form wants. A package that includes slightly more or slightly less than the standard is a deliberate choice, and you need to know which choice it made before you use it in a form that has to reject or accept specific territories.

The repository also mentions capitals, which is a good example of a field that is useful in one context and misleading in another. A capital city is unambiguous for most countries and meaningless for many territories, and the package does not claim to resolve that.

So the practical advice is to check the codes you actually need against the data the package installs, rather than trusting the count or the standard reference. The count of 249 is a useful headline, but it is a count of what is in the table, not a statement that the table is authoritative for your regulator.

The repository is small, and the documentation lives elsewhere

The repository listing shows a focused package: a src/ directory, a stubs/ directory, a tests/ directory, a composer.json, a phpunit.xml, a StyleCI configuration, a changelog, a licence file and a .gitattributes file.

The test directory and the phpunit configuration are the parts worth noting, because a package that ships country data has a natural test: the data has to be complete and consistent, and a test suite that checks the seeded rows is what stops a bad release from shipping a country with no currency or a duplicate code. The StyleCI configuration points to automated style checks on the code, which is the convention for a package with this many contributors.

The documentation is somewhere else. The README points to a separate documentation site for the complete documentation, examples and API reference, and it is not hosted in this repository. That is a reasonable choice for a package whose documentation is written with a static site generator, but it does mean the repository README is an introduction rather than a reference.

The release picture is a slow, major-versioned one. The listed releases are v2.1.2 from April 2026 and v2.2.2 from September 2026, with the last push on the same day as the newer tag, so the package is being maintained and the data is being refreshed on a schedule that follows the underlying lists rather than the code.

The version 2 line also means the API has had time to settle, and the changelog is where you would look for the country additions and corrections between releases, which for a data package is the most useful part of the release notes.

Editorial conclusion

Adopt laravel-countries if your Laravel application needs a maintained country and currency list with regional grouping and validation rules already written, and you are comfortable adding a seeded table to your database. Do not adopt it if your data has to match a regulatory standard exactly, because the package describes its coverage as almost ISO 3166_2 and 3166_3, so verify the specific codes your compliance requirements name. Before you install, check that the country count and the code format match what your form and your reporting expect, and read the changelog, since the package sits at version 2.2.2 and the list of countries changes over time.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. webpatser/laravel-countries on GitHub