Filament Iban Input Laravel Package

Getting Started

This release is about the IBAN form field itself, so start where the field is rendered rather than in the service layer.

1. Update and smoke-test the field.

   composer update <vendor>/<package>
   php artisan vendor:publish --tag=<package>-assets   # if you use compiled assets
   

   Load any form that already uses the IBAN field and confirm the country selector, formatting and validation messages still appear as before. The UI was reworked in 4.1.0, so eyeballing one real form is faster than reading the diff.

2. Find your existing usages first. Grep for the field class before changing anything:

   grep -rn "Iban\|IBAN" app/Filament app/Http/Livewire resources/views
   

   Note which of them set an explicit country, a default value, or custom validation — those are the ones most likely to shift behaviour.

3. First use case: a single IBAN field on a payout/beneficiary form. Add the field to your schema, keep a iban column (store normalized, see Gotchas), and let the package handle formatting and country selection in the UI while your FormRequest does the authoritative validation.

Implementation Patterns

Let the field own presentation, keep validation server-side. The field's improved validation feedback is a UX layer. Pair it with a request rule so the same data is checked on submit:

$request->validate([
    'iban' => ['required', 'string', 'iban'], // or the package's rule, if it ships one
]);

Normalize at the boundary. The formatted value shown in the input contains spaces; persist a canonical form and format only for display:

protected function prepareForValidation(): void
{
    $this->merge([
        'iban' => strtoupper(preg_replace('/\s+/', '', (string) $this->iban)),
    ]);
}

Use the country-length metadata for hints, not authority. The new country-specific length metadata is useful for placeholder text, max-length attributes and "an IBAN for Germany is 22 characters" style help. Keep the actual accept/reject decision in one place — the validator — so UI metadata and stored data can't drift.

Multi-country forms. If your form already has a country/currency selector, set the IBAN field's country from it so the two don't disagree, and re-render the field when the country changes. For single-country products, hard-set the country and let the selector be hidden rather than relying on auto-detection from the typed prefix.

RTL admin panels. 4.1.0 forces LTR on the input value. That's the right default for IBANs even in Arabic/Hebrew locales — don't override it with a theme-level direction: rtl, or the grouping of characters will read wrongly. Keep RTL for labels and surrounding layout, LTR for the value.

Test data. Build a small fixture set of valid IBANs across several countries (and a couple of near-misses: wrong length, wrong check digits, lowercase input, spaces) and reuse it in feature tests for both the field and the request rule.

Gotchas and Tips

• Formatted vs stored values. The most common bug after this kind of UI change is a unique/exists rule comparing DE89 3704 0044 0532 0130 00 against a DB column holding DE89370400440532013000. Normalize before every comparison, not just before save.
• Country selection behaviour may have changed. With explicit country selection and per-country lengths, auto-detection from the typed prefix is no longer the only path. If a form pre-fills an IBAN from the database, verify the selected country matches the value's actual country on first render.
• Length metadata is not the whole rule. Some countries have more than one valid IBAN length, and length alone says nothing about check digits. Treat metadata as a hint and always validate the checksum.
• RTL enforcement is inline/CSS-level. If you have custom field styling or a published theme, check that your overrides don't reintroduce direction or text-align on the input.
• Browser/Dusk tests are the fragile part. DOM and class changes from the UI rework break selectors. Re-run your browser suite specifically against the IBAN field before shipping.
• Upgrade is minor (4.1.0), so expect no schema changes — but treat the visual/validation changes as behaviour changes for snapshot tests and any JS that reads the input value.
• Debugging tip: when validation "fails silently," log the normalized value you submit, not the raw request input; the discrepancy is usually whitespace or case introduced by the formatter.
• Extension point: if the country list or length data lives in a publishable config/array, publish it and override rather than patching vendor files — that's the piece most likely to need local additions.