ianfortier / basic-freshsales-api
A basic REST Freshsales API wrapper.
Requires
- php: >=7.1.0
- guzzlehttp/guzzle: ^6.3
- guzzlehttp/promises: ^1.3
- psr/log: ^1.1
This package is auto-updated.
Last update: 2024-04-06 09:34:33 UTC
README
A simple API wrapper for Freshsales using Guzzle. It supports both the REST API provided by Freshsales, and basic rate limiting abilities. Also supported: asynchronous requests through Guzzle's promises.
This library required PHP >= 7.
PS: This project is largely inspired (aka copy <3 ) from osiset/Basic-Shopify-API.
Table of Contents
Installation
The recommended way to install is through composer.
composer require ianfortier/basic-freshsales-api
Usage
Add use ianfortier\BasicFreshsalesAPI;
to your imports.
REST (sync)
For REST calls, the shop domain and access token are required.
$api = new BasicFreshsaleAPI(); // Now run your requests... $resul = $api->rest(...);
REST (async)
For REST calls, the shop domain and access token are required.
$api = new BasicFreshsaleAPI(); // Now run your requests... $promise = $api->restAsync(...); $promise->then(function ($result) { // ... });
Making requests
REST
Requests are made using Guzzle.
$api->rest(string $type, string $path, array $params = null, array $headers = [], bool $sync = true);
type
refers to GET, POST, PUT, DELETE, etcpath
refers to the API path, example:/api/leads
params
refers to an array of params you wish to pass to the path, examples:['email' => 'customer@email.com']
headers
refers to an array of custom headers you would like to optionally send with the request, example:['X-Freshsales-Test' => '123']
sync
refers to if the request should be synchronous or asynchronous.
You can use the alias restAsync
to skip setting sync
to false
.
If sync is true (regular rest call):
The return value for the request will be an object containing:
response
the full Guzzle response objectbody
the JSON decoded response body (array)bodyObject
the JSON decoded response body (stdClass)
Note: request()
will alias to rest()
as well.
If sync is false (restAsync call):
The return value for the request will be a Guzzle promise which you can handle on your own.
The return value for the promise will be an object containing:
response
the full Guzzle response objectbody
the JSON decoded response body (array)bodyObject
the JSON decoded response body (stdClass)
$promise = $api->restAsync(...); $promise->then(function ($result) { // `response` and `body` available in `$result`. });
Passing additional request options
If you'd like to pass additional request options to the Guzzle client created, pass them as the second argument of the constructor.
$api = BasicFreshsaleAPI(true, ['connect_timeout' => 3.0]);
In the above, the array in the second argument will be merged into the Guzzle client created.
Checking API limits
After each request is made, the API call limits are updated. To access them, simply use:
// Returns an array of left, made, and limit. // Example: ['left' => 79, 'made' => 1, 'limit' => 80] $limits = $api->getApiCalls('rest');
Rate Limiting
This library comes with a built-in basic rate limiter, disabled by default. It will sleep for x microseconds to ensure you do not go over the limit for calls with Freshsales.
By default the cycle is set to 500ms, with a buffer for safety of 100ms added on.
Enable Rate Limiting
Setup your API instance as normal, with an added:
$api->enableRateLimiting();
This will turn on rate limiting with the default 500ms cycle and 100ms buffer. To change this, do the following:
$api->enableRateLimiting(0.25 * 1000, 0);
This will set the cycle to 250ms and 0ms buffer.
Disabiling Rate Limiting
If you've previously enabled it, you simply need to run:
$api->disableRateLimiting();
Checking Rate Limiting Status
$api->isRateLimitingEnabled();
Errors
This library internally catches only 400-500 status range errors through Guzzle. You're able to check for an error of this type and get its response status code and body.
$call = $api->rest('GET', '/xxxx/non-existant-route-or-object'); if ($call->errors) { echo "Oops! {$call->status} error"; var_dump($call->body); // Original exception can be accessed via `$call->exception` // Example, if response body was `{"error": "Not found"}`... /// then: `$call->body` would return "Not Found" }
Logging
This library accepts a PSR-compatible logger.
$api->setLogger(... your logger instance ...);
LICENSE
This project is released under the MIT license.