Increase PHP API library

The Increase PHP library provides convenient access to the Increase REST API from any PHP 8.1.0+ application.

Documentation

The REST API documentation can be found on increase.com.

Installation

composer require "increase/increase 0.145.0"

Usage

This library uses named parameters to specify optional arguments. Parameters with a default value must be set by name.

<?phpuseIncrease\Client;
$client = newClient(
apiKey: getenv('INCREASE_API_KEY'),
environment: 'sandbox',
);
$account = $client->accounts->create(
name: 'New Account!',
entityID: 'entity_n8y8tnk2p9339ti393yi',
programID: 'program_i2v2os4mwza1oetokh9i',
);
var_dump($account->id);

Value Objects

It is recommended to use the static with constructor Dog::with(name: "Joey") and named parameters to initialize value objects.

However, builders are also provided (new Dog)->withName("Joey").

Pagination

List methods in the Increase API are paginated.

This library provides auto-paginating iterators with each list response, so you do not have to request successive pages manually:

<?phpuseIncrease\Client;
$client = newClient(
apiKey: getenv('INCREASE_API_KEY'),
environment: 'sandbox',
);
$page = $client->accounts->list();
var_dump($page);
// fetch items from the current pageforeach ($page->getItems() as$item) {
var_dump($item->id);
}
// make additional network requests to fetch items from all pages, including and after the current pageforeach ($page->pagingEachItem() as$item) {
var_dump($item->id);
}

Handling errors

When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of Increase\Core\Exceptions\APIException will be thrown:

<?phpuseIncrease\Core\Exceptions\APIConnectionException;
useIncrease\Core\Exceptions\RateLimitException;
useIncrease\Core\Exceptions\APIStatusException;
try {
$account = $client->accounts->create(name: 'Oops');
} catch (APIConnectionException$e) {
echo"The server could not be reached", PHP_EOL;
var_dump($e->getPrevious());
} catch (RateLimitException$e) {
echo"A 429 status code was received; we should back off a bit.", PHP_EOL;
} catch (APIStatusException$e) {
echo"Another non-200-range status code was received", PHP_EOL;
echo$e->getMessage();
}

Error codes are as follows:

Cause	Error Type
HTTP 400	BadRequestException
HTTP 401	AuthenticationException
HTTP 403	PermissionDeniedException
HTTP 404	NotFoundException
HTTP 409	ConflictException
HTTP 422	UnprocessableEntityException
HTTP 429	RateLimitException
Other HTTP error	APIStatusException
Timeout	APITimeoutException
Network error	APIConnectionException

Retries

Certain errors will be automatically retried 2 times by default, with a short exponential backoff.

Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal errors, and timeouts will all be retried by default.

You can use the maxRetries option to configure or disable this:

<?phpuseIncrease\Client;
// Configure the default for all requests:$client = newClient(requestOptions: ['maxRetries' => 0]);
// Or, configure per-request:$result = $client->accounts->create(
name: 'New Account!',
entityID: 'entity_n8y8tnk2p9339ti393yi',
programID: 'program_i2v2os4mwza1oetokh9i',
requestOptions: ['maxRetries' => 5],
);

File uploads

Request parameters that correspond to file uploads can be passed as a resource returned by fopen(), a string of file contents, or a FileParam instance.

<?phpuseIncrease\Core\FileParam;
// Pass a string with filename and content type:$contents = file_get_contents('my/file.txt');
// Pass a string with filename and content type:$file = $client->files->create(
file: FileParam::fromString($contents, filename: 'my/file.txt', contentType: '…'),
purpose: 'check_image_front',
);
// Pass in only a string (where applicable)$file = $client->files->create(file: 'check.png', purpose: 'check_image_front');
// Pass an open resource:$fd = fopen('my/file.txt', 'r');
try {
$file = $client->files->create(
file: FileParam::fromResource($fd, filename: 'my/file.txt', contentType: '…'),
purpose: 'check_image_front',
);
} finally {
fclose($fd);
}

Advanced concepts

Making custom or undocumented requests

Undocumented properties

You can send undocumented parameters to any endpoint, and read undocumented response properties, like so:

Note: the extra* parameters of the same name overrides the documented parameters.

<?php$account = $client->accounts->create(
name: 'New Account!',
entityID: 'entity_n8y8tnk2p9339ti393yi',
programID: 'program_i2v2os4mwza1oetokh9i',
requestOptions: [
'extraQueryParams' => ['my_query_parameter' => 'value'],
'extraBodyParams' => ['my_body_parameter' => 'value'],
'extraHeaders' => ['my-header' => 'value'],
],
);

Undocumented request params

If you want to explicitly send an extra param, you can do so with the extra_query, extra_body, and extra_headers under the request_options: parameter when making a request, as seen in the examples above.

Undocumented endpoints

To make requests to undocumented endpoints while retaining the benefit of auth, retries, and so on, you can make requests using client.request, like so:

<?php$response = $client->request(
method: "post",
path: '/undocumented/endpoint',
query: ['dog' => 'woof'],
headers: ['useful-header' => 'interesting-value'],
body: ['hello' => 'world']
);

Versioning

This package follows SemVer conventions. As the library is in initial development and has a major version of 0, APIs may change at any time.

This package considers improvements to the (non-runtime) PHPDoc type definitions to be non-breaking changes.

Requirements

PHP 8.1.0 or higher.

Contributing

See the contributing documentation.