README

This is a PHP client for REST APIs like the TraderOnline APIs.

Requirements

This api client requires PHP 7.3 or newer and uses composer to install further PHP dependencies. See the composer specification for more details.

When contributing, access to a working mongo database for testing is needed. See the Contribution Guidelines for more details.

Installation

tol-api-php can be installed for use in your project using composer.

The recommended way of using this library in your project is to add a composer.json file to your project. The following contents would add tol-api-php as a dependency:

composer require traderinteractive/tol-api

Basic Usage

The basic guzzle client, without caching or automated pagination handling is mostly easy to work with.

To instantiate a client, you need the guzzle adapter, client id, client secret, and API url. This client should work with apis like the TOL APIs.

use TraderInteractive\Api;
$apiAdapter = new Api\GuzzleAdapter();
$auth = Api\Authentication::createClientCredentials(
    'clientId',
    'clientSecret'
)
$apiClient = new Api\Client(
    $apiAdapter,
    $auth,
    'https://baseApiUrl/v1'
);

Then you can make index requests like below, although it is recommended to take a look at the Collection section below so that you can take advantage of automatic pagination handling. Here's an example of how to fetch a single page of items.

<li>
<?php
$response = $apiClient->index(
    'resourceName',
    array('aFilter' => '5')
);

if ($response->getStatusCode() !== 200) {
    throw new Exception('Non successful index call');
}

$body = json_decode($response->getBody(), true);
$total = $body['pagination']['total'];

// Loop over the first page of items
foreach ($body['result'] as $item) {
    echo "<li>{$item['foo']}</li>\n";
}
?>
</ul>

For getting just a single item back from the api, you can use the get method:

// Get item 1234
$response = $apiClient->get('resourceName', '1234');

if ($response->getStatusCode() !== 200) {
    throw new Exception('Failed to fetch item 1234');
}

$item = json_decode($response->getBody(), true);
echo "Fetched item {$item['foo']}\n";

For creating a new item, you can use the post method:

$response = $apiClient->post(
    'resourceName',
    array(
        'foo' => array(
            'bar' => 'boo',
            'bing' => '5',
        ),
    )
);

if ($response->getStatusCode() !== 201) {
    throw new Exception('Failed to create item foo');
}

$item = json_decode($response->getBody(), true);
echo $item['result']['foo'];

For updating an item, you can use the put method:

// Set item 1234's foo to bar.
$response = $apiClient->put(
    'resourceName',
    '1234',
    array('bing' => array('foo' => 'bar'))
);

if ($response->getStatusCode() !== 200) {
    throw new Exception('Failed to update item 1234');
}

For deleting an item, you can use the delete method:

// Delete item 1234.
$response = $apiClient->delete('resourceName', '1234');

if ($response->getStatusCode() !== 204) {
    throw new Exception('Failed to delete item 1234');
}

For making asynchronous requests use the start*() and end() methods:

$handleOne = $apiClient->startGet('resourceName', '1234');
$handleTwo = $apiClient->startGet('resourceName', '5678');

$responseOne = $apiClient->end($handleOne);
$responseTwo = $apiClient->end($handleTwo);

if ($responseOne->getStatusCode() !== 200) {
    throw new Exception('Failed to fetch item 1234');
}

if ($responseTwo->getStatusCode() !== 200) {
    throw new Exception('Failed to fetch item 5678');
}

$itemOne = json_decode($responseOne->getBody(), true);
$itemTwo = json_decode($responseTwo->getBody(), true);

echo "Fetched item {$itemOne['foo']}\n";
echo "Fetched item {$itemTwo['foo']}\n";

Cache

The library allows for a PSR-16 SimpleCache implementation.

Collection

This is the preferred way to make index requests so that you don't have to handle (or forget to handle!) pagination yourself. Using this iterator is simple with the API Client. As an example, here is a snippet of code that will create a dropdown list of items. WARNING Updates should not be performed to the items in the collection while interating as this may change the pagination.

<ul>
<?php
$items = new \TraderInteractive\Api\Collection(
    $apiClient,
    'resourceName',
    array('aFilter' => '5')
);
foreach ($items as $item) {
    echo "<li>{$item['foo']}</li>\n";
}
?>
</ul>

Contributing

If you would like to contribute, please use our build process for any changes and after the build passes, send us a pull request on github!

There is also a docker-based fig configuration that will standup docker containers for the databases, execute the build inside a docker container, and then terminate everything. This is an easy way to build the application:

fig run build

dominionenterprises / tol-api

Maintainers

Details