Download the PHP package daycry/iban without Composer

Daycry Iban

IBAN validation, parsing, formatting and bank-entity resolution for CodeIgniter 4 — usable standalone, with a zero-dependency core.

Quickstart

Facade (framework-free, works standalone)

CI4 service

CI4 helper

spark commands

Complete per-symbol API reference: docs/api-reference.md. Task-oriented guide — the 16 ViolationCode cases, the national validators, caching, and the Config\Iban options: see docs/importers.md.

API overview

The public surface is the facade Daycry\Iban\Iban (also what service('iban') returns). Every method accepts a raw string; the ones that already have a parsed value object accept that too.

IBAN

BIC / SWIFT

Sub-service accessors

validator(), parser(), resolver(), bicValidator() and bicParser() return the underlying components, for when you want to reuse a single instance or call them directly.

The helper (helper('iban')) mirrors these as plain functions (iban_validate(), iban_parse(), iban_resolve(), bic_is_valid(), iban_bic_validate(), …) and every helper is degradation-safe — none throw. See docs/api-reference.md for the exhaustive per-symbol reference.

Database setup (optional)

Validation, parsing, formatting and BIC checks need no database — the core ships a compiled registry and works out of the box. The database is only for bank-entity resolution (resolve() / resolveBic() returning real bank names and BICs) and, optionally, for serving the ISO 3166-1 country list from a table instead of the bundled compiled list. These steps only apply under CodeIgniter 4.

1. Run the migrations

Both tables (banks and iso_countries) live in the package's module namespace, so migrate it:

2. Enable the database provider

Publish the config (php spark iban:publish) and, in app/Config/Iban.php, switch the provider:

3. Populate the banks table

No bank data ships with the package (by licensing design — see docs/licensing.md). You fill the table yourself from official sources with the bundled importers:

The BanksSeeder is intentionally empty — it exists only as a seed hook; the importers are the real data path. See docs/importers.md for the full source list and coverage matrix.

4. (Optional) Serve ISO 3166-1 from the database

BIC validation uses the bundled compiled ISO 3166-1 list by default ($isoCountrySource = 'php' — nothing to install). To serve it from the iso_countries table instead (so you can edit it in the DB), set $isoCountrySource = 'database' in app/Config/Iban.php and seed the table from the compiled list:

Features

• ISO 13616 + MOD-97 validation over a structural registry covering 78 countries — length, BBAN token grammar, and field offsets, all compiled into PHP (no runtime data files, no network).
• Structural parsing: country code, IBAN check digits, BBAN, bank identifier, branch identifier (where applicable), account number, and national check digit — all as a ParsedIban value object.
• Three output formats: Electronic (canonical, no spaces), Print (space-grouped every 4 chars), Anonymized (country code + last 4 digits visible, rest masked). See docs/formatting.md.
• Pluggable bank-entity resolver: resolve() always returns a BankResult; bank fields stay null with the default NullProvider, or get filled in by the optional DatabaseProvider once you seed the banks table — optionally cached via Providers\CachedProvider (Config\Iban::$cacheTtl). A bank-level fallback (findByBankCode($cc, $bank, null)) resolves branch-carrying IBANs even when only a bank-level row was imported.
• National check-digit validation for 9 countries (checkNational: true): ES, BE, PT, SI, FI, FR (+MC), IT (+SM) — see docs/usage.md for the algorithm per country (Estonia is deliberately not covered — its real algorithm needs bank-specific data the IBAN doesn't carry).
• BIC / SWIFT validation (ISO 9362): validate, parse (ParsedBic), and — given both an IBAN and a BIC — cross-check them for country and (where structurally possible) bank coherence, plus optional BIC-first bank resolution (resolveBic()). Country codes are checked against a bundled 249-code ISO 3166-1 registry, so BICs from non-IBAN countries (US, JP, …) validate too. A BIC has no checksum, so "valid" means well-formed + recognised country, never "this BIC exists". Works standalone, no database. See docs/usage.md.
• 30 bundled bank-data importers, none of them bundling any actual data: iban:update lists/runs official-source importers for 25 countries (AT, DE, CH, NL, ES, CZ, GR, SI, SK, BG, MD, PL, AZ, BE, HR, LU, MT, HU, NO, GE, IL, UA, KZ, LI, BR) plus the EPC SEPA Register, which covers GB, GI, IE, LV and RO and also reports SEPA reachability (SCT/SCT Inst/SDD Core/SDD B2B) — live or from a local --file. 24 of 42 SEPA countries now resolve. See docs/importers.md for the full list and coverage matrix.
• Zero-dependency core: Daycry\Iban\Iban and everything under Core/, Contracts/, DTO/, Enums/, Exceptions/, Registry/, National/, Resolver/ never import CodeIgniter — usable in a plain php -r script, a CLI tool, or any other framework. (The package as a whole additionally requires ext-mbstring, ext-iconv and ext-zip, used by the bundled importers to normalize source encodings and read .xlsx sources.)
• First-class CI4 integration: service('iban'), helper('iban'), Config\Iban, and 6 spark commands (iban:validate, iban:parse, iban:resolve, iban:update, iban:publish, iban:bic) — auto-discovered, no manual wiring required.

Standalone usage (outside CodeIgniter 4)

The core has zero framework dependencies (PHP ^8.3 + ext-mbstring + ext-iconv + ext-zip only), so you can use it without CI4 installed at all:

codeigniter4/framework is only a require-dev (test/dev) dependency — it is never pulled in by a plain composer require daycry/iban for standalone use. Config\Iban, Config\Services, the spark commands, Models\BankModel, the optional DatabaseProvider/CachedProvider, and Import\ImportRunner are the only pieces that need CI4; they simply aren't loaded unless CI4 itself is present in the consuming application. The bundled importers themselves (Import\Importers/*) and the ImporterInterface/ImportReport/ImporterRegistry framework stay CI4-free, fetching over plain PHP.

Architecture

The package is split into two layers connected by a one-way dependency rule: the framework-free core and resolver never know about CodeIgniter 4.

See CLAUDE.md for the full breakdown, including which directories are guarded (framework-free) and which are allowed to depend on CI4.

Compatibility matrix

CodeIgniter 4 is optional (require-dev only) — the core works on plain PHP 8.3/8.4 with no framework at all.

Documentation

• docs/api-reference.md — the complete public-API reference: every facade method, helper function, config property, DTO, enum, exception, contract, and registry member, verified against the source.
• docs/usage.md — full facade/helper/command API, the 16 ViolationCode cases, national check-digit validators, BIC/SWIFT validation, resolve() with NullProvider/DatabaseProvider/CachedProvider, Config\Iban reference.
• docs/importers.md — the bank-data importer framework, iban:update reference, the 30 bundled official-source importers with a coverage matrix, and how to write a custom one.
• docs/formatting.md — Electronic / Print / Anonymized formats, with the exact Anonymized mask scheme.
• docs/i18n.md — why validation messages are English-only in the core, and how to translate them at the CI4 layer.
• docs/licensing.md — why no SWIFT/SwiftRef/globalcitizen/Wikipedia data is bundled, and how the registry was independently authored.
• docs/registry-authoring.md — methodology for authoring/cross-checking the structural country registry.
• docs/architecture.md — the two-layer architecture and the enforced dependency rule.
• docs/roadmap.md — what shipped in v1.1, and what's planned for v2.0.
• CHANGELOG.md — release history (Keep a Changelog format).

Development

No composer.lock: as a library (not an application), composer.lock is gitignored on purpose. CI always runs composer update against the version constraints in composer.json, so the test matrix reflects what consumers actually get.

License

MIT License - see LICENSE file for details.