Skip to content
This repository has been archived by the owner on Aug 24, 2023. It is now read-only.

Latest commit

 

History

History
106 lines (80 loc) · 4.11 KB

README.md

File metadata and controls

106 lines (80 loc) · 4.11 KB
Raw

PHP client library for YNAB

build status version release date license

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.

Authors

License

MIT