Quick Start Guide

Basic Usage

The Countries class is the main entry point for accessing country data:

use Webpatser\Countries\Countries;
 
$countries = new Countries();
 
// Get a single country
$usa = $countries->getOne('US');
echo $usa['name'];     // "United States"
echo $usa['flag'];     // "🇺🇸"
echo $usa['capital'];  // "Washington D.C."
 
// Get all countries
$allCountries = $countries->getList();
echo count($allCountries); // 249

Filtering and Searching

Filter by Currency

// Get all countries using Euro
$euroCountries = $countries->getByCurrency('EUR');
 
foreach ($euroCountries as $code => $country) {
    echo $country['flag'] . ' ' . $country['name'] . PHP_EOL;
}
// 🇦🇩 Principality of Andorra
// 🇦🇹 Republic of Austria
// 🇧🇪 Kingdom of Belgium
// ...

Filter by Region

// Get all European countries
$europeanCountries = $countries->getByRegion('Europe');
 
// Get all Asian countries
$asianCountries = $countries->getByRegion('Asia');

Search Countries

// Search by name or capital
$searchResults = $countries->search('united');
 
// Results include:
// - United States
// - United Kingdom
// - United Arab Emirates

Helper Functions

Laravel Countries provides convenient global helper functions:

// Get country information
country_name('US');           // "United States"
country_flag('US');           // "🇺🇸"
country_capital('US');        // "Washington D.C."
country_formatted('US');      // "🇺🇸 United States"
 
// Get currency information
$currency = country_currency('US');
// ['code' => 'USD', 'name' => 'US Dollar', 'symbol' => '$']
 
// Check if country exists
country_exists('US');         // true
country_exists('ZZ');         // false
 
// Convert between formats
country_code_to_flag('DE');   // "🇩🇪"
flag_to_country_code('🇯🇵');  // "JP"

Collection Macros

Extend Laravel Collections with country-specific methods:

use Webpatser\Countries\Countries;
 
$countries = collect((new Countries())->getList());
 
// Filter by region
$europeanCountries = $countries->byRegion('Europe');
 
// Filter by currency
$euroCountries = $countries->byCurrency('EUR');
 
// Search countries
$searchResults = $countries->searchCountries('united');
 
// Get just country names
$countryNames = $countries->countryNames();
 
// Get just flags
$flags = $countries->countryFlags();
 
// Chain multiple operations
$result = $countries
    ->byRegion('Europe')
    ->byCurrency('EUR')
    ->countryNames()
    ->sort();

String Macros

Extend Laravel's Str class with country utilities:

use Illuminate\Support\Str;
 
// Convert country codes to flags
Str::toCountryFlag('US');       // "🇺🇸"
Str::toCountryFlag('DE');       // "🇩🇪"
 
// Convert flags back to codes
Str::fromCountryFlag('🇺🇸');    // "US"
Str::fromCountryFlag('🇩🇪');    // "DE"
 
// Get country names
Str::countryName('FR');         // "French Republic"
Str::countryName('JP');         // "Japan"

Form Validation

Use built-in validation rules for forms:

use Webpatser\Countries\Rules\ValidCountryCode;
use Webpatser\Countries\Rules\ValidCurrencyCode;
use Webpatser\Countries\Rules\ValidRegion;
 
// In your form request or controller
$request->validate([
    'country' => ['required', new ValidCountryCode('iso_3166_2')],
    'currency' => ['nullable', new ValidCurrencyCode()],
    'region' => ['nullable', new ValidRegion()],
]);

Common Use Cases

Country Dropdown for Forms

// Get select options for forms
$countryOptions = countries_select_options();
 
// With flags
$countryOptions = countries_select_options(null, true);
 
// Only European countries
$europeanOptions = countries_select_options('Europe');

User Profile with Country

use Webpatser\Countries\Traits\HasCountry;
 
class User extends Model
{
    use HasCountry;
 
    // country_code field in database
}
 
// Now you can use:
$user->country->name;           // Country name
$user->country_name;            // Via accessor
$user->formatted_country;       // "🇺🇸 United States"
$user->isFromEurope();         // Boolean check

Analytics by Region

// Get users grouped by region
$usersByRegion = User::all()
    ->groupBy(fn($user) => country_region($user->country_code))
    ->map->count();
 
// Get revenue by currency
$revenueByCurrency = Order::all()
    ->groupBy(fn($order) => country_currency($order->country)['code'])
    ->map(fn($orders) => $orders->sum('total'));

Performance Tips

Caching

Enable caching for JSON source or frequent lookups:

// In config/countries.php
'cache_ttl' => 3600, // Cache for 1 hour

Eloquent Optimization

// Eager load countries for multiple users
$users = User::with('country')->get();
 
// Use specific selects to reduce memory
$countries = Country::select('iso_3166_2', 'name', 'flag')->get();