Country Flags Laravel Package

Getting Started

Install with Composer:

composer require stidges/country-flags

The package is Laravel-auto-discovered on 5.5+, so no manual service-provider registration is usually needed. On older apps, add the provider/facade alias from the package README to config/app.php.

Look first at:

1. The package’s service provider — this tells you the container binding and whether a Blade directive/helper is registered.
2. The main class (typically Stidges\CountryFlags\CountryFlag) — it exposes the conversion method, usually get().
3. Any published config file — it may contain the country-code-to-emoji mapping or an override table.

First use case: render a flag next to a user’s country.

use Stidges\CountryFlags\CountryFlag;

CountryFlag::get('US'); // 🇺🇸
CountryFlag::get('be'); // 🇧🇪 (verify case handling in your version)

In a Blade view:

{{ CountryFlag::get($user->country_code) }} {{ $user->name }}

If the package registers a helper, the same result is often available as country_flag('US'). Check the README/provider before relying on it — helper registration varies by release.

Implementation Patterns

Model accessor — keep flag rendering out of views:

public function getFlagAttribute(): string
{
    return CountryFlag::get($this->country_code) ?? '';
}

Then {{ $user->flag }} in Blade. Add $appends = ['flag'] only if you actually need it in JSON.

API resources — return the emoji as a separate field rather than embedding it in a name:

return [
    'country_code' => $this->country_code,
    'flag' => CountryFlag::get($this->country_code),
];

Blade component for consistent markup and accessibility:

{{-- resources/views/components/flag.blade.php --}}
@props(['code'])
<span role="img" aria-label="{{ strtoupper($code) }} flag">
    {{ CountryFlag::get($code) }}
</span>

Usage: <x-flag code="{{ $user->country_code }}" />.

Fallback chain — country codes are often nullable or dirty:

$flag = CountryFlag::get($code)
    ?? CountryFlag::get(strtoupper($code))
    ?? '🏳️';

Form validation — pair the package with a validation rule so invalid codes don’t silently produce null:

'country_code' => ['required', 'string', 'size:2', 'alpha'],

Select lists — combine with a country-name package (or your own mapping) for <option> labels, and use this package only for the emoji preview.

Caching — if you render large lists, resolve flags once and cache the resulting HTML/array; the conversion itself is cheap, but per-row facade calls across thousands of rows add up.

Emails and notifications — flags render fine in HTML mail if the client supports emoji fonts; always include the country name as text for clients that don’t.

Gotchas and Tips

• Alpha-2 only. This package maps ISO 3166-1 alpha-2 codes (US, GB). USA or United States will not work. Normalize codes at the boundary (form request, importer) rather than scattering strtoupper() calls.
• Unknown codes may return null or the input unchanged, depending on version. Test the exact behavior for your release and always provide a fallback; don’t assume a string is returned.
• Case sensitivity. Some versions expect uppercase. Normalize with strtoupper() before calling, or wrap the call in a small helper you control.
• Emoji are not images. Rendering depends on the OS/browser emoji font. Windows, older Linux servers, headless Chromium, and PDF generators may show tofu boxes or monochrome glyphs. If you generate PDFs or screenshots, use SVG flag assets instead, or verify your font stack includes an emoji font.
• Terminal and log output may render flags unpredictably; avoid using them as the sole identifier in CLI output.
• Accessibility. A bare emoji communicates little to screen readers. Wrap in a <span> with role="img" and an aria-label containing the country name.
• Don’t store the emoji in the database. Store the country code; flags are presentation. Storing emoji bakes in font/encoding assumptions and makes migrations painful.
• Config caching. If you publish and edit a config file, run php artisan config:clear during development — a cached config will ignore your changes.
• Package age. Last release was January 2021; it targets older Laravel/PHP versions. On PHP 8.1+ or Laravel 10/11, check for deprecation warnings and confirm the service provider still boots. If it doesn’t, the underlying logic (regional indicator symbol conversion) is a few lines and easy to vendor into your app.
• Testing. Emoji in test assertions can be fragile across encodings. Prefer asserting the country_code field, or assert against "\u{1F1FA}\u{1F1F8}"-style Unicode escapes rather than pasting the literal flag into the test file.
• Extension point. If the package exposes a mapping array (config or a setFlags()-style method), override entries there for non-standard codes (e.g. XK for Kosovo) instead of forking. Verify the key format matches what get() expects.
• Alternatives. For new projects, consider a maintained package or a two-line local helper that maps alpha-2 codes to regional indicator symbols. This package is small enough that the maintenance risk often outweighs the convenience.