Laravel ISO Countries

https://github.com/io238/laravel-iso-countries
Admin
A Laravel package that provides ready-to-use application models and seeds a database with...
Tokens:34,811
Snippets:275
Trust Score:5.4
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Example - basic call to languages()

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/country-model.md

Shows basic usage of the languages relationship, including accessing the collection directly and using pluck to get language IDs. The example retrieves official languages for Luxembourg ('LU').

```php
use Io238\ISOCountries\Models\Country;

// Official languages spoken in Luxembourg
Country::find('LU')->languages;

// -> Collection of Language models: ['lb' (Luxembourgish), 'de', 'fr']
Country::find('LU')->languages()->pluck('id'); // ["lb", "de", "fr"]
```

--------------------------------

### Install via Composer

Source: https://github.com/io238/laravel-iso-countries/blob/main/README.md

Use this command to add the package to your Laravel project.

```bash
composer require io238/laravel-iso-countries
```

--------------------------------

### Config override example

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/isocountries-service-provider.md

Demonstrates how published configuration files override the default package settings after the register() method is called.

```php
// config/iso-countries.php (published with --tag="config")
return [
    'locales' => ['en', 'de', 'fr', 'es'],
    'database_path' => database_path('iso-countries.sqlite'),
];

// After register(), the merged value is readable:
config('iso-countries.locales');       // ['en', 'de', 'fr', 'es'] (app value wins)
config('iso-countries.database_path'); // database_path('iso-countries.sqlite')
```

--------------------------------

### Verify connection registration

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/isocountries-service-provider.md

Example showing how the iso-countries connection is registered and used by models after auto-discovery.

```php
// composer.json (of the consuming project) — auto-discovery happens automatically,
// no manual provider registration needed. After boot, Laravel knows the connection:
config('database.connections.iso-countries');
// ['driver' => 'sqlite', 'database' => '/abs/path/to/iso-countries.sqlite']

// The models use this connection by default:
Io238\ISOCountries\Models\Country::find('DE')->getConnectionName(); // 'iso-countries'
```

--------------------------------

### currencies() basic call example

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/country-model.md

Shows how to retrieve currency IDs for a country using the currencies relation. Uses Country::find('GH') and Country::find('US') to get currency IDs.

```php
use Io238\ISOCountries\Models\Country;

// Currencies used in Ghana
Country::find('GH')->currencies->pluck('id'); // ["GHS"]

// Currencies used in the United States
Country::find('US')->currencies->pluck('id'); // ["USD"]
```

--------------------------------

### Catching MissingSqliteExtensionException

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/errors.md

Example of how to catch the exception during the application boot phase to allow for graceful handling.

```php
try {
    // boot the app / run something that boots providers
} catch (\Io238\ISOCountries\Exceptions\MissingSqliteExtensionException $e) {
    // graceful handling, e.g. log + skip ISO features
}
```

--------------------------------

### Catching MissingSqliteExtensionException during test bootstrap

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/missing-sqlite-extension-exception.md

An example of how to catch the exception within a test case setup to skip tests if the extension is missing.

```php
use Io238\ISOCountries\Exceptions\MissingSqliteExtensionException;
use Orchestra\Testbench\TestCase as Orchestra;

class TestCase extends Orchestra
{
    protected function getPackageProviders($app)
    {
        return [\Io238\ISOCountries\ISOCountriesServiceProvider::class];
    }

    protected function setUp(): void
    {
        try {
            parent::setUp();
        } catch (MissingSqliteExtensionException $e) {
            $this->markTestSkipped('pdo_sqlite extension not available: ' . $e->getMessage());
        }
    }
}
```

--------------------------------

### Basic slug usage

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/base-model.md

Example of accessing the slug attribute for Country models.

```php
use Io238\ISOCountries\Models\Country;

Country::find('AD')->slug; // "andorra"
Country::find('US')->slug; // "united-states"
```

--------------------------------

### resolveRouteBinding() basic usage

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/language-model.md

Example of implicit route model binding for a language code.

```php
// routes/web.php
Route::get('/languages/{language}', function (Io238\ISOCountries\Models\Language $language) {
    return $language->name;
});

// GET /languages/EN -> resolves to Language with id "en"
```

--------------------------------

### Currency::get implementation

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/currency-cast.md

The get method resolves the stored ISO code to a Currency model instance.

```php
/**
 * Cast the given value.
 *
 * @param \Illuminate\Database\Eloquent\Model $model
 * @param string                              $key
 * @param mixed                               $value
 * @param array                               $attributes
 * @return array
 */
public function get($model, $key, $value, $attributes)
{
    return CurrencyModel::find(strtoupper($value));
}
```

--------------------------------

### Manual check for pdo_sqlite extension

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/isocountries-service-provider.md

Example of manually verifying the pdo_sqlite extension before relying on the package.

```php
if (! extension_loaded('pdo_sqlite')) {
    throw new \Io238\ISOCountries\Exceptions\MissingSqliteExtensionException();
}
```

--------------------------------

### Example - assigning a model instance

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/country-cast.md

Shows how to assign a Country model instance to the cast attribute. The stored value is the model's id (uppercased). The example uses CountryModel::find('CH') and then reads the raw original value to confirm the stored code.

```php
use Io238\ISOCountries\Models\Country as CountryModel;

$model = MyModel::query()->first();
$model->update(['country' => CountryModel::find('CH')]);

// The currency_code column now contains "CH":
$model->getRawOriginal('country'); // "CH"
```

--------------------------------

### Example - query usage with whereHas and eager loading

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/country-model.md

Shows query usage of the languages relationship, including filtering countries where English is an official language using whereHas, and eager loading the relationship with the with() method.

```php
// Countries where English ('en') is an official language
$englishSpeaking = Country::query()->whereHas('languages', function ($q) {
    $q->where('languages.id', 'en');
})->pluck('id');

// Eager loading
$country = Country::with('languages')->find('MX');
$country->languages->count(); // > 0
```

--------------------------------

### neighbours() basic call example

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/country-model.md

Shows how to retrieve neighbouring country IDs using the neighbours relation. Uses Country::find('LU') and Country::find('US') to get neighbour IDs.

```php
use Io238\ISOCountries\Models\Country;

// Land borders of Luxembourg
Country::find('LU')->neighbours->pluck('id'); // ["BE", "DE", "FR"]

// Borders of the United States
Country::find('US')->neighbours->pluck('id'); // ["CA", "MX"]
```

--------------------------------

### resolveRouteBinding() with custom field

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/language-model.md

Example of resolving by a specific column while maintaining case normalization.

```php
// Resolving by the iso639_2 column, still case-normalized to lowercase:
Route::get('/languages/by-code/{language:iso639_2}', function (Io238\ISOCountries\Models\Language $language) {
    return $language->id;
});

// GET /languages/by-code/DEU -> Language id "de"
```

--------------------------------

### Basic usage of route binding

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/currency-model.md

Example of implicit route model binding in a Laravel web route.

```php
// routes/web.php
Route::get('/currencies/{currency}', function (Io238\ISOCountries\Models\Currency $currency) {
    return $currency->symbol_native;
});

// GET /currencies/usd -> resolves to Currency with id "USD"
```

--------------------------------

### Example - basic call assigning a code

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/country-cast.md

Shows how to assign a raw ISO code string to the cast attribute. The value is stored uppercased; assigning 'us' stores 'US'. Assigning 'USD' (a non-existent country) stores 'USD' but the attribute reads back null.

```php
$model = MyModel::query()->first();
$model->update(['country' => 'us']);      // stored as "US"
$model->update(['country' => 'USD']);     // stored as "USD" (no such country; attribute reads back null)
```

--------------------------------

### neighbours() non-trivial: combine with language relation

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/country-model.md

Shows how to get neighbouring countries of Switzerland with German as official language. Uses the neighbours() relation and pluck to get IDs.

```php
use Io238\ISOCountries\Models\Country;

// Neighbouring countries of Switzerland with German as official language
Country::find('CH')->neighbours()->pluck('id'); // -> ["AT", "DE", "FR", "IT", "LI"]
```

--------------------------------

### Implement get method for Country cast

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/country-cast.md

The get method is called by Eloquent to transform the raw database value into a Country model instance.

```php
/**
 * Cast the given value.
 *
 * @param \Illuminate\Database\Eloquent\Model $model
 * @param string                              $key
 * @param mixed                               $value
 * @param array                               $attributes
 * @return array
 */
public function get($model, $key, $value, $attributes)
{
    return CountryModel::find(strtoupper($value));
}
```

--------------------------------

### get method implementation of Language cast

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/language-cast.md

The get method resolves the raw value to a Language model by lowercasing it and calling LanguageModel::find(). Returns null for unknown or empty codes.

```php
/**
 * Cast the given value.
 *
 * @param \Illuminate\Database\Eloquent\Model $model
 * @param string                              $key
 * @param mixed                               $value
 * @param array                               $attributes
 * @return array
 */
public function get($model, $key, $value, $attributes)
{
    return LanguageModel::find(strtolower($value));
}
```

--------------------------------

### Basic usage of resolveRouteBinding with route definition

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/country-model.md

Shows a route definition that uses implicit route model binding with the Country model. The comment indicates that GET /countries/us resolves to the Country with id "US".

```php
// routes/web.php
Route::get('/countries/{country}', function (Io238\ISOCountries\Models\Country $country) {
    return $country->name;
});

// GET /countries/us  -> resolves to Country with id "US"
```

--------------------------------

### Handle MissingSqliteExtensionException in Handler

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/isocountries-service-provider.md

Example of reporting the MissingSqliteExtensionException within the Laravel exception handler.

```php
// app/Exceptions/Handler.php
use Io238\ISOCountries\Exceptions\MissingSqliteExtensionException;

public function register(): void
{
    $this->reportable(function (MissingSqliteExtensionException $e) {
        Log::critical('ISO Countries package requires pdo_sqlite', [
            'message' => $e->getMessage(),
        ]);
    });
}
```

--------------------------------

### Basic call to Language cast get

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/language-cast.md

Shows how the cast resolves an uppercase code 'EN' to a Language instance and accesses its properties. The cast lowercases the value before lookup.

```php
$model = MyModel::make(['language' => 'EN']);

$model->language;              // Io238\ISOCountries\Models\Language instance
$model->language->iso639_2;    // "eng"
$model->language->iso639_2b;   // "eng"
$model->language->family;      // "Indo-European"
$model->language->countries;   // countries with English as official language (relation)
```

--------------------------------

### Unknown or empty code yields null

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/language-cast.md

When the stored code does not exist, the cast returns null. This example shows how to handle that case safely.

```php
$model = MyModel::make(['language' => 'xx']); // no such ISO 639-1 code

$model->language; // null

if ($model->language !== null) {
    echo $model->language->native_name;
} else {
    echo 'Unknown language';
}
```

--------------------------------

### get($model, $key, $value, $attributes)

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/currency-cast.md

Casts the given value by resolving the stored ISO 4217 code to a Currency model instance. Returns null for unknown or empty codes.

```APIDOC
## get($model, $key, $value, $attributes)

### Description
Casts the given value by resolving the stored ISO 4217 code to a Currency model instance. Returns null for unknown or empty codes.

### Method
Cast method (Eloquent custom cast)

### Parameters
- **$model** (\Illuminate\Database\Eloquent\Model) - Required - The parent Eloquent model instance being cast.
- **$key** (string) - Required - The attribute name on the parent model.
- **$value** (mixed) - Required - Raw value from the database (e.g. 'eur' or 'EUR').
- **$attributes** (array) - Required - All raw attributes of the parent model.

### Return Type
Io238\ISOCountries\Models\Currency - The resolved currency model, or null when the code is not found (also for null/empty input).

### Throws
None. Unknown codes produce null, not an error.

### Example - basic call
```php
$model = MyModel::make(['currency' => 'JPY']);

$model->currency;                // Io238\ISOCountries\Models\Currency instance
$model->currency->symbol;        // "¥"
$model->currency->symbol_native; // "￥"
$model->currency->decimal_digits;// 0
$model->currency->countries;     // countries using JPY (relation)
```

### Example - unknown or empty code yields null
```php
$model = MyModel::make(['currency' => 'XYZ']); // no such ISO 4217 code

$model->currency; // null

// Guard against null:
if ($model->currency === null) {
    // fall back to a default currency
}
```
```

--------------------------------

### get($model, $key, $value, $attributes)

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/language-cast.md

Casts the given value by resolving the lowercased ISO 639-1 code to a Language model instance. Returns null for unknown or empty codes.

```APIDOC
## get($model, $key, $value, $attributes)

### Description
Casts the given value by resolving the lowercased ISO 639-1 code to a Language model instance. Returns null for unknown or empty codes.

### Method
get

### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| $model | \Illuminate\Database\Eloquent\Model | yes | The parent Eloquent model instance being cast. |
| $key | string | yes | The attribute name on the parent model. |
| $value | mixed | yes | Raw value from the database (e.g. 'EN' or 'en'). |
| $attributes | array | yes | All raw attributes of the parent model. |

### Return type
Io238\ISOCountries\Models\Language — the resolved language model — or null when the code is not found (also for null/empty input).

### Throws
None. Unknown codes produce null, not an error.

### Example — basic call
```php
$model = MyModel::make(['language' => 'EN']);

$model->language;              // Io238\ISOCountries\Models\Language instance
$model->language->iso639_2;    // "eng"
$model->language->iso639_2b;   // "eng"
$model->language->family;      // "Indo-European"
$model->language->countries;   // countries with English as official language (relation)
```

### Example — unknown or empty code yields null
```php
$model = MyModel::make(['language' => 'xx']); // no such ISO 639-1 code

$model->language; // null

if ($model->language !== null) {
    echo $model->language->native_name;
} else {
    echo 'Unknown language';
}
```
```

--------------------------------

### Assigning a Language model instance to the cast

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/language-cast.md

When assigning a Language model instance, the cast uses its id (the ISO code) and lowercases it. The example shows the raw original value after update.

```php
use Io238\ISOCountries\Models\Language as LanguageModel;

$model = MyModel::query()->first();
$model->update(['language' => LanguageModel::find('fr')]);

$model->getRawOriginal('language'); // "fr"
```

--------------------------------

### get($model, $key, $value, $attributes)

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/country-cast.md

Cast the given value. Called by Eloquent when the cast attribute is read. The stored value is uppercased and looked up by primary key; the resulting Country model instance (or null) is returned.

```APIDOC
## get($model, $key, $value, $attributes)

### Description
Cast the given value. Called by Eloquent when the cast attribute is read. The stored value is uppercased and looked up by primary key; the resulting Country model instance (or null) is returned.

### Method
Cast method (Eloquent custom cast)

### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `$model` | `\Illuminate\Database\Eloquent\Model` | yes | The parent Eloquent model instance being cast. |
| `$key` | `string` | yes | The attribute name on the parent model. |
| `$value` | `mixed` | yes | Raw value from the database (e.g. 'lu' or 'LU'). |
| `$attributes` | `array` | yes | All raw attributes of the parent model. |

### Return type
`Io238\ISOCountries\Models\Country` — the resolved country model — or `null` when the code is not found in the `countries` table (also for `null`/empty input).

### Throws
None. Unknown codes produce `null`, not an error.

### Example — basic call
```php
$model = MyModel::make(['country' => 'LU']);

$model->country;                   // Io238\ISOCountries\Models\Country instance
$model->country->alpha3;           // "LUX"
$model->country->name;             // localized name, e.g. "Luxembourg"
$model->country->languages;        // official languages relation works as usual
$model->country->currencies;       // ["EUR"]
```

### Example — unknown or empty code yields null
```php
$model = MyModel::make(['country' => 'XQ']); // no such ISO code

$model->country; // null

// Guard against null:
if ($model->country !== null) {
    echo $model->country->capital;
} else {
    echo 'Unknown country';
}
```
```

--------------------------------

### boot() method signature

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/isocountries-service-provider.md

The boot method signature as defined in the service provider.

```php
public function boot()
```

--------------------------------

### Publish Configuration

Source: https://github.com/io238/laravel-iso-countries/blob/main/README.md

Publish the package configuration file to customize locales and database storage paths.

```bash
php artisan vendor:publish --provider="Io238\ISOCountries\ISOCountriesServiceProvider" --tag="config"
```

--------------------------------

### Pointing a PDO connection to the package database

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/isocountries-service-provider.md

Uses the path returned by getPackageDatabaseFile() to initialize a raw PDO connection for querying the database.

```php
use Io238\ISOCountries\ISOCountriesServiceProvider;

$pdo = new PDO('sqlite:' . ISOCountriesServiceProvider::getPackageDatabaseFile());

$count = $pdo->query('SELECT COUNT(*) FROM countries')->fetchColumn();
// int(250)
```

--------------------------------

### Accessing Country, Language, and Currency Relationships

Source: https://github.com/io238/laravel-iso-countries/blob/main/README.md

Demonstrates how to retrieve related data such as official languages for a country, currencies for a country, countries by language, and countries by currency.

```php
// Official languages spoken in Luxembourg ('LU')
Country::find('LU')->languages;

// Currencies used in Ghana ('GH')
Country::find('GH')->currencies;

// Countries that have Spanish ('es') as one of their official languages 
Language::find('es')->countries;

// Countries that use the Euro ('EUR') as currency
Currency::find('EUR')->countries;
```

--------------------------------

### Run tests with Composer

Source: https://github.com/io238/laravel-iso-countries/blob/main/README.md

Execute the project's test suite using the Composer package manager.

```bash
composer test
```

--------------------------------

### Basic call to getPackageDatabaseFile()

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/isocountries-service-provider.md

Retrieves the path to the package database file using the static method.

```php
use Io238\ISOCountries\ISOCountriesServiceProvider;

$file = ISOCountriesServiceProvider::getPackageDatabaseFile();
// e.g. '/app/vendor/io238/laravel-iso-countries/data/iso-countries.sqlite'
```

--------------------------------

### Contents of config/iso-countries.php

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/configuration.md

The default configuration file defines supported locales and the storage path for the SQLite database.

```php
<?php

return [

    // Supported locales for names (countries, languages, currencies)
    'locales' => [
        'en',
        'de',
        'fr',
        'es',
    ],

    // Path for storing your own SQLITE database
    'database_path' => database_path('iso-countries.sqlite'),

];
```

--------------------------------

### set($model, $key, $value, $attributes)

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/currency-cast.md

Prepares the given value for storage by converting it to an uppercase ISO 4217 code string. Accepts a string or a Currency model instance.

```APIDOC
## set($model, $key, $value, $attributes)

### Description
Prepares the given value for storage by converting it to an uppercase ISO 4217 code string. Accepts a string or a Currency model instance.

### Method
Cast method (Eloquent custom cast)

### Parameters
- **$model** (\Illuminate\Database\Eloquent\Model) - Required - The parent Eloquent model being cast.
- **$key** (string) - Required - The attribute name on the parent model.
- **$value** (string | Io238\ISOCountries\Models\Currency | mixed) - Required - The assigned value: ISO code string or Currency model instance.
- **$attributes** (array) - Required - All raw attributes of the parent model.

### Return Type
string - The uppercased ISO 4217 code to persist.

### Throws
None; however, object values that are neither strings nor Currency instances are passed to strtoupper() directly, which raises a PHP TypeError/ValueError at runtime - the source does not guard other types.

### Example - basic call (assigning a code)
```php
$model = MyModel::query()->first();
$model->update(['currency' => 'usd']); // stored as "USD"
```

### Example - assigning a model instance
```php
use Io238\ISOCountries\Models\Currency as CurrencyModel;

$model = MyModel::query()->first();
$model->update(['currency' => CurrencyModel::find('EUR')]);

$model->getRawOriginal('currency'); // "EUR"
```
```

--------------------------------

### Configuration File Contents

Source: https://github.com/io238/laravel-iso-countries/blob/main/README.md

The default structure of the published configuration file, defining supported locales and the SQLite database path.

```php
[
    // Supported locales for names (countries, languages, currencies)
    'locales' => [
        'en',
        'de',
        'fr',
        'es',
    ],

    // Path for storing your own SQLITE database
    'database_path' => database_path('iso-countries.sqlite'),
];
```

--------------------------------

### Retrieve countries by currency

Source: https://github.com/io238/laravel-iso-countries/blob/main/README.md

Demonstrates querying the countries relationship for a specific currency and plucking the names.

```php
// Retrieve all countries that use the Euro (EUR) as currency.
Currency::find('EUR')->countries->pluck('name');

Illuminate\Support\Collection {
     all: [
       "Andorra",
       "Austria",
       "Åland Islands",
       "Belgium",
       "St. Barthélemy",
       "Cyprus",
       "Germany",
       "Estonia",
       "Spain",
       "Finland",
       "France",
       "French Guiana",
       "Guadeloupe",
       "Greece",
       "Ireland",
       "Italy",
       "Lithuania",
       "Luxembourg",
       "Latvia",
       "Monaco",
       "Montenegro",
       "St. Martin",
       "Martinique",
       "Malta",
       "Netherlands",
       "St. Pierre & Miquelon",
       "Portugal",
       "Réunion",
       "Slovenia",
       "Slovakia",
       "San Marino",
       "French Southern Territories",
       "Vatican City",
       "Republic of Kosovo",
       "Mayotte",
       "Zimbabwe",
     ],
   }
```

--------------------------------

### Fallback handling for unknown currency codes

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/currency-model.md

Demonstrates how to handle cases where a currency code does not exist in the database.

```php
use Io238\ISOCountries\Models\Currency;

// Currency::find() returns null (not an exception) for unknown codes:
$currency = Currency::find('ZZZ');

if ($currency === null) {
    abort(404, "Unknown currency code");
}

$currency->name; // e.g. "Euro"
```

--------------------------------

### Basic call to Language cast set with a code

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/language-cast.md

Assigning a code string to the language attribute stores it lowercased. The example updates a model with 'DE' and stores 'de'.

```php
$model = MyModel::query()->first();
$model->update(['language' => 'DE']); // stored as "de"
```

--------------------------------

### Currency::set implementation

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/currency-cast.md

The set method prepares the value for storage by ensuring it is an uppercase ISO code string.

```php
/**
 * Prepare the given value for storage.
 *
 * @param \Illuminate\Database\Eloquent\Model $model
 * @param string                              $key
 * @param array                               $value
 * @param array                               $attributes
 * @return string
 */
public function set($model, $key, $value, $attributes)
{
    return strtoupper($value instanceof CurrencyModel ? $value->id : $value);
}
```

--------------------------------

### Build command locale collection

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/configuration.md

This snippet demonstrates how the package collects and deduplicates locales from the application configuration and the package-specific configuration during the build process.

```php
$locales = collect(config('app.locale'))
    ->merge(config('app.fallback_locale'))
    ->merge(config('iso-countries.locales'))
    ->unique();
```

--------------------------------

### Assigning a Currency model instance

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/currency-cast.md

Assigning a Currency model instance will extract its ID for storage.

```php
use Io238\ISOCountries\Models\Currency as CurrencyModel;

$model = MyModel::query()->first();
$model->update(['currency' => CurrencyModel::find('EUR')]);

$model->getRawOriginal('currency'); // "EUR"
```

--------------------------------

### Handling unknown or empty codes

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/country-cast.md

Shows how the cast returns null for invalid ISO codes and how to safely handle the result.

```php
$model = MyModel::make(['country' => 'XQ']); // no such ISO code

$model->country; // null

// Guard against null:
if ($model->country !== null) {
    echo $model->country->capital;
} else {
    echo 'Unknown country';
}
```

--------------------------------

### Handle method signature

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/build-command.md

The signature for the handle method in src/Commands/Build.php.

```php
/**
 * Execute the console command.
 *
 * @return int
 */
public function handle()
```

--------------------------------

### Language::countries() basic usage

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/language-model.md

Demonstrates retrieving countries associated with specific language codes.

```php
use Io238\ISOCountries\Models\Language;

// Countries that have Spanish ('es') as one of their official languages
Language::find('es')->countries->pluck('id');
// -> e.g. ["AR", "BO", "CL", "CO", "CR", "CU", "DO", "EC", "ES", "GQ", "GT",
//          "HN", "MX", "NI", "PA", "PE", "PR", "PY", "SV", "UY", "VE", ...]

// Countries that use German
Language::find('de')->countries->pluck('id'); // -> ["AT", "BE", "CH", "DE", "LI", "LU", "VA"]
```

--------------------------------

### set($model, $key, $value, $attributes)

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/language-cast.md

Prepares the given value for storage by lowercasing the ISO 639-1 code or extracting the ID from a Language model instance. Returns the lowercased string to persist.

```APIDOC
## set($model, $key, $value, $attributes)

### Description
Prepares the given value for storage by lowercasing the ISO 639-1 code or extracting the ID from a Language model instance. Returns the lowercased string to persist.

### Method
set

### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| $model | \Illuminate\Database\Eloquent\Model | yes | The parent Eloquent model being cast. |
| $key | string | yes | The attribute name on the parent model. |
| $value | string \| Io238\ISOCountries\Models\Language \| mixed | yes | The assigned value: ISO code string or Language model instance. |
| $attributes | array | yes | All raw attributes of the parent model. |

### Return type
string — the lowercased ISO 639-1 code to persist.

### Throws
None; however, object values that are neither strings nor Language instances are passed to strtolower() directly, which raises a PHP TypeError/ValueError at runtime — the source does not guard other types.

### Example — basic call (assigning a code)
```php
$model = MyModel::query()->first();
$model->update(['language' => 'DE']); // stored as "de"
```

### Example — assigning a model instance
```php
use Io238\ISOCountries\Models\Language as LanguageModel;

$model = MyModel::query()->first();
$model->update(['language' => LanguageModel::find('fr')]);

$model->getRawOriginal('language'); // "fr"
```
```

--------------------------------

### Private internal methods in Build.php

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/build-command.md

A list of private methods defined in src/Commands/Build.php that handle database operations and data loading.

```php
private function resetDatabase(): void          // src/Commands/Build.php, line 88
private function createTables(): void           // line 96
private function createPivotTables(): void      // line 145
private function loadCountries(): void          // line 173
private function loadCurrencies(): void         // line 224
private function loadLanguages(): void          // line 248
private function storeRelations(): void         // line 273
private function loadNameTranslations($model): void   // line 295
private function copyDatabaseFile(): void       // line 324
```

--------------------------------

### Retrieve Currency model

Source: https://github.com/io238/laravel-iso-countries/blob/main/README.md

Finds a currency record by its ISO code.

```php
Currency::find('COP');

Io238\ISOCountries\Models\Currency {
     id: "COP",
     name: "{\"en\":\"Colombian Peso\",\"de\":\"Kolumbianischer Peso\",\"fr\":\"peso colombien\",\"es\":\"peso colombiano\"}",
     name_plural: "Colombian pesos",
     symbol: "CO$",
     symbol_native: "$",
     decimal_digits: 0,
     rounding: 0,
   }
```

--------------------------------

### Cast ISO codes to models

Source: https://github.com/io238/laravel-iso-countries/blob/main/README.md

Shows how to use the provided casts to enrich model attributes with Currency metadata and update them using either ISO strings or model instances.

```php
use Io238\ISOCountries\Casts\Currency;

class MyModel{
    
    // ...

    protected $casts = [
        'currency' => Currency::class,
    ];
    
    // ...
}

// Now you can dynamically retrieve all meta data associated with the currency
MyModel::first()->currency;

Io238\ISOCountries\Models\Currency {
     id: "JPY",
     name: "{\"en\":\"Japanese Yen\",\"de\":\"Japanischer Yen\",\"fr\":\"yen japonais\",\"es\":\"yen\"}",
     name_plural: "Japanese yen",
     symbol: "¥",
     symbol_native: "￥",
     decimal_digits: 0,
     rounding: 0,
   }


// When filling the model, the ISO code (string) or the model can be used 
MyModel::first()->update(['currency' => 'USD']);
MyModel::first()->update(['currency' => Io238\ISOCountries\Models\Currency::find('USD')]);
```

--------------------------------

### Rebuild Database

Source: https://github.com/io238/laravel-iso-countries/blob/main/README.md

Execute this command to generate or update the SQLite database after modifying the configuration.

```bash
php artisan db:seed countries:build
```

--------------------------------

### Retrieve Language model

Source: https://github.com/io238/laravel-iso-countries/blob/main/README.md

Finds a language record by its ISO code.

```php
Country::find('pt');

Io238\ISOCountries\Models\Language {
     id: "pt",
     iso639_2: "por",
     iso639_2b: null,
     name: "{\"en\":\"Portuguese\",\"de\":\"Portugiesisch\",\"fr\":\"portugais\",\"es\":\"portugu\\u00e9s\"}",
     native_name: "Português",
     family: "Indo-European",
     wiki_url: "https://en.wikipedia.org/wiki/Portuguese_language",
   }
```

--------------------------------

### Command signature and description

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/build-command.md

Defines the artisan command signature and description within the Build command class.

```php
protected $signature = 'countries:build';

protected $description = 'Build Sqlite database with ISO country information in all configured translations.';
```

--------------------------------

### Define pivot table columns in src/Commands/Build.php

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/types.md

Defines the schema for country-related pivot tables, including country_language, country_currency, and country_country relationships.

```php
$table->string('country_id', 2)->index();   // country_language
$table->string('language_id', 2)->index();

$table->string('country_id', 2)->index();   // country_currency
$table->string('currency_id', 3)->index();

$table->string('country_id', 2)->index();   // country_country
$table->string('neighbour_id', 2)->index();
```

--------------------------------

### Retrieve languages for a country

Source: https://github.com/io238/laravel-iso-countries/blob/main/README.md

Demonstrates querying the languages relationship for a specific country using the Country model.

```php
// Retrieve languages that are spoken in Luxembourg
Country::find('LU')->languages;

Illuminate\Database\Eloquent\Collection {                                                                  
     all: [                                                                                                        
       Io238\ISOCountries\Models\Language {                                                                   
         id: "de",                                                                                                 
         iso639_2: "deu",                                                                                          
         iso639_2b: "ger",                                                                                         
         name: "{\"en\":\"German\",\"de\":\"Deutsch\",\"fr\":\"allemand\",\"es\":\"alem\u00e1n\"}",                                
         native_name: "Deutsch",                                                                                   
         family: "Indo-European",                                                                                  
         wiki_url: "https://en.wikipedia.org/wiki/German_language",                                                
       },                                                                                                          
       Io238\ISOCountries\Models\Language {                                                                   
         id: "fr",                                                                                                 
         iso639_2: "fra",                                                                                          
         iso639_2b: "fre",                                                                                         
         name: "{\"en\":\"French\",\"de\":\"Franz\u00f6sisch\",\"fr\":\"fran\u00e7ais\",\"es\":\"franc\u00e9s\"}",                 
         native_name: "français, langue française",                                                                
         family: "Indo-European",                                                                                  
         wiki_url: "https://en.wikipedia.org/wiki/French_language",                                                
       },                                                                                                          
       Io238\ISOCountries\Models\Language {                                                                   
         id: "lb",                                                                                                 
         iso639_2: "ltz",                                                                                          
         iso639_2b: null,                                                                                          
         name: "{\"en\":\"Luxembourgish\",\"de\":\"Luxemburgisch\",\"fr\":\"luxembourggeois\",\"es\":\"luxemburgu\u00e9s\"}",       
         native_name: "Lëtzebuergesch",                                                                            
         family: "Indo-European",                                                                                  
         wiki_url: "https://en.wikipedia.org/wiki/Luxembourgish_language",                                         
       },                                                                                                          
     ],                                                                                                            
   }
```

--------------------------------

### register()

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/isocountries-service-provider.md

Laravel service provider lifecycle hook that merges package configuration and registers the Build artisan command.

```APIDOC
## register()

### Description
Registers the package's configuration and artisan commands during the service provider registration phase.

### Method
register

### Signature
public function register()

### Parameters
None (Laravel lifecycle hook).

### Return Type
void (untyped in source).

### Throws
None.

### Behavior
- Merges package defaults from `config/iso-countries.php` under the `iso-countries` config key, overridden by any published config file.
- Registers the `Io238\ISOCountries\Commands\Build` artisan command.

### Example
```php
// config/iso-countries.php (published with --tag="config")
return [
    'locales' => ['en', 'de', 'fr', 'es'],
    'database_path' => database_path('iso-countries.sqlite'),
];

// After register(), the merged value is readable:
config('iso-countries.locales');       // ['en', 'de', 'fr', 'es'] (app value wins)
config('iso-countries.database_path'); // database_path('iso-countries.sqlite')
```
```

--------------------------------

### getPackageDatabaseFile() method signature

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/isocountries-service-provider.md

The getPackageDatabaseFile() static method returns the path to the package's database file.

```php
static public function getPackageDatabaseFile(): string
```

--------------------------------

### Console invocation

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/build-command.md

The command used to trigger the database build process from the terminal.

```bash
php artisan countries:build
```

--------------------------------

### Retrieve localized country names

Source: https://github.com/io238/laravel-iso-countries/blob/main/README.md

Demonstrates setting the application locale and retrieving country names based on that locale using the Country model.

```php
// Set the app locale
app()->setLocale('fr');

// Retrieve the top 10 countries in Africa (by population):
Io238\ISOCountries\Models\Country::where('region', 'Africa')->orderByDesc('population')->limit(10)->pluck('name');

// Country names will be returned according to the app locale (fr = French)
Illuminate\Support\Collection {
     all: [
       "Nigéria",
       "Éthiopie",
       "Égypte",
       "Congo-Kinshasa",
       "Afrique du Sud",
       "Tanzanie",
       "Kenya",
       "Algérie",
       "Soudan",
       "Ouganda",
     ],
   }
```

--------------------------------

### Language::countries() with join and attributes

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/language-model.md

Shows how to filter and order related countries using Eloquent query builder methods.

```php
use Io238\ISOCountries\Models\Language;

// European countries where Portuguese is official, ordered by population
Language::find('pt')->countries()
    ->where('region', 'Europe')
    ->orderByDesc('population')
    ->pluck('name');
// -> ["Portugal", ...]
```

--------------------------------

### Class declaration for Currency model

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/currency-model.md

The Currency model extends BaseModel and defines the relationship to the Country model.

```php
class Currency extends BaseModel {

    public function countries()
    {
        return $this->belongsToMany(Country::class);
    }
```

--------------------------------

### Assigning a currency code string

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/currency-cast.md

Assigning a string to the attribute will store it as an uppercase ISO code.

```php
$model = MyModel::query()->first();
$model->update(['currency' => 'usd']); // stored as "USD"
```

--------------------------------

### Retrieve Country model

Source: https://github.com/io238/laravel-iso-countries/blob/main/README.md

Finds a country record by its ISO code.

```php
Country::find('AD');

Io238\ISOCountries\Models\Country {
     id: "AD",
     alpha3: "AND",
     name: "{\"en\":\"Andorra\",\"de\":\"Andorra\",\"fr\":\"Andorre\",\"es\":\"Andorra\"}",
     native_name: "Andorra",
     capital: "Andorra la Vella",
     top_level_domain: ".ad",
     calling_code: "376",
     region: "Europe",
     subregion: "Southern Europe",
     population: 78014,
     lat: 42.5,
     lon: 1.5,
     demonym: "Andorran",
     area: 468,
   }
```

--------------------------------

### Constructor signature for MissingSqliteExtensionException

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/missing-sqlite-extension-exception.md

The inherited constructor signature for the exception class.

```php
public __construct(
    string $message = "The PHP extension pdo_sqlite is not installed or enabled. This package requires the SQLite extension.",
    int $code = 0,
    ?Throwable $previous = null
)
```

--------------------------------

### getPackageDatabaseFile()

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/isocountries-service-provider.md

Static method that returns the current value of the static $packageDatabaseFile property, which points to the packaged SQLite database file.

```APIDOC
## getPackageDatabaseFile()

### Description
Returns the path to the packaged ISO countries SQLite database file.

### Method
getPackageDatabaseFile

### Signature
static public function getPackageDatabaseFile(): string

### Parameters
None.

### Return Type
string - The current value of the static $packageDatabaseFile property.

### Example - Basic call
```php
use Io238\ISOCountries\ISOCountriesServiceProvider;

$file = ISOCountriesServiceProvider::getPackageDatabaseFile();
// e.g. '/app/vendor/io238/laravel-iso-countries/data/iso-countries.sqlite'
```

### Example - Pointing a raw PDO connection at the packaged database
```php
use Io238\ISOCountries\ISOCountriesServiceProvider;

$pdo = new PDO('sqlite:' . ISOCountriesServiceProvider::getPackageDatabaseFile());

$count = $pdo->query('SELECT COUNT(*) FROM countries')->fetchColumn();
// int(250)
```
```

--------------------------------

### Programmatic invocation

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/build-command.md

Invoke the command programmatically using the Artisan facade, useful for seeders or tests.

```php
use Illuminate\Support\Facades\Artisan;

$exitCode = Artisan::call('countries:build');
// $exitCode === 0 (self::SUCCESS)

// Output of the command (progress messages) is available via:
$output = Artisan::output();
```

--------------------------------

### Non-trivial usage of countries() with population sorting

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/currency-model.md

Combines the countries relationship with query builder methods to sort by population.

```php
use Io238\ISOCountries\Models\Currency;

// Euro countries sorted by population (descending)
Currency::find('EUR')->countries()
    ->orderByDesc('population')
    ->take(5)
    ->pluck('name');
// -> ["Germany", "France", "Italy", "Spain", "Netherlands"] (top 5)
```

--------------------------------

### Basic usage of Country cast

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/country-cast.md

Demonstrates accessing the resolved Country model and its properties from an Eloquent model instance.

```php
$model = MyModel::make(['country' => 'LU']);

$model->country;                   // Io238\ISOCountries\Models\Country instance
$model->country->alpha3;           // "LUX"
$model->country->name;             // localized name, e.g. "Luxembourg"
$model->country->languages;        // official languages relation works as usual
$model->country->currencies;       // ["EUR"]
```

--------------------------------

### Throwing MissingSqliteExtensionException

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/errors.md

This exception is thrown in the service provider's boot method when the pdo_sqlite extension is missing.

```php
// src/ISOCountriesServiceProvider.php, lines 19-22
if (!extension_loaded('pdo_sqlite')) {
    throw new MissingSqliteExtensionException();
}
```

--------------------------------

### countries() relationship method

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/currency-model.md

Defines the inverse many-to-many relationship to the Country model.

```php
public function countries()
{
    return $this->belongsToMany(Country::class);
}
```

--------------------------------

### Currency::find

Source: https://github.com/io238/laravel-iso-countries/blob/main/README.md

Retrieves a currency model by its ISO 4217 code. The returned object contains currency details such as localized names, plural name, symbols, decimal digits, and rounding.

```APIDOC
## Currency::find

### Description
Retrieves a currency model by its ISO 4217 code. The returned object contains currency details such as localized names, plural name, symbols, decimal digits, and rounding.

### Method
find

### Parameters
- **id** (string) - Required - The ISO 4217 currency code (e.g., 'COP' for Colombian Peso).

### Request Example
Currency::find('COP');

### Response
#### Success Response
- **id** (string) - The ISO 4217 currency code.
- **name** (object) - Localized names in multiple languages (en, de, fr, es).
- **name_plural** (string) - The plural name of the currency.
- **symbol** (string) - The currency symbol.
- **symbol_native** (string) - The native currency symbol.
- **decimal_digits** (integer) - The number of decimal digits.
- **rounding** (integer) - The rounding value.

#### Response Example
{
  "id": "COP",
  "name": "{\"en\":\"Colombian Peso\",\"de\":\"Kolumbianischer Peso\",\"fr\":\"peso colombien\",\"es\":\"peso colombiano\"}",
  "name_plural": "Colombian pesos",
  "symbol": "CO$",
  "symbol_native": "$",
  "decimal_digits": 0,
  "rounding": 0
}
```

--------------------------------

### Slug derived from current locale

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/base-model.md

Demonstrates how the slug changes based on the application's current locale.

```php
app()->setLocale('fr');
Country::find('ET')->slug; // "ethiopie"  (French name: "Éthiopie")

app()->setLocale('de');
Country::find('ET')->slug; // "athiopien" (German name: "Äthiopien")
```

--------------------------------

### Locale file lookup logic in loadNameTranslations

Source: https://github.com/io238/laravel-iso-countries/blob/main/_autodocs/api-reference/build-command.md

Logic used to determine the translation file path based on the provided model class-string.

```php
$file = match ($model) {
    Country::class  => __DIR__ . "/../../data/translations/countries/$locale/country.php",
    Language::class => __DIR__ . "/../../data/translations/languages/$locale/language.php",
    Currency::class => __DIR__ . "/../../data/translations/currencies/$locale/currency.php",
};

if ( ! file_exists($file)) {
    continue;
}
```
Tokens:
Raw