Iban Laravel Package

Getting Started

Install with Composer; the package has no Laravel auto-discovery and no service provider, so nothing needs registering:

composer require jschaedl/iban

Look first at the single entry point, Jschaedl\Iban\IBAN. Everything is a plain value object built from a string:

use Jschaedl\Iban\IBAN;

$iban = new IBAN('DE89370400440532013000');

$iban->isValid();            // bool — format + mod-97 checksum
$iban->getCountryCode();     // "DE"
$iban->getBBAN();            // "370400440532013000"
$iban->getBankIdentifier();  // "37040044"
$iban->getAccountNumber();   // "0532013000"
$iban->toFormat();           // "DE89 3704 0044 0532 0130 00"

Your first real use case in a Laravel app is validating a user-submitted payout/refund IBAN in a form request, then storing a normalized copy: strip spaces, uppercase, persist the compact form, display the formatted form. Treat the library as a pure validator/parser — it tells you whether the string is structurally a valid IBAN, never whether the account exists.

Implementation Patterns

Custom validation rule. Wrap IBAN in an Illuminate\Contracts\Validation\Rule so it slots into FormRequests and inline Validator::make calls identically:

class ValidIban implements Rule
{
    public function passes($attribute, $value): bool
    {
        $normalized = strtoupper(str_replace(' ', '', (string) $value));
        try {
            return (new IBAN($normalized))->isValid();
        } catch (\Throwable) {
            return false;
        }
    }

    public function message(): string
    {
        return 'The :attribute is not a valid IBAN.';
    }
}

Normalize at the boundary. Always normalize before constructing: users paste IBANs with spaces, lowercase, and non-breaking spaces. Do this once in a FormRequest prepareForValidation() or in a value-object named constructor, not scattered through controllers.

Value object + Eloquent accessor. Keep the compact IBAN in the database column and expose formatting via an accessor:

protected function ibanFormatted(): Attribute
{
    return Attribute::get(fn () => (new IBAN($this->iban))->toFormat());
}

Pre-payment gate. In a SEPA/payout flow, run validation immediately before dispatching to your payment provider, not only at signup — IBANs get edited. Pair this with provider-side verification (name/account match); format validity is a cheap pre-check, not a substitute.

No facade/singleton needed. The class is stateless and cheap to instantiate; binding it in a service provider adds ceremony without benefit. If you want a single seam for swapping libraries later, introduce a thin IbanService interface in your domain and inject the package behind it — this makes the eventual deprecation migration a one-file change.

Test data. Use a fixed table of known-valid IBANs across your supported countries in factories/seeders rather than generating at runtime; deterministic fixtures catch checksum regressions and keep tests readable.

Gotchas and Tips

• This package is deprecated and last released in 2017. There will be no fixes for new country formats added since then, and PHP 8.x compatibility is not guaranteed (expect possible deprecation notices or dynamic-property warnings). For new code prefer symfony/validator's Iban constraint (already available if you use Laravel's validator stack) or globalcitizen/php-iban; keep this assessment's integration patterns but swap the implementation.
• isValid() vs. the constructor. Depending on input, the constructor may throw for structurally unparseable strings while isValid() returns false for bad checksums. Always wrap construction in try/catch in validation rules, as shown above, or you will turn a bad user input into a 500.
• Format acceptance is inconsistent across versions. Some paths tolerate spaces, some don't, and case handling is not uniformly applied. Uppercasing and space-stripping yourself is the only reliable contract.
• Country coverage is frozen at 2017. Countries that joined the IBAN registry afterward, or whose BBAN layout changed, may be wrongly rejected or wrongly parsed. If you operate in newer SEPA markets, verify coverage with a fixture per country before shipping.
• getBankIdentifier() / getAccountNumber() are layout-dependent. They reflect the registry's BBAN split for that country, not a universal rule. Don't assume their lengths or semantics across countries; some countries don't define a bank identifier at all.
• The mod-97 check only proves the string is a well-formed IBAN. It says nothing about whether the account is open, belongs to the user, or matches the account holder's name. Never skip provider-side verification based on this result.
• Random generation (if used for seeds/demos) produces syntactically valid but fictional accounts. Keep it out of production flows and out of anything that could be mistaken for a real payout instruction.
• Debugging failures: decompose the IBAN — length, country prefix presence, checksum. A quick external cross-check against a known-good validator for the specific country usually distinguishes "bad input" from "package doesn't know this country."
• Storing formats: persist compact uppercase only. Storing the spaced form causes duplicate-account detection to fail and breaks any unique index you put on the column.
• Migration path: wrap the package behind your own IbanValidator/IbanParser contract now. When you move to symfony/validator or php-iban, your FormRequests, accessors, and payout services stay untouched.