README

Author: Tomasz Chmielewski

The library is an unofficial PHP-wrapper for backend Kontomatik service.

Library allows a developer to easily fetch data from remote kontomatik service, listen to the client-server communication while getting the data and parse XML files to Entities.

1. Installation

via git

git clone git@bitbucket.org:solvenfinance/kontomatikapi.git

via composer

composer require solvenfinance/kontomatikapi

2. Theory of operation

How does it work?

1. KontomatikApi\Source\SourceInterface

The interface defines the way it fetches data from the source. In this concrete implementation, KontomatikApi\Source\KontomatikRemote is responsible for delivering successful-state XML. Internally, first it orders executing a command, then it keeps asking with the defined interval (default is 1000 ms) the remote source for the command result. Each time the request is made, KontomatikApi\Source\KontomatikRemote\Event\DataFetchedEvent is triggered. If it is in the successful state already, the ready XML is returned. If the remote source returned error, KontomatikApi\Source\KontomatikRemote\KontomatikErrorException is thrown.

2. KontomatikApi\Mapper\MapperInterface

The interface defined the way remote, successful-state XML is parsed. In this concrete implementation KontomatikApi\Mapper\Mapper can be used. You can produce such an instance, using KontomatikApi\Mapper\StandardMapperFactory. More details can be found in chapter 5 of this documentation.

3. KontomatikApi\KontomatikService

The service sticks the interfaces mentioned in above paragraphs all together. More details can be found in chapter 3 of this documentation

3. Kontomatik Service

To fetch data from remote Kontomatik service all you need to do is to create command object and execute it.

use KontomatikApi\KontomatikService;
use KontomatikApi\Command\ResultAggregate;
use KontomatikApi\Entity\Account;
use KontomatikApi\Entity\Owner;
use KontomatikApi\Entity\MoneyTransaction;

$service = KontomatikService::buildRemoteKontomatik("https://test.api.kontomatik.com", "superSecretApiKey");

$command = new DefaultImport(
    "212321", "secretSignature", "2016-01-01"
);

try {
    /** @var ResultAggregate */
    $result = $service->execute($command);
    
    foreach ($result as $row) {
        if ($row instanceof Account) {
            // prints "PL210009990009999090900 ..."
            echo (string)$row->iban;
            
            // tylko dla komendy DefaultImport
            foreach ($row->moneyTransactions as $transaction) {
                // prints "return for new years eve party ..."
                echo (string)$transaction->title;
            }
        }
        
        if ($row instanceof MoneyTransaction) {
            // prints "return for new years eve party ..."
            echo (string)$row->title;
        }
        
        if ($row instanceof Owner) {
            // prints "88010109380"
            echo (string)$row->pesel;
        }                
    }
    
} catch (\Exception $e) {
    // ... handle connection/validation exceptions
}

4. Listening to client-server communication

You can attach your own listener to listen while KontomatikRemote data source fetches XMLs from server. Listener pattern relies here on ZendFramework 3 EventManager module. If you're familiar with this library, you should have no problem with implementing your own listener.

use KontomatikApi\KontomatikService;
use KontomatikApi\Source\KontomatikRemote\Event\DataFetchedEvent;

$service = KontomatikService::buildRemoteKontomatik("https://test.api.kontomatik.com", "superSecretApiKey");
$eventManager = $service->getDataSource()->getEventManager();

// prints whole client-server communication
$eventManager->attach(DataFetchedEvent::DATA_FETCHED_EVENT, function (DataFetchedEvent $event) {
    echo $event->getXml();
});

// prints only successful result of the command
// you can attach to this listener for logging response XML to the file, etc...
$eventManager->attach(DataFetchedEvent::DATA_FETCHED_EVENT, function (DataFetchedEvent $event) {
    $elements = @simplexml_load_string($event->getXml());
    $state = $body->command->attributes()['state'];
    $commandStatus = CommandStatus::fromNative((string)$state);
    if ($commandStatus->isSuccessful()) {
        // perform XML log to file...
    }
});

5. Parse raw XML files to entities

You can use standalone interface KontomatikApi\Mapper\MapperInterface implementation to parse previously cached/stored XML files.

use KontomatikApi\Mapper\StandardMapperFactory;

$mapper = StandardMapperFactory::buildStandardMapper();
$result = $mapper->doMapping(file_get_contents('previouslyStoredXmlFile.xml'));

solvenfinance / kontomatikapi

Maintainers

Details