README

This is the library that simplifies the way how you can communicate with Joystick API.

Requirements

PHP 7.2 and later

Installation

You can install the package via Composer:

composer require getjoystick/joystick-php

We will try to find the PSR-18 compatible HTTP client within your dependencies using php-http/discovery, if you don't have one installed, just run this command to install Guzzle HTTP client:

composer require guzzlehttp/guzzle

Usage

To use the client, use Composer's autoload:

require_once 'vendor/autoload.php';

Simple usage looks like this:

$config = \Joystick\ClientConfig::create()->setApiKey(getenv('JOYSTICK_API_KEY'));

$client = \Joystick\Client::create($config);

$getContentsResponse = $client->getContents(['content-id1', 'content-id2']);

$getContentsResponse->myProperty1
$getContentsResponse->myProperty2

Requesting Content by single Content Id

$getContentResponse = $client->getContent('content-id1');
$getContentResponse->myProperty1

Specifying additional parameters:

When creating the ClientConfig object, you can specify additional parameters which will be used by all API calls from the client, for more details see API documentation:

$config = \Joystick\ClientConfig::create()
    ->setApiKey(getenv('JOYSTICK_API_KEY'))
    ->setCacheExpirationSeconds(600) // 10 mins
    ->setSerialized(true)
    ->setParams([
        'param1' => 'value1',
        'param2' => 'value2',
     ])
     ->setSemVer('0.0.1')
     ->setUserId('user-id-1');

Options

`fullResponse`

In most of the cases you will be not interested in the full response from the API, but if you're you can specify fullResponse option to the client methods. The client will return you raw API response:

$getContentResponse = $client->getContent('content-id1', ['fullResponse' => true]);
// OR
$getContentsResponse = $client->getContents(['content-id1', 'content-id2'], ['fullResponse' => true]);

`serialized`

When true, we will pass query parameter responseType=serialized to Joystick API.

$getContentResponse = $client->getContent('content-id1', ['serialized' => true]);
// OR
$getContentsResponse = $client->getContents(['content-id1', 'content-id2'], ['serialized' => true]);

`refresh`

If you want to ignore existing cache and request the new config – pass this option as true.

$getContentResponse = $client->getContent('content-id1', ['refresh' => true]);
// OR
$getContentsResponse = $client->getContents(['content-id1', 'content-id2'], ['refresh' => true]);

This option can be set for every API call from the client by setting setSerialized(true):

$config = \Joystick\ClientConfig::create()
    ->setApiKey(getenv('JOYSTICK_API_KEY'))
    ->setSerialized(true)

Caching

By default, the client uses array caching, which means that if you build the HTTP application where each process exits after the request has been processed – the cache will be erased after the process is finished.

You can specify your cache implementation which conforms PSR-16.

See examples/file-cache for more details.

Clear the cache

If you want to clear the cache – run $client->clearCache().

Note that we will call clear() on the PSR-16 interface. Make sure that you use different cache instances in different places of your app

HTTP Client

If you want to provide custom HTTP client, which may be useful for use-cases like specifying custom proxy, collecting detailed metrics about HTTP requests,

You can specify your HTTP client implementation which conforms PSR-18.

See examples/custom-http-client for more details.

Testing

To run unit tests, just run:

phpunit

Security

If you discover any security related issues, please email letsgo@getjoystick.com instead of using the issue tracker.

Credits

License

The MIT. Please see License File for more information.

getjoystick / joystick-php

Maintainers

Details