PHPackages                             keen-io/keen-io - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. keen-io/keen-io

ActiveLibrary[API Development](/categories/api)

keen-io/keen-io
===============

A PHP library for reporting events to the Keen IO API

v2.9.0(1y ago)1332.3M↓26.8%55[9 issues](https://github.com/keenlabs/KeenClient-PHP/issues)[2 PRs](https://github.com/keenlabs/KeenClient-PHP/pulls)7MITPHPPHP >=5.6.0

Since Sep 4Pushed 1y ago39 watchersCompare

[ Source](https://github.com/keenlabs/KeenClient-PHP)[ Packagist](https://packagist.org/packages/keen-io/keen-io)[ Docs](http://keen.io)[ RSS](/packages/keen-io-keen-io/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (6)Versions (35)Used By (7)

Keen IO PHP Library
===================

[](#keen-io-php-library)

The Keen IO API lets developers build analytics features directly into their apps.

[![Build Status](https://camo.githubusercontent.com/fe84a39b1d1a28863f5d1cf545b811783b58cd13fe6cd2d8c7656500ac629a91/68747470733a2f2f7472617669732d63692e6f72672f6b65656e6c6162732f4b65656e436c69656e742d5048502e706e673f6272616e63683d6d6173746572)](https://travis-ci.org/keenlabs/KeenClient-PHP)

Installation with Composer
--------------------------

[](#installation-with-composer)

```
$ php composer.phar require keen-io/keen-io:~2.5
```

For composer documentation, please refer to [getcomposer.org](http://getcomposer.org/).

Integrated Frameworks
---------------------

[](#integrated-frameworks)

For easier usage the following community developed integrations are also available:

- [Zend Framework 2](https://github.com/keenlabs/KeenClient-PHP-ZF2)
- [Symfony2 Framework](https://github.com/keenlabs/KeenClient-PHP-SF2)
- [Laravel 5](https://github.com/garethtdavies/keen-io-laravel)

Changes
-------

[](#changes)

Please review the change log ( [CHANGE.md](CHANGE.md) ) before upgrading!

Usage
-----

[](#usage)

This client was built using [Guzzle](http://guzzlephp.org/), a PHP HTTP client & framework for building RESTful web service clients.

When you first create a new `KeenIOClient` instance you can pass configuration settings like your Project ID and API Keys in an array to the factory method. These are optional and can be later specified through Setter methods.

For certain API Resources, the Master API Key is required and can also be passed to the factory method in the configuration array. Please read the [Security Documentation](https://keen.io/docs/security/) regarding this Master API key.

For Requests, the `KeenIOClient` will determine what API Key should be passed based on the type of Request and configuration in the [Service Description](/src/Client/Resources/keen-io-3_0.php). The API Key is passed in the `Authorization` header of the request.

For a list of required and available parameters for the different API Endpoints, please consult the Keen IO [API Reference Docs](https://keen.io/docs/api/reference/).

#### Configuring the Client

[](#configuring-the-client)

The factory method accepts an array of configuration settings for the Keen IO Webservice Client.

SettingProperty NameDescriptionProject ID`projectId`The Keen IO Project ID for your specific projectMaster API Key`masterKey`The Keen IO Master API Key - the one API key to rule them allRead API Key`readKey`The Read API Key - used for access to read only GET or HEAD operations of the APIWrite API Key`writeKey`The Write API Key - used for write PUT or POST Requests operations of the APIAPI Version`version`The API Version. Currently used to version the API URL and Service DescriptionWhen passing `version` to the factory method or using the `setVersion()` method, the Client will try to load a client Service Description that matches that version. That Service Description defines the operations available to the Webservice Client.

Currently the Keen IO Webservice Client only supports - and automatically defaults - to the current version (`3.0`) of the API.

##### More details about the client

[](#more-details-about-the-client)

Since the Keen client extends the [Guzzle](http://guzzlephp.org/) client, you get all the power and flexibility of that behind the scenes. If you need more complex logging, backoff/retry handling, or asynchronous requests, check out their [Plugins](http://guzzle3.readthedocs.io/docs.html#plugins).

###### Example

[](#example)

```
use KeenIO\Client\KeenIOClient;

$client = KeenIOClient::factory([
    'projectId' => $projectId,
    'writeKey'  => $writeKey,
    'readKey'   => $readKey
]);
```

For more options see [Guzzle Client documentation](http://docs.guzzlephp.org/en/stable/quickstart.html#creating-a-client)Please notice that *all other options passed to the constructor are used as default request options with every request created by the client*.

#### Configuration can be updated to reuse the same Client:

[](#configuration-can-be-updated-to-reuse-the-same-client)

You can reconfigure the Keen IO Client configuration options through available getters and setters. You can get and set the following options: `projectId`, `readKey`, `writeKey`, `masterKey`, & `version`.

###### Example

[](#example-1)

```
//Get the current Project Id
$client->getProjectId();

//Set a new Project Id
$client->setProjectId($someNewProjectId);

//Get the current Read Key
$client->getReadKey();

//Set a new Read Key
$newReadKey = $client->createScopedKey($filters, $allowedOperations);
$client->setReadKey($newReadKey);
```

#### Send an event to Keen - ([Changed in 2.0!](CHANGE.md))

[](#send-an-event-to-keen---changed-in-20)

Once you've created a `KeenIOClient`, sending events is simple:

###### Example

[](#example-2)

```
$event = ['purchase' => ['item' => 'Golden Elephant']];

$client->addEvent('purchases', $event);
```

#### Data Enrichment

[](#data-enrichment)

A data enrichment is a powerful add-on to enrich the data you're already streaming to Keen IO by pre-processing the data and adding helpful data properties. To activate add-ons, you simply add some new properties within the "keen" namespace in your events. Detailed documentation for the configuration of our add-ons is available [here](https://keen.io/docs/api/?php#data-enrichment).

Here is an example of using the [URL parser](https://keen.io/docs/streams/url-enrichment/):

```
$client->addEvent('requests', [
    'page_url' => 'http://my-website.com/cool/link?source=twitter&foo=bar/#title',
    'keen' => [
        'addons' => [
            [
                'name' => 'keen:url_parser',
                'input' => [
                    'url' => 'page_url'
                ],
                'output' => 'parsed_page_url'
            ]
        ]
    ]
]);
```

Keen IO will parse the URL for you and that would equivalent to:

```
$client->addEvent('requests', [
    'page_url' => 'http://my-website.com/cool/link?source=twitter&foo=bar/#title',
    'parsed_page_url' => [
        'protocol' => 'http',
        'domain' => 'my-website.com',
        'path' => '/cool/link',
        'anchor' => 'title',
        'query_string' => [
            'source' => 'twitter',
            'foo' => 'bar'
        ]
    ]
]);
```

Here is another example of using the [Datetime parser](https://keen.io/docs/streams/datetime-enrichment/). Let's assume you want to do a deeper analysis on the "purchases" event by day of the week (Monday, Tuesday, Wednesday, etc.) and other interesting Datetime components. You can use "keen.timestamp" property that is included in your event automatically.

```
$client->addEvent('purchases', [
    'keen' => [
        'addons' => [
            [
                'name' => 'keen:date_time_parser',
                'input' => [
                    'date_time' => 'keen.timestamp'
                ],
                'output' => 'timestamp_info'
            ]
        ]
    ],
    'price' => 500
]);
```

Other Data Enrichment add-ons are located in the [API reference docs](https://keen.io/docs/api/?php#data-enrichment).

#### Send batched events to Keen - ([Changed in 2.0!](CHANGE.md))

[](#send-batched-events-to-keen----changed-in-20)

You can upload multiple Events to multiple Event Collections at once!

In the example below, we will create two new purchase events in the `purchases` event collection and a single new event in the `sign_ups` event collection. Note that the keys of the `data` array specify the `event_collection`where those events should be stored.

###### Example

[](#example-3)

```
$purchases = [
    ['purchase' => ['item' => 'Golden Elephant']],
    ['purchase' => ['item' => 'Magenta Elephant']]
];
$signUps = [
    ['name' => 'foo', 'email' => 'bar@baz.com']
];

$client->addEvents(['purchases' => $purchases, 'sign_ups' => $signUps]);
```

#### Get Analysis on Events

[](#get-analysis-on-events)

All Analysis Endpoints should be supported. See the [API Reference Docs](https://keen.io/docs/api/reference/) for required parameters. You can also check the [Service Description](/src/Client/Resources/keen-io-3_0.php) for configured API Endpoints.

Below are a few example calls to some of the Analysis methods available.

Note: Once the API acknowledges that your event has been stored, it may take up to 10 seconds before it will appear in query results.

###### Example

[](#example-4)

```
//Count
$totalPurchases = $client->count('purchases', ['timeframe' => 'this_14_days']);

//Count Unqiue
$totalItems = $client->countUnique('purchases', ['target_property' => 'purchase.item', 'timeframe' => 'this_14_days']);

//Select Unique
$items = $client->selectUnique('purchases', ['target_property' => 'purchase.item', 'timeframe' => 'this_14_days']);

//Multi Analysis
$analyses = [
    'clicks'        => ['analysis_type' => 'count'],
    'average price' => ['analysis_type' => 'average', 'target_property' => 'purchase.price'],
    'timeframe'     => 'this_14_days'
];
$stats = $client->multiAnalysis('purchases', ['analyses' => $analyses]);

//Using Filters in your Analysis
$filters = [
    ['property_name' => 'item.price', 'operator' => 'gt', 'property_value' => 10]
];

$client->count('purchases', ['filters' => $filters, 'timeframe' => 'this_14_days']);
```

#### Create a Scoped Key

[](#create-a-scoped-key)

Scoped keys allow you to secure the requests to the API Endpoints and are especially useful when you are providing access to multiple clients or applications. You should read the Keen IO docs concerning [Scoped Keys](https://keen.io/docs/security/#scoped-key)for more details.

###### Example

[](#example-5)

```
$filter = [
    'property_name'  => 'user_id',
    'operator'       => 'eq',
    'property_value' => '123'
];

$filters = [$filter];
$allowedOperations = ['read'];

$scopedKey = $client->createScopedKey($filters, $allowedOperations);
```

#### Using saved queries

[](#using-saved-queries)

[Saved Queries](https://keen.io/docs/api/?php#saved-queries) allow you to perform with exactly the same parameters every time with minimal effort. It's effectively a bookmark or macro to analysis that you can jump to or share without configuring each time. While you can create and access them via the Dashboard, the PHP library gives you the same ability.

###### Example: Creating a Saved Query

[](#example-creating-a-saved-query)

```
$client = KeenIOClient::factory([
    'projectId' => $project_id,
    'masterKey' => $master_key
]);

$query = [
    "analysis_type" => "count",
    "event_collection" => "api_requests",
    "filters" =>
        [
            [
                "property_name" => "user_agent",
                "operator" => "ne",
                "property_value"=> "Pingdom.com_bot_version_1.4_(http://www.pingdom.com/)"
            ]
        ],
    "timeframe" => "this_2_weeks"
];

$results = $client->createSavedQuery(['query_name' => 'total-API-requests', 'query' => $query]);
```

###### Example: Retrieving a Saved Query

[](#example-retrieving-a-saved-query)

```
$client = KeenIOClient::factory([
    'projectId' => $project_id,
    'masterKey' => $master_key
]);

$results = $client->getSavedQuery(['query_name' => 'total-API-requests']);
```

#### Using Cached queries

[](#using-cached-queries)

By [Caching a Query](https://keen.io/docs/api/?php#creating-a-cached-query), you are adding a `refresh_rate` property to a query payload.

Cached Queries helps you to automatically refresh a saved query within a particular time. This allows you to get an immediate result using the saved query for a subsequent trip.

You can either cache a query while [creating a saved query](https://keen.io/docs/api/#creating-a-saved-query) or [updating a saved query](https://keen.io/docs/api/#updating-saved-queries).

While you can create this via the Dashboard, the PHP library gives you the same ability.

###### Example: Caching a query when creating Saved Query

[](#example-caching-a-query-when-creating-saved-query)

```
$client = KeenIOClient::factory([
    'projectId' => $project_id,
    'masterKey' => $master_key
]);

$query = [
    "analysis_type" => "count",
    "event_collection" => "api_requests",
    "filters" =>
        [
            [
                "property_name" => "user_agent",
                "operator" => "ne",
                "property_value"=> "Pingdom.com_bot_version_1.4_(http://www.pingdom.com/)"
            ]
        ],
    "timeframe" => "this_2_weeks",
    "refresh_rate" => 14400

];

$client->createSavedQuery(['query_name' => 'total-API-requests', 'query' => $query]);
```

###### Example: Caching a query when updating a saved Query

[](#example-caching-a-query-when-updating-a-saved-query)

```
$client = KeenIOClient::factory([
    'projectId' => $project_id,
    'masterKey' => $master_key
]);

$query = [
    "analysis_type" => "count",
    "event_collection" => "api_requests",
    "filters" =>
        [
            [
                "property_name" => "user_agent",
                "operator" => "ne",
                "property_value"=> "Pingdom.com_bot_version_1.4_(http://www.pingdom.com/)"
            ]
        ],
    "timeframe" => "this_2_weeks",
    "refresh_rate" => 14400

];

$results = $client->updateSavedQuery(['query_name' => 'total-API-requests', 'query' => $query]);
```

###### Example: Retrieving a Cached Query

[](#example-retrieving-a-cached-query)

```
$client = KeenIOClient::factory([
    'projectId' => $project_id,
    'masterKey' => $master_key
]);

$results = $client->getSavedQuery(['query_name' => 'total-API-requests']);
```

Troubleshooting
---------------

[](#troubleshooting)

When your client sends a request that the API rejects with an HTTP 400 BAD REQUEST or similar error, it is translated to an exception. You might inspect this exception object's getMessage() method, like this:

```
try {
  $client->addEvent( "php-events" , ['broken.purchase' => ['item' => 'Golden Elephant', 'amount' => 42.50]] );
} catch( Exception $e ) {
  print $e->getMessage();
}
```

This won't give you much in the way of useful details, though:

```
Client error response
[status code] 400
[reason phrase] Bad Request
[url] ...

```

Instead, use the getResponse() method, which will give you the entire HTTP response:

```
try {
  $client->addEvent( "php-events" , ['broken.purchase' => ['item' => 'Golden Elephant', 'amount' => 42.50]] );
} catch( Exception $e ) {
  print $e->getResponse();
}
```

```
HTTP/1.1 400 Bad Request
... headers ...

{"message": "Property name is invalid. Must be