Fio API PHP implemention

Fio bank REST API implementation in PHP. It allows you to download and iterate through account balance changes.

There is a Symfony Bundle for using this library in a Symfony app.

Usage

1. Install the latest version with composer require mhujer/fio-api-php
2. Create a token in the ebanking (Nastavení / API)
3. Use it according to the example bellow and check the docblocks

<?php
require_once 'vendor/autoload.php';

$downloader = new FioApi\Downloader('TOKEN@todo');
$transactionList = $downloader->downloadSince(new \DateTimeImmutable('-1 week'));

foreach ($transactionList->getTransactions() as $transaction) {
    var_dump($transaction); //object with getters
}

Available endpoints:

• downloadFromTo(DateTimeInterface $from, DateTimeInterface $to): TransactionList
• downloadSince(DateTimeInterface $since): TransactionList
• downloadLast(): TransactionList
• setLastId(string $id) - sets the last downloaded ID through the API

Rate Limiting

Fio API enforces a 30-second cooldown between requests using the same token. If you make a request sooner, the API returns HTTP 409.

This library includes a built-in rate limiter that coordinates requests across multiple processes using a shared JSON file with file locking.

Wait mode (default) — sleeps until the token is ready:

<?php
require_once 'vendor/autoload.php';

$store = new FioApi\RateLimit\JsonRateLimitStore('/tmp/fio-rate-limit.json');
$limiter = new FioApi\RateLimit\RateLimiter($store, true);

$downloader = new FioApi\Downloader('TOKEN@todo', null, $limiter);
$transactionList = $downloader->downloadSince(new \DateTimeImmutable('-1 week'));

In wait mode, if less than 30 seconds have passed since the last request for the same token, the limiter will sleep() for the remaining time before proceeding.

Throw mode — throws exception immediately:

<?php
require_once 'vendor/autoload.php';

$store = new FioApi\RateLimit\JsonRateLimitStore('/tmp/fio-rate-limit.json');
$limiter = new FioApi\RateLimit\RateLimiter($store, false);

$downloader = new FioApi\Downloader('TOKEN@todo', null, $limiter);

try {
    $transactionList = $downloader->downloadSince(new \DateTimeImmutable('-1 week'));
} catch (FioApi\Exceptions\TooGreedyException $e) {
    // Handle: request came too soon, try again later
}

Multi-process safety

The JsonRateLimitStore uses flock() for file-level locking, so multiple cron jobs or workers sharing the same store file will safely stagger their API calls without colliding.

Custom store backend

You can implement FioApi\RateLimit\RateLimitStoreInterface to use a database or other shared storage (e.g. Redis, SQLite) instead of a JSON file.

Testing

The library includes unit tests for all rate limiting components:

composer test

Requirements

Fio API PHP works with PHP 7.4 or higher (including PHP 8.4).

Submitting bugs and feature requests

Bugs and feature request are tracked on GitHub

Author

Martin Hujer - https://www.martinhujer.cz

Changelog

5.0.0 (2024-06-07)

• #31 add composer/ca-bundle as a required dependency instead of bundled root cert (thx @feldsam!)

4.2.0 (2024-05-30)

• #28 use new Fio API URL (thx @feldsam!)

4.1.2 (2019-12-28)

• #19 gracefully handle response with empty column8 (thx @fmasa!)

4.1.1 (2019-01-28)

• #17 added senderName (nazev protiuctu) (thx @jan-stanek!)

4.1.0 (2018-04-13)

• #13 Support /last and /set-last-id endpoints (thx @jiripudil!)

4.0.1 (2017-08-09)

• #12 handle empty transaction list (thx @soukicz!)

4.0.0 (2017-08-04)

• #9 minimal supported version is PHP 7.1
• #9DateTime replaced with DateTimeImmutable (or DateTimeInterface)
• #9 strict types and primitive typehints are used everywhere

3.0.0 (2016-11-24)

• dropped support for PHP <7

2.3.0 (2016-11-24)

• #7: added official composer CA bundle support (@soukicz)

2.2.0 (2016-03-13)

• #2: added Kdyby/CurlCaBundle as an optional dependency (@mhujer)

2.1.0 (2016-03-12)

• #1: updated default GeoTrust certificate (@soukiii)
• #1: added specification field in transaction (@soukiii)

2.0.0 (2015-06-14)

• upgraded to Guzzle 6
• support for PHP 5.4 dropped (as Guzzle 6 requires PHP 5.5+)

1.0.3 (2015-06-14)

• updated root certificate (Root 3) as the Fio changed it on 2014-05-26

1.0.0 (2015-04-05)

• initial release