Countries Laravel Package

Getting Started

Install the package with Composer and publish any shipped config/seed assets:

composer require pod-point/countries
php artisan vendor:publish --provider="PodPoint\Countries\CountriesServiceProvider"

Check the package README and config/countries.php first — this is where locale behaviour, table names, and lookup sources are configured. If the package ships migrations or a seeder, run them before touching application code:

php artisan migrate
php artisan db:seed --class=CountriesSeeder

The quickest first use case is a country select on a registration or checkout form: pull the country list, render a <select> keyed by ISO alpha-2 code, and validate the submitted value against the package's rule. From v3.2.2 onward you can request Spanish or French country names simply by setting the application locale (es / fr) before resolving the list, so a single set of views can serve multiple storefronts.

Implementation Patterns

Validation. Use the package's country-code rule rather than a hand-rolled in: list. This keeps validation aligned with the data the package ships and automatically covers new territories when you upgrade:

$request->validate([
    'country' => ['required', 'string', 'country_code'], // confirm exact rule name in README
]);

Localised name resolution. The headline of v3.2.2 is the addition of es and fr locales. Resolve country names inside the request lifecycle (or explicitly pass a locale) rather than caching a single-language list:

app()->setLocale('fr');
$countries = Countries::all(); // names rendered in French

// or explicit, if the API supports it
Countries::locale('es')->all();

For multi-locale APIs, expose the locale as a request header/query parameter and resolve names per request. Avoid storing localised display names in your own tables unless you also store the locale alongside them.

Form and API presentation. Keep the canonical ISO code as the persisted value and treat the localised name as presentation only:

return CountryResource::collection(
    Countries::all()
)->map(fn ($country) => [
    'code' => $country->iso_alpha2,
    'name' => $country->name,
]);

Caching. Country data is effectively static. Cache the resolved list per locale with a long TTL, and key the cache on the locale so adding es/fr does not cause stale mixed-language payloads:

$countries = Cache::rememberForever("countries.{$locale}", fn () => Countries::locale($locale)->all());

Clear these keys in your deployment script when you bump the package version.

Seeding and testing. In tests, use RefreshDatabase and run the package seeder in setUp rather than asserting against a partially populated table. If you only need a handful of countries in a feature test, seed the full table and query by ISO code — it is faster to reason about than fixture subsets.

Gotchas and Tips

• Locale coverage is still narrow. v3.2.2 adds Spanish and French on top of the existing set. If your app ships other locales, verify the package falls back gracefully (usually to the default locale) instead of returning empty names or raw keys. Test de, it, etc. explicitly.
• v3.2.2 is additive and non-breaking. The changelog only adds locales; no deprecations or signature changes are listed. It is a safe patch upgrade, but re-run your test suite if you assert on the exact number of locales or on locale config arrays.
• Alpha-2 vs alpha-3 confusion. Pick one code format for persistence (alpha-2 is the common choice) and enforce it at the validation boundary. Mixing formats is a frequent source of "country not found" bugs in lookups.
• Case sensitivity. Normalise submitted codes to uppercase before validation/lookup; 'gb' vs 'GB' behaviour depends on the underlying data source and can differ between database collations.
• Stale data after upgrade. New locales and any refreshed country lists won't appear until caches are cleared and seeders re-run. Add php artisan cache:clear (or targeted key deletion) to your release routine.
• The "API3 / 3.2 base" note in the release indicates forward planning for a future API. Pin to ^3.2 in composer.json so you get locale additions without accidentally crossing into a 4.x API rewrite.
• Extension points. Prefer overriding via published config and container binding (custom repository/loader) over editing vendor files. If you need additional locales before upstream ships them, back the package with your own translation source and bind it — do not fork unless necessary.
• Debugging missing countries. If a country disappears from a select, check the seeder ran, the config isn't filtering by continent/active flag, and the cache key matches the current locale.