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

RateLimiter::acquire() (used by Downloader) checks the 30 second window and reserves the slot in one step under an exclusive flock() on the store file. Concurrent cron jobs or workers sharing the same store file therefore never send a request for the same token within one window: in wait mode they queue up, otherwise TooGreedyException is thrown. Failing to open, lock or write the store file throws a RuntimeException instead of silently disabling the limit.

Custom store backend

Implement FioApi\RateLimit\AtomicRateLimitStoreInterface (tryAcquire() must check and reserve atomically) to use a database or other shared storage (e.g. Redis, SQLite) instead of a JSON file. Stores implementing only FioApi\RateLimit\RateLimitStoreInterface still work, but fall back to a non-atomic check followed by record.

Testing

The library includes unit tests for all rate limiting components:

composer test

Requirements

Fio API PHP works with PHP 8.1 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