Helper Functions

Available Helper Functions

Laravel Countries provides a comprehensive set of global helper functions that make working with country data simple and intuitive:

Basic Information Functions

country_name($code)

Get the official name of a country:

echo country_name('US');    // "United States"
echo country_name('DE');    // "Federal Republic of Germany"
echo country_name('JP');    // "Japan"
echo country_name('XYZ');   // null (invalid code)

country_flag($code)

Get the flag emoji for a country:

echo country_flag('US');    // "🇺🇸"
echo country_flag('DE');    // "🇩🇪"
echo country_flag('JP');    // "🇯🇵"
echo country_flag('XYZ');   // null

country_capital($code)

Get the capital city of a country:

echo country_capital('US');    // "Washington D.C."
echo country_capital('DE');    // "Berlin"
echo country_capital('JP');    // "Tokyo"

country_formatted($code)

Get a formatted string with flag and name:

echo country_formatted('US');   // "🇺🇸 United States"
echo country_formatted('DE');   // "🇩🇪 Federal Republic of Germany"
echo country_formatted('JP');   // "🇯🇵 Japan"

Currency Functions

country_currency($code)

Get complete currency information as an array:

$currency = country_currency('US');
// Returns:
[
    'code' => 'USD',
    'name' => 'US Dollar',
    'symbol' => '$'
]
 
$euroCurrency = country_currency('DE');
// Returns:
[
    'code' => 'EUR',
    'name' => 'Euro',
    'symbol' => '€'
]

Usage in Templates

// In Blade templates
@php $currency = country_currency($user->country_code) @endphp
 
<span>{{ $currency['symbol'] }}{{ $price }}</span>
<small>{{ $currency['name'] }}</small>

Utility Functions

country_exists($code)

Check if a country code is valid:

if (country_exists('US')) {
    echo "Valid country code";
}
 
if (!country_exists('XYZ')) {
    echo "Invalid country code";
}
 
// Useful for validation
$isValid = country_exists($request->country_code);

country_region($code)

Get the geographical region of a country:

echo country_region('US');    // "Americas"
echo country_region('DE');    // "Europe"
echo country_region('JP');    // "Asia"

country_languages($code)

Get an array of languages spoken in a country:

$languages = country_languages('US');
// Returns: ['English']
 
$languages = country_languages('CH');
// Returns: ['German', 'French', 'Italian']

Advanced Functions

countries_select_options($region, $withFlags)

Generate select options for forms:

// All countries
$options = countries_select_options();
 
// European countries only
$europeanOptions = countries_select_options('Europe');
 
// With flag emojis
$flagOptions = countries_select_options('Europe', true);
 
// Usage in Blade
<select name="country">
    @foreach(countries_select_options('Europe', true) as $code => $display)
        <option value="{{ $code }}">{{ $display }}</option>
    @endforeach
</select>

countries_by_region($region)

Get all countries in a specific region:

$europeanCountries = countries_by_region('Europe');
$asianCountries = countries_by_region('Asia');
 
// Returns array with country codes as keys

countries_by_currency($currency)

Get all countries using a specific currency:

$euroCountries = countries_by_currency('EUR');
$dollarCountries = countries_by_currency('USD');

Flag Conversion Functions

country_code_to_flag($code)

Convert country code to flag emoji:

echo country_code_to_flag('US');    // "🇺🇸"
echo country_code_to_flag('DE');    // "🇩🇪"
 
// Same as country_flag() but more explicit

flag_to_country_code($flag)

Convert flag emoji back to country code:

echo flag_to_country_code('🇺🇸');    // "US"
echo flag_to_country_code('🇩🇪');    // "DE"
echo flag_to_country_code('🇯🇵');    // "JP"

Real-world Examples

User Profile Display

// In a Blade template
<div class="user-profile">
    <h3>{{ $user->name }}</h3>
    <p>
        <strong>Location:</strong>
        {{ country_formatted($user->country_code) }}
    </p>
    <p>
        <strong>Capital:</strong>
        {{ country_capital($user->country_code) }}
    </p>
</div>

E-commerce Price Display

// Controller
public function showProduct($id, Request $request)
{
    $product = Product::find($id);
    $userCountry = $request->header('CF-IPCountry', 'US');
    $currency = country_currency($userCountry);
 
    return view('product', compact('product', 'currency'));
}
 
// Blade template
<div class="price">
    {{ $currency['symbol'] }}{{ $product->price }}
    <small>{{ $currency['code'] }}</small>
</div>

API Response Formatting

// API Controller
public function getUserProfile($id)
{
    $user = User::find($id);
 
    return response()->json([
        'user' => [
            'name' => $user->name,
            'email' => $user->email,
            'country' => [
                'code' => $user->country_code,
                'name' => country_name($user->country_code),
                'flag' => country_flag($user->country_code),
                'region' => country_region($user->country_code),
            ]
        ]
    ]);
}

Form Validation with Helpers

// Custom validation rule
public function rules()
{
    return [
        'country_code' => [
            'required',
            function ($attribute, $value, $fail) {
                if (!country_exists($value)) {
                    $fail('The selected country is invalid.');
                }
            }
        ]
    ];
}
 
// Or in a custom validator
Validator::extend('valid_country', function ($attribute, $value, $parameters) {
    return country_exists($value);
});

Performance Considerations

Caching Helper Results

For high-traffic applications, consider caching helper results:

use Illuminate\Support\Facades\Cache;
 
// Cache country data for a user
$countryData = Cache::remember("country_data_{$user->country_code}", 3600, function () use ($user) {
    return [
        'name' => country_name($user->country_code),
        'flag' => country_flag($user->country_code),
        'currency' => country_currency($user->country_code),
    ];
});