search

sandermarechal / jejik-mt940

An MT940 bank statement parser for PHP
MIT License
82 stars 33 forks source link

readme

Jejik/MT940

An MT940 bank statement parser for PHP

Build Status

Installation

You can install Jejik/MT940 using Composer. You can read more about Composer and its main repository at http://packagist.org. First install Composer for your project using the instructions on the Packagist home page, then define your dependency on Jejik/MT940 in your composer.json file.

composer require jejik/mt940

This library follows the PSR-0 standard. You will need a PSR-0 compliant autoloader to load the Jejik/MT940 classes. Composer provides one for you in your vendor/.composer/autoload.php.

PSR-12 standard is for Code-Syntax.

Usage

<?php

use Jejik\MT940\Reader;

$reader = new Reader();
$statements = $reader->getStatements(file_get_contents('mt940.txt'));

foreach ($statements as $statement) {
    echo $statement->getOpeningBalance()->getAmount() . "\n";

    foreach ($statement->getTransactions() as $transaction) {
        echo $transaction->getAmount() . "\n";
    }

    echo $statement->getClosingBalance()->getAmount() . "\n";
}

Statement structure

The returned statements have the following properties. Not all banks supply all properties (e.g. only few provide a transaction book date separately). Properties that are not supplied will be null.

Supported banks

Currencly there are statement parsers for the following banks:

Adding bank parsers

You can easily add your own parser to the statement reader.

<?php

use Jejik\MT940\Reader;

$reader = new Reader();
$reader->addParser('My bank', 'My\Bank');

When you add your own parser, the default list of parsers is cleared. You must add them back if you want the reader to support them as well.

<?php

/** @var \Jejik\MT940\Reader $reader */
$reader->addParsers($reader->getDefaultParsers());

You can also add your parser at a specific place in the parser chain. For example, this is how you add your parser before the ING parser.

<?php

/** @var \Jejik\MT940\Reader $reader */
$reader->addParsers($reader->getDefaultParsers());
$reader->addParser('My bank', 'My\Bank', 'ING');

Custom parsers should extend the Jejik\MT940\Parser\AbstractParser class. Have a look at the parsers already implemented to see how to support your bank. At the very minimum, you should implement the accept() method.

<?php

namespace My;

use Jejik\MT940\Parser\AbstractParser;

class Bank extends AbstractParser
{
    public function accept(string $text): bool
    {
        return strpos($text, 'MYBANK') !== false;
    }
}

Injecting classes

You can easily extend the build-in objects and inject them into the MT940 reader. This allows for easily integrating MT940 into your application. For example, by storing the statements in your database. You can inject them using the following methods:

You can either specify the classname as a string, or provide a PHP callable that returns an object. Your classes do not have to extend the built-in classes but they must implement the proper interfaces.

The callable for the Statement class is passed an AccountInterface and the statement sequence number as parameters. The callable for the Account class and ContraAccount class are passed the account number as parameter. The other callables are not passed any variables.

If the callable for the Account class or Statement class returns null then that statement will be skipped by the parser.

An example, integrating MT940 with your ORM:

<?php

use Jejik\MT940\AccountInterface;
use Jejik\MT940\Reader;

$db = new ORM(); // Whatever your flavour is...
$reader = new Reader();

$reader->setAccountClass(function ($accountNumber) use ($db) {
    $account = $db::factory('My\Account')->findBy(array(
        'number' => $accountNumber,
    ));

    return $account ?: new My\Account();
});

$reader->setStatementClass(function (AccountInterface $account, $number) use ($db) {
    $statement = $db::factory('My\Statement')->findBy(array(
        'account' => $account->getNumber(),
        'number'  => $number,
    ));

    return $statement ?: new My\Statement();
});

$reader->setTransactionClass('My\Transaction')
       ->setContraAccountClass('My\ContraAccount')
       ->setOpeningBalanceClass('My\OpeningBalance')
       ->setClosingBalanceClass('My\ClosingBalance');

foreach ($reader->getStatements(file_get_contents('mt940.txt'))) {
    $statement->save();
}

Contributing

If you have written a parser for your bank, I'd be happy to add it to the list of default parsers. Just send me a Pull Request with your parsers. Make sure that you also add a unit test for it that parses a test document. You can redact personal information from the test document (e.g. use '123456789' for the account number, etcetera).

I am also happy to implement a parser for you, if you prefer that. Just open an issue and I will contact you privately. I will need an unredacted MT940 file from your bank. It needs to be unredacted because the MT940 isn't well defined and can be fickle. If you redact it, it is possible that the parser I write will work on the file you supplied but not on the real thing. Of course, I will redact the file for you when I add it to my unit tests.

Do not add unredacted MT940 files in the issue tracker please. Send them to me privately. My e-mail address is listed in the source code files.

License

Jejik\MT940 is licensed under the MIT license. See the LICENSE.txt file for the full details. The test files for the ABN-AMRO, ING, Rabobank and Triodos bank come from the dovadi/mt940 ruby parser. Their license can be found in the LICENSE.fixtures.txt file.

The test file for Sparkasse come from Dominic Richter / Powercloud GmbH. The Parser Commerzbank, Deutsche Bank, German Bank, Landesbank Berlin, NuaPay, Oldenburgische Landesbank, Sparkasse, StarMoney and Unicredit come from Powercloud GmbH.