Filament Country Select Laravel Package

Getting Started

• Install with composer require tanthammar/filament-country-select, then confirm the service provider is auto-discovered (no manual registration needed on Laravel 10/11+ with package discovery enabled).
• Look first at the published config (php artisan vendor:publish --tag="filament-country-select-config") and at the field class itself — the field extends Filament's Select, so anything you know about Select (searchability, ->native(), ->preload(), validation) applies here too.
• Store countries as ISO 3166-1 alpha-2 codes in a string(2) column. This is the least surprising choice and keeps you compatible with laravel/framework's country validation rule, Stripe, and most address APIs.
• First use case — an address form:

use Tanthammar\CountrySelect\...\CountrySelect; // check the namespace in the package README

CountrySelect::make('country')
    ->searchable()
    ->required()
    ->default('NL');

Then render it back in a table column with the flag + translated name rather than the raw code.

Implementation Patterns

• Form field + table column pair. Keep the raw ISO code as the source of truth in the DB and derive the display name at render time. A small accessor ($user->country_name) or a helper keeps the rest of the app free of package imports, which makes swapping the package later trivial.
• Two-letter vs three-letter. The package exposes both alpha-2 and alpha-3 style codes. Pick one at the schema level and never mix — the most common bug in address forms is a column that holds alpha-2 for old rows and alpha-3 for new ones.
• Limiting the option list. For checkout/shipping forms, constrain to countries you actually ship to (either via the field's ->options()/allowed-countries method or a ->in() validation rule backed by the same config array). Define that list once in config/ and reuse it in the validation rule so the UI and the rule can't drift.
• Validation. Pair the field with ['required', 'string', 'size:2', Rule::in(array_keys($allowed))]. Don't rely on the field's ->required() alone — Livewire payloads are user-controlled.
• Phone + country combos. Wire the country field to a phone input via ->live() + ->afterStateUpdated() if you want to auto-set the dial code, but keep the phone number stored in E.164. Recomputing the dial code on every hydration is a common source of flicker in Filament forms.
• Localised labels. Set the app locale and let the package resolve translated country names. For multi-locale admin panels, the field label itself should come from __('...') in your own lang files, not from the package.
• Testing. Assert against the stored code, not the label: assertFormSet(['country' => 'TR']). Label-based assertions break the moment translations change (as 1.1.2 demonstrates).

Gotchas and Tips

• The Turkish İ problem (fixed in 1.1.2). PHP's mb_strtolower('İ') returns "i̇" (an i plus a combining dot above), not a plain i. Any search/normalisation that lowercases country names will fail to match Türkiye, İran, İrlanda, İzlanda, etc. 1.1.2 ships Turkish aliases so those names still resolve. If you maintain your own country list or your own search normaliser, mirror this: strip combining marks after lowercasing, or use a transliteration table — never assume strtolower/mb_strtolower round-trips.
• Don't rely on strtolower() anywhere in the address stack. On a Turkish-locale server, strtolower('I') yields ı. If you validate or key options by lowercased codes, you will get intermittent, locale-dependent failures that never reproduce on your dev machine. Always uppercase ISO codes explicitly.
• Caching after upgrading. Filament caches form/table components and the config is merged at boot. After composer update, run php artisan filament:cache-components (if you use component caching) and php artisan config:clear — stale cached components are the most common "the package update did nothing" report.
• Flag rendering. Emoji flags (🇳🇱) render inconsistently across Windows and some Linux desktop environments. If flags are a core part of your UI, prefer the package's SVG/icon option or a dedicated icon set; test on Windows before shipping.
• Native selects on mobile. ->native() gives better mobile UX but disables the searchable dropdown; with 250 options, a non-native searchable select is the better default on desktop, and the reverse on mobile.
• Extension points. The field is a Filament component, so you can subclass it to add project defaults (->searchable()->preload() applied once) rather than repeating them in every form. If you need different labels, prefer a custom field class over monkey-patching the package's translation files — package-level lang files are overwritten on update.
• Patch-level upgrade. 1.1.2 is a translation/alias fix with no API or schema changes; it is safe to bump in a minor release train. There is nothing to migrate, but do add a regression test asserting that searching for a Turkish country name by its Turkish spelling still returns the right code, so a future data change doesn't silently break it.