README

BAV (bank account validator) is a validation library for German bank accounts.

This repository is an actively maintained fork of the original project. It it also regularly released to packagist.org, so you can install it with Composer using cashlink/bav.

Installation

Use Composer:

{
    "require": {
        "cashlink/bav": "^3"
    }
}

Configuration

You can use BAV out of the box. BAV comes with a ready to play default configuration (DefaultConfiguration):

UTF-8 encoding (if supported)
FileDataBackendContainer. I.e. it uses binary search on the file from the Bundesbank. Note that this data backend uses the directory bav/data for install and update operations. You have to make sure that this directory is writable.
automatic installation. You don't have to call any installation script. The container will download the Bundesbank file upon the first execution.
update plan which triggers an E_USER_NOTICE if the Bundesbank file is outdated.

You can define your own configuration by calling ConfigurationRegistry::setConfiguration() or preferably creating the file bav/configuration.php which returns a Configuration object:

namespace malkusch\bav;

$configuration = new DefaultConfiguration();

$pdo = new \PDO("mysql:host=localhost;dbname=test;charset=UTF8");
$configuration->setDataBackendContainer(new PDODataBackendContainer($pdo));

$configuration->setUpdatePlan(new AutomaticUpdatePlan());

return $configuration;

Update

The Bundesbank releases new files for March, June, September and December. BAV needs those new files. You have several possiblities to update bav:

Script

Call bin/bav-update.php.

Programmatically

use malkusch\bav\BAV;

$bav = new BAV();
$bav->update();

Automatic

Enable automatic updates with AutomaticUpdatePlan in your bav/configuration.php:

namespace malkusch\bav;

$configuration = new DefaultConfiguration();
$configuration->setUpdatePlan(new AutomaticUpdatePlan());

return $configuration;

This automatic update plan will perform long running update operations as a shutdown hook. I.e. it won't bother users during normal operations.

Usage

You can use BAV with the api facade BAV:

BAV::isValidBank($bankID): Returns true for existing bank ids.
BAV::isValidBankAccount($bankID, $account): Returns true for existing accounts of an existing bank.
BAV::isValidAccount($account): This method validates an account against the bank of the last isValidBank() call.
BAV::getValidBankFilterCallback(): Returns a callback for filter bank validation.
BAV::getValidAccountFilterCallback(): Returns a callback for filter account validation. The account filter needs to be called after the bank filter.
BAV::getMainAgency(): Returns the main agency of a bank.
BAV::getAgencies(): Returns further agencies. The main agency is not included in this list. This list can be empty.

An Agency object has the fields:

Example

use malkusch\bav\BAV;

$bav = new BAV();
$bankID  = "10000000";
$account = "1234567890"

// check for a bank
var_dump(
    $bav->isValidBank($bankID)
);

// check for a bank account
var_dump(
    $bav->isValidBankAccount($bankID, $account)
);

// filter validation
var_dump(
    filter_var($bankID, FILTER_CALLBACK, $bav->getValidBankFilterCallback()),
    filter_var($account, FILTER_CALLBACK, $bav->getValidAccountFilterCallback())
);

// Get informations about a bank
$agency = $bav->getMainAgency($bankID);
echo "{$agency->getName()} {$agency->getCity()}\n";

Optional Dependencies

You may have:

CURL: If you provide bav/data/banklist.txt you don't need CURL.
mbstring: BAV works with unicode encoding. Your PHP must have support compiled in the mb_* functions. If these functions are missing BAV works only with the ISO-8859-15 encoding.
PDO: If you intend to use a DBS you need to use PDODataBackendContainer. PDODataBackendContainer needs a PDO support compiled in PHP.
doctrine/orm: You can use DoctrineBackendContainer which uses doctrine as data backend.

License and authors

The author of the original project which gave the idea to this project is Björn Wilmsmann. Previous maintainer is Markus Malkusch markus@malkusch.de.

cashlink / bav

Maintainers

Details