README

Description

Countries provides the country reference dataset used across the Laravel Enso ecosystem.

The package ships the countries table, a JSON-backed seeder for the full country list, an Eloquent model with a few convenience behaviors, and an authenticated options endpoint meant for select inputs.

It is a foundational backend package for address management, currencies, webshop flows, and any feature that needs normalized country metadata such as ISO codes, currency details, calling codes, or flags.

Installation

This package comes pre-installed in Laravel Enso applications that require country metadata.

For standalone installation in an Enso-based application:

composer require laravel-enso/countries

The package automatically:

loads its API routes
loads its migrations
publishes its seeders when requested

Run the migrations after installation:

php artisan migrate

If you want the package seeder in your application's database seeders directory, publish it with:

php artisan vendor:publish --tag=countries-seeder

Then seed the table:

php artisan db:seed --class="LaravelEnso\Countries\Database\Seeders\CountrySeeder"

Features

Creates the countries table with ISO, currency, region, and calling metadata.
Ships a JSON-backed seeder for the full country dataset.
Provides an Eloquent Country model with rememberable lookup keys.
Exposes an authenticated options endpoint for select inputs.
Returns only active countries through the options endpoint.
Includes a region label helper that adapts for Romania and the United States.

Usage

Fetch active country options through the API:

route('core.countries.options');

Query the model directly:

use LaravelEnso\Countries\Models\Country;

$romania = Country::whereIso31662('RO')->firstOrFail();

$label = $romania->regionLabel();

The options endpoint serializes countries in a frontend-friendly shape:

{
  "id": 1,
  "name": "Romania",
  "currencyCode": "RON"
}

::: warning Note The package exposes only active countries through its options endpoint.

If you seed or modify the dataset manually, remember that inactive rows will not be returned by core.countries.options. :::

API

Routes

All package routes are registered under:

prefix: api/core/countries
name prefix: core.countries.
middleware: api, auth, core

Endpoints:

GET /api/core/countries/options

Controller

LaravelEnso\Countries\Http\Controllers\Options

Behavior:

builds select-style options through LaravelEnso\Select\Traits\OptionsBuilder
filters by active countries only
allows querying by name and iso_3166_3

Resource

LaravelEnso\Countries\Http\Resources\Country

Serialized attributes:

id
name
currencyCode

Model

LaravelEnso\Countries\Models\Country

Useful traits:

ActiveState
AvoidsDeletionConflicts
HasFactory
Rememberable

Rememberable keys:

id
iso_3166_2
name

Useful method:

regionLabel(): string

Seeder

LaravelEnso\Countries\Database\Seeders\CountrySeeder

Reads the dataset from:

vendor/laravel-enso/countries/database/countries.json

Depends On

Required Enso packages:

Framework dependency:

laravel/framework ↗

Contributions

are welcome. Pull requests are great, but issues are good too.

Thank you to all the people who already contributed to Enso!

laravel-enso / countries

Maintainers

Package info

Statistics

Security