davidvanerkelens / ynab-php-client
A PHP client implementation for the You Need A Budget (YNAB) API.
Requires
- doctrine/annotations: ^1.13
- fig/http-message-util: ^1.1
- guzzlehttp/guzzle: ^7.0
- phpdocumentor/reflection-docblock: ^5.2
- symfony/cache: ^5.3
- symfony/property-access: ^5.3
- symfony/serializer: ^5.3
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.1
- phpspec/prophecy: ^1.14
- phpspec/prophecy-phpunit: ^2.0
- phpunit/phpunit: ^9.5
- squizlabs/php_codesniffer: 3.*
- vimeo/psalm: ^4.9
README
This is a PHP client implementation for the You Need A Budget (YNAB) API.
⚠️ This library is still in active development. Not all code is covered by tests yet, and contracts are subject to change. Breaking changes will be released according to semantic versioning version numbers.
Installation
Using composer
composer require davidvanerkelens/ynab-php-client
Manual installation
Download the contents of this repository, and include the vendor/autoloader.php
file.
Basic usage
In order to use this library, you need an API key. See the YNAB API documentation for more information about this.
// Create a basic configuration // Returns an instance of ConfigurationInterface $config = YNAB::createConfiguration('your api token'); // Create a client object // Returns an instance of ClientInterface $client = YNAB::createClient($config);
Via the $client
object, all non-deprecated methods available on the YNAB API can be accessed. See this
document for all available methods on the client object.
Server knowledge
Several endpoints can be provided with a number, indicating the last server knowledge state. If available, the server knowledge state is included in the response object.
Error handling
If a request to the API returns an unexpected status code, a YnabErrorException will be thrown. In this exception, an instance of ErrorResponseInterface can be found, which contains the error reported by the YNAB API.
Milliunits
All amounts reported by the YNAB API are in milliunits format. A converter for this format is available.
$converter = YNAB::getMilliunitsConverter(); $converter->toFloat(123930); // returns 123.93 $converter->fromFloat(123.93); // returns 123930
Rate limiting
YNAB's API is rate limited to 200 requests per access token per hour. The current usage is returned by the YNAB API in a header, which you can fetch via the client object after a call to the API has been performed.
$config = YNAB::createConfiguration('your api token'); $client = YNAB::createClient($config); // your logic here $rateLimit = $client->getRateLimit();
This function will return null
if no requests have been made yet. The returned value of this function is the number of
requests made towards the rate limit as reported at the moment of the last response from the YNAB API.
Caching
This library supports caching for all GET requests. By default, a simple in-memory cache will be used with a timeout of 5 minutes. If you want to disable caching, you can do so via the configuration object.
$config = YNAB::createConfiguration('your api token'); $config->setCachingDisabled(true);
In the same way, you can configure the timeout for the cache.
$config = YNAB::createConfiguration('your api token'); $config->setCacheTimeout(new DateInterval("PT10M"));
You can also call the setCacheTimeout
function with null
to disable expiration of cached items.
It is also possible to provide your own caching adapter that implements the PSR-6
CacheItemPoolInterface
.
$config = YNAB::createConfiguration('your api token'); $config->setCacheItemPool(new MyCache());
Contributing
This library is still an active work in progress by the author. Pull requests are appreciated, but the library can undergo structural changes at any moment in time.