Flagiconcss Bundle Laravel Package

Getting Started

This package is a Symfony2 bundle, not a Laravel package — there is no FlagIconCssServiceProvider, no composer.json autoload mapping into App\, and no facade. A Laravel developer should treat it as reference material, not a dependency: the thing you actually want is lipis/flag-icon-css (the underlying CSS/SVG set the bundle wraps).

If you are on Laravel, do this instead:

npm install flag-icons        # actively maintained successor to flag-icon-css
# or, for the exact original asset set:
npm install flag-icon-css

/* resources/css/app.css */
@import 'flag-icons/css/flag-icons.min.css';

Then render in Blade:

<span class="fi fi-us"></span>

If you genuinely inherited a Symfony2 project, the bundle's first steps are: composer require st/flagiconcss-bundle, register new ST\FlagIconCssBundle\STFlagIconCssBundle() in app/AppKernel.php, run php app/console assets:install --symlink and assetic:dump, then use the Twig helper the extension registers. Where to look first: vendor/st/flagiconcss-bundle/Resources/ (the bundled assets and any templates) and the Twig extension class under Twig/ — that single class tells you the exact helper name, its arguments, and the markup it emits. Copy that markup into your Blade component rather than trying to bridge the bundle.

First use case: a user profile or address showing a country flag next to a stored country_code column.

Implementation Patterns

Blade component (the idiomatic Laravel replacement):

{{-- resources/views/components/flag.blade.php --}}
@props(['code', 'squared' => false, 'size' => null])
<span
    class="fi fi-{{ strtolower($code) }}{{ $squared ? ' fis' : '' }}{{ $size ? ' fi-'.$size : '' }}"
    role="img"
    aria-label="{{ $label ?? strtoupper($code) }}"
></span>

<x-flag code="{{ $user->country_code }}" squared />

Mapping the Symfony config surface. The bundle's DependencyInjection/Configuration.php exposes any default prefix/class options. Reproduce that as a single config file so it stays tweakable:

// config/flags.php
return ['class_prefix' => 'fi', 'default_size' => null];

Country code normalization. Store ISO 3166-1 alpha-2 lowercase in the database and normalize once, at the model boundary, not in every view:

protected function countryCode(): Attribute
{
    return Attribute::get(fn ($v) => strtolower($v ?? 'xx'));
}

List rendering / selection inputs. For country pickers, iterate a code→name array and render <x-flag> inline with the option label. This is the highest-value pattern — flags make long country lists scannable.

Sizes and variants. flag-icon-css ships .flag-icon-squared and 2x/3x/4x classes; flag-icons uses .fis and fi-2x. Keep these in a component prop map rather than scattering class strings through views.

Locale-driven display. Derive the flag from App::getLocale() for a header language switcher — en → gb needs an explicit mapping table (see gotchas).

Gotchas and Tips

• The bundle will not run in Laravel. Symfony bundles rely on the Kernel, DI container compilation, and Resources/config/services.yml. No auto-discovery, no Artisan commands. Don't add it to composer.json.
• The package is effectively abandoned — zero stars, zero dependents, targeting Symfony2 (EOL since 2018). Treat any code you copy as a one-time reference.
• flag-icon-css itself is deprecated. The maintained successor is lipis/flag-icons, which renamed classes from flag-icon flag-icon-us to fi fi-us. Pick one and be consistent; don't mix class sets.
• uk is not a country code. Use gb for the United Kingdom, eu for the EU, un for the UN, xx for unknown. Maintain an explicit alias map for locale codes: en→gb, ja→jp, zh→cn, pt-BR→br.
• Accessibility. A bare <span class="fi fi-us"> is invisible to screen readers and meaningless to anyone who can't see the flag. Always add role="img" plus aria-label or adjacent text. Purely decorative flags next to a country name should be aria-hidden="true" instead.
• Bundle size. The full CSS set pulls one SVG per country (~250 files, several hundred KB). If you only ship a handful of markets, import the individual SVGs or generate a subset CSS rather than the whole package.
• Asset pipeline mismatch. Tutorials for the Symfony bundle reference assets:install and assetic:dump. In Laravel those mean nothing — your equivalent is Vite: import the CSS in resources/css/app.css and let npm run build handle hashing and public/build output.
• 404s in a legacy Symfony install almost always mean assets were never installed to web/bundles/stflagiconcss/; re-run assets:install --symlink and clear the cache.
• Helper not rendering in legacy Symfony usually means the bundle wasn't registered in AppKernel.php or the Twig extension service isn't tagged twig.extension. Use debug:container --tag=twig.extension to confirm.
• Extension points are limited. The Symfony bundle's only real knob is the Twig helper's class arguments; there's no event system worth hooking. In Laravel, the equivalent extension point is the Blade component's $attributes bag — let callers pass class, id, and data attributes through.