Eloquent Models

The Country Model

Laravel Countries provides a full Eloquent model with all the benefits of Laravel's ORM:

use Webpatser\Countries\Models\Country;
 
// Find a country by code
$usa = Country::findByCode('US');
echo $usa->name;     // "United States"
echo $usa->flag;     // "🇺🇸"
 
// Get all countries
$allCountries = Country::all();
 
// Use standard Eloquent methods
$country = Country::where('iso_3166_2', 'DE')->first();

Model Attributes

The Country model has the following attributes:

Query Scopes

The Country model includes useful query scopes for filtering:

By Region

// Get all European countries
$europeanCountries = Country::byRegion('Europe')->get();
 
// Get all Asian countries
$asianCountries = Country::byRegion('Asia')->get();

By Currency

// Get all countries using Euro
$euroCountries = Country::byCurrency('EUR')->get();
 
// Get all countries using US Dollar
$usdCountries = Country::byCurrency('USD')->get();

Search Countries

// Search by name or capital
$results = Country::search('united')->get();
 
// Chain with other scopes
$europeanUnited = Country::byRegion('Europe')
    ->search('united')
    ->get();

Accessors & Mutators

The model provides convenient accessors for common operations:

$country = Country::findByCode('US');
 
// Formatted display
echo $country->formatted;  // "🇺🇸 United States"
 
// Currency information as array
$currency = $country->currency;
// ['code' => 'USD', 'name' => 'US Dollar', 'symbol' => '$']
 
// Check if country has specific language
$hasEnglish = $country->hasLanguage('English'); // true
 
// Get primary language
echo $country->primary_language; // "English"

HasCountry Trait

Add country relationships to your models with the HasCountry trait:

use Webpatser\Countries\Traits\HasCountry;
 
class User extends Model
{
    use HasCountry;
 
    protected $fillable = [
        'name',
        'email',
        'country_code' // Add this field to your migration
    ];
}
 
// Usage
$user = User::create([
    'name' => 'John Doe',
    'email' => '[email protected]',
    'country_code' => 'US'
]);
 
// Access country information
echo $user->country->name;           // "United States"
echo $user->country->flag;           // "🇺🇸"
echo $user->country_name;            // "United States" (accessor)
echo $user->formatted_country;       // "🇺🇸 United States"
 
// Query users by country
$americanUsers = User::whereCountry('US')->get();
$europeanUsers = User::whereCountryRegion('Europe')->get();

Model Casts

The Country model includes automatic casting for complex data types:

// Languages are automatically cast to array
$country = Country::findByCode('CH');
$languages = $country->languages; // Returns array, not JSON string
 
// You can use the cast in your own models
use Webpatser\Countries\Casts\CountryLanguages;
 
class Location extends Model
{
    protected $casts = [
        'supported_languages' => CountryLanguages::class,
    ];
}

Model Relationships

Easily create relationships with the Country model:

// User model with country relationship
class User extends Model
{
    public function country()
    {
        return $this->belongsTo(Country::class, 'country_code', 'iso_3166_2');
    }
}
 
// Order model with country relationship
class Order extends Model
{
    public function country()
    {
        return $this->belongsTo(Country::class, 'country_code', 'iso_3166_2');
    }
}
 
// Eager loading relationships
$users = User::with('country')->get();
$orders = Order::with('country')->get();
 
// Group users by region
$usersByRegion = User::with('country')
    ->get()
    ->groupBy('country.region');

Performance Optimization

// Good: Eager load relationships
$users = User::with('country')->get();
 
// Bad: This will cause N+1 queries
$users = User::all();
foreach ($users as $user) {
    echo $user->country->name; // Separate query for each user
}
 
// Use select to limit fields
$countries = Country::select('iso_3166_2', 'name', 'flag')->get();
 
// Cache frequently accessed data
$popularCountries = Cache::remember('popular_countries', 3600, function () {
    return Country::whereIn('iso_3166_2', ['US', 'GB', 'DE', 'FR'])->get();
});