README

Database-driven language and country management for Laravel 13.

• Languages — ISO 639-1, enabled/default flags
• Countries — ISO 3166-1 alpha-2, flag emoji, timezone, E.164 calling code, primary language
• Octane-safe — stateless singleton service, current locale read dynamically per request

Requirements

Installation

composer require rdcstarr/laravel-locale

Run the install command to publish and run migrations, then seed languages, countries and their relationships:

php artisan locale:install

Manual installation

If you prefer to control the process yourself, publish the migrations without running the install command:

php artisan vendor:publish --tag=laravel-locale-migrations

Then run the migrations and seed the reference data:

php artisan migrate
php artisan db:seed --class="Rdcstarr\Locale\Database\Seeders\LanguagesSeeder"
php artisan db:seed --class="Rdcstarr\Locale\Database\Seeders\CountriesSeeder"
php artisan db:seed --class="Rdcstarr\Locale\Database\Seeders\CountryLanguageSeeder"

Note: Migrations run automatically without publishing — skip vendor:publish if you do not need to modify the migration files.

Languages

use Locale;

// All enabled languages
Locale::enabledLanguages();

// Default language
Locale::defaultLanguage();

// Find by ISO 639-1 code
Locale::languageByCode('ro');

// code → id map (useful for seeding)
Locale::enabledLanguageCodeToId();

// Raw query builder
Locale::languages()->where('enabled', true)->get();

Countries

use Locale;

// Find by ISO 3166-1 alpha-2 code
Locale::countryByCode('RO');

// Phone prefix (ITU-T E.164, e.g. "+40")
Locale::callingCodeByCode('RO');     // → "+40"
country_calling_code('RO');          // → "+40"  (global helper)
Locale::countryByCode('RO')->calling_code;  // direct model access

// All countries sharing a calling code (e.g. NANP "+1")
Locale::countries()->byCallingCode('+1')->get();

// All countries that use a given language
Locale::countriesForLanguage('ro');

// code → id map (useful for seeding)
Locale::countryCodeToId();

// Raw query builder
Locale::countries()->with('primaryLanguage')->get();

Models

Language

Country

The country_language pivot table stores all official languages per country with an is_official boolean.

Octane compatibility

LocaleService is registered as a singleton but stores no request-scoped state — the current locale is always read dynamically via app()->getLocale(), so it is safe to reuse across requests on a long-lived worker.