Consume the ThisData.com REST API using this client. Requires at least PHP5.5.

Using composer:

composer require thisdata/api

Use the factory to return an instance of ThisData\Api\ThisData, configured with default settings.

use ThisData\Api\ThisData;

$apiKey = '<API_KEY>';

$thisData = ThisData::create($apiKey);

⚠️ Don't commit your API key to source control! Use an environment variable, or perhaps you have a configuration solution that allows you to store secrets in local configuration without being shared.

Each endpoint will have different methods, depending on the functionality the endpoint provides. For instance, the events endpoint can track successful login attempts.

Documentation for API endpoints can be found here:

• POST Events
• POST Verify
• GET Events

Use the $thisData instance to get an instance of the events endpoint.

$endpoint = $thisData->getEventsEndpoint();

Then track events:

$ip = $_SERVER['REMOTE_ADDR'];
$user = [
    'id' => 'johntitor',
    'name' => 'John Titor',
    'email' => '[email protected]',
    'mobile' => '+64270000001'
];
$userAgent = $_SERVER['HTTP_USER_AGENT'];

$endpoint->trackLogIn($ip, $user, $userAgent);

$verb = 'my-custom-verb';
$endpoint->trackEvent($verb, $ip, $user, $userAgent);

When the login attempt is unsuccessful:

$ip = $_SERVER['REMOTE_ADDR'];
$user = [
    'id' => 'johntitor',
    'authenticated' => false
];
$userAgent = $_SERVER['HTTP_USER_AGENT'];
$endpoint->trackEvent(EventsEndpoint::VERB_LOG_IN_DENIED, $ip, $user, $userAgent);

When you're using a multi-tenanted app:

$ip = $_SERVER['REMOTE_ADDR'];
$user = [
    'id' => 'johntitor'
];
$userAgent = $_SERVER['HTTP_USER_AGENT'];
$source = [
    'name' => 'SubCustomer 1'
]
$endpoint->trackLogIn($ip, $user, $userAgent, $source);

When a sensitive action is about to occur, perhaps before finalizing the log-in process, you can verify that the user is who they say they are, and check the risk that their account is being impersonated by an attacker. If they present a medium or high risk, force them to provide a two-factor authentication code.

$endpoint = $thisData->getVerifyEndpoint();

$ip = $_SERVER['REMOTE_ADDR'];
$user = [
    'id' => 'johntitor'
];
$userAgent = $_SERVER['HTTP_USER_AGENT'];

$response = $endpoint->verify($ip, $user, $userAgent);

if ($response['risk_level'] != "green") {
    # Ask for Two Factor Authentication code
} else {
    # Everything is OK
}

You can fetch a paginated, filterable array of Events from the API. The method accepts any of the parameters described in the documentation: http://help.thisdata.com/docs/v1getevents

e.g. returning the 10 most recent log-in events for a user

$endpoint = $thisData->getEventsEndpoint();
$events = $endpoint->getEvents(["verb" => "log-in", "user_id" => 112233, "limit" => 10]);

There are several configuration options that modify the way the library behaves. By using the Builder you can set these configuration options.

use ThisData\Api\Builder;
$builder = new Builder($apiKey);

// Configure the builder here. See below for more details.
// ...
// e.g. $builder->setAsync(false);
// $builder->setExpectJsCookie(true);
// ...

$thisData = $builder->build();

By default, requests are sent to the server asynchronously. If this is not required, or synchronous communication is preferred, configure your builder to use synchronous requests.

$builder->setAsync(false);

ThisData's Javascript tracking code is optional, but when included in a page will add a cookie called __tdli. If you're using the optional javascript library, this library will automatically pick up that cookie. You should also tell the API that each request should come with a cookie:

$builder->setExpectJsCookie(true);

If you require more control of your network settings, such as using a proxy, configure the client settings when building.

$builder->setClientOption('proxy', 'tcp://localhost:8125');

If you want to see the verbose output of the HTTP request, enable debug mode in Guzzle.

$builder->setClientOption('debug', true);

All settings supported by the Guzzle HTTP Client can be configured here, including curl options.

If you require access to directly interact with the Guzzle HTTP client to send custom requests, the configured instance can be retrieved from an endpoint.

/** @var GuzzleHttp\Client $guzzle */
$guzzle = $events->getClient();

Alternatively, you can instantiate the client manually, without the added endpoint abstration layers.

$client = new ThisData\Api\Client('<API_KEY>'); // An extension of the GuzzleHttp\Client class
$client->post('events', ['body' => '{"ip":"127.0.0.1"}']);

Thanks for helping! Start by forking the repository. Then make sure the tests pass:

composer install
./vendor/bin/phpunit

Make your changes, add test coverage, and check the tests are still passing. Then open a PR! :)