You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
We welcome you to report [issues](/../../issues) or submit [pull requests](/../../pulls). While the below guidelines are necessary to get code merged, you can
3
+
submit pull requests that do not adhere to them and we will try to take care of them in our spare time. We are a smallish group of developers,
4
+
though, so if you can make sure the build is passing 100%, that would be very useful.
5
+
6
+
We recommend including details of your particular usecase(s) with any issues or pull requests. We love to hear how our libraries are being used
7
+
and we can get things merged in quicker when we understand its expected usage.
8
+
9
+
## Pull Requests
10
+
Code changes should be sent through [GitHub Pull Requests](/../../pulls). Before submitting the pull request, make sure that phpunit reports success
11
+
by running:
12
+
```sh
13
+
./vendor/bin/phpunit
14
+
```
15
+
And there are not coding standard violations by running
16
+
```sh
17
+
./vendor/bin/phpcs
18
+
```
19
+
20
+
## Builds
21
+
Our [Travis build](https://travis-ci.org/traderinteractive/tol-api-php) executes [PHPUnit](http://www.phpunit.de) and uses [Coveralls](https://coveralls.io/) to enforce code coverage.
22
+
While the build does not strictly enforce 100% code coverage, it will not allow coverage to drop below its current percentage.
23
+
[Scrutinizer](https://scrutinizer-ci.com/) is used to ensure code quality and enforce the [coding standard](http://www.php-fig.org/psr/psr-2/).
This is a PHP client for [REST](http://en.wikipedia.org/wiki/Representational_state_transfer) APIs like the TraderOnline APIs.
11
15
12
16
## Requirements
13
17
14
-
This api client requires PHP 5.4 or newer and uses composer to install further PHP dependencies. See the [composer specification](composer.json) for more details. For caching, there are also optional dependencies on mongo (using the 1.3+ PECL extension) and redis (via the Predis library).
18
+
This api client requires PHP 7.0 or newer and uses composer to install further PHP dependencies. See the [composer specification](composer.json) for more details.
15
19
16
-
When contributing, access to a working mongo database for testing is needed. See the [Contribution Guidelines](#Contributing) for more details.
20
+
When contributing, access to a working mongo database for testing is needed. See the [Contribution Guidelines](.github/CONTRIBUTING.md) for more details.
17
21
18
22
## Installation
19
23
20
24
tol-api-php can be installed for use in your project using [composer](http://getcomposer.org).
21
25
22
26
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:
23
27
24
-
```json
25
-
{
26
-
"require": {
27
-
"dominionenterprises/tol-api": "~0.1.0"
28
-
}
29
-
}
28
+
```sh
29
+
composer require traderinteractive/tol-api
30
30
```
31
31
32
32
## Basic Usage
@@ -35,12 +35,13 @@ The basic guzzle client, without caching or automated pagination handling is mos
35
35
36
36
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.
37
37
```php
38
-
$apiAdapter = new \DominionEnterprises\Api\GuzzleAdapter();
Here's an example of instantiating the included mongo cache adapter.
157
-
158
-
Note that it is important to call ensureIndexes() on the mongo cache adapter at least once before using the cache. This can be done when building/deploying the application, manually before release, or on application startup. Without calling this method, the index for expiry won't be set and the responses will never be removed from the collection effectively making all cached objects stay cached forever. **Important**: Calling it every time you use the cache is not recommended because it can be a very expensive call that can cause extreme load on the mongo database.
159
-
160
-
```php
161
-
$cacheAdapter = new \DominionEnterprises\Api\MongoCache(
162
-
$mongoUrl,
163
-
$mongoDbName,
164
-
$mongoCollectionName
165
-
);
166
-
167
-
// This has to be called at least once to set the expiry index.
168
-
// Without this call, the response won't ever expire. This should
169
-
// definitely not be done on every request. It can cause extreme
170
-
// load on the mongo database and should therefore be done
171
-
// sparingly.
172
-
$cacheAdapter->ensureIndexes();
173
-
```
174
-
175
-
And then later, you can use the cache adapter when creating the client and all of the GET requests made using that client will be sent through the cache to check if they exist, and if not, any successful responses from the API that include Expires headers will be cached for future calls.
176
-
177
-
```php
178
-
$cacheAdapter = new \DominionEnterprises\Api\MongoCache(
179
-
$mongoUrl,
180
-
$mongoDbName,
181
-
$mongoCollectionName
182
-
);
183
-
184
-
$apiClient = new \DominionEnterprises\Api\Client(
185
-
$apiAdapter,
186
-
$auth,
187
-
$apiBaseUrl,
188
-
$cacheAdapter
189
-
);
190
-
191
-
// Assuming this doesn't exist in the cache, it will fetch from the
192
-
// API and store the result in the cache.
193
-
$apiClient->index('resourceName');
194
-
195
-
// Because of the above call, the response should already be
196
-
// cached. This will mean that no further requests are being made
197
-
// to the API.
198
-
$apiClient->index('resourceName');
199
-
```
156
+
The library allows for a [PSR-16 SimpleCache](https://www.php-fig.org/psr/psr-16/) implementation.
200
157
201
158
### Collection
202
159
203
160
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.
161
+
**WARNING** Updates should not be performed to the items in the collection while interating as this may change the pagination.
204
162
```php
205
163
<ul>
206
164
<?php
207
-
$items = new \DominionEnterprises\Api\Collection(
165
+
$items = new \TraderInteractive\Api\Collection(
208
166
$apiClient,
209
167
'resourceName',
210
168
array('aFilter' => '5')
@@ -218,10 +176,7 @@ foreach ($items as $item) {
218
176
219
177
## Contributing
220
178
221
-
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! The build requires a running mongo and redis. The URI's to these services can be specified via environment variables or left to their defaults (localhost on the default port):
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!
225
180
226
181
There is also a [docker](http://www.docker.com/)-based [fig](http://www.fig.sh/) 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:
0 commit comments