-
Notifications
You must be signed in to change notification settings - Fork 57
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Switched Keen IO PHP SDK to use Guzzle Web Service Client
Added support for: Bulk Loading Parallel Requests Data Analysis methods Service Description and Version of Webservice Client Updated Readme and Unit Tests
- Loading branch information
keith kirk
committed
Oct 15, 2013
1 parent
8f0a735
commit dcf9e24
Showing
13 changed files
with
1,479 additions
and
540 deletions.
There are no files selected for viewing
Empty file.
Empty file.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,50 +1,203 @@ | ||
| Keen IO PHP Library | ||
| =================== | ||
| [](https://travis-ci.org/keenlabs/KeenClient-PHP) [](https://www.versioneye.com/package/php--keen-io--keen-io) | ||
| The Keen IO API lets developers build analytics features directly into their apps. | ||
|
|
||
| This is a library to abstract the Keen IO API addEvent method | ||
| [](https://travis-ci.org/kmfk/KeenClient-PHP.png) | ||
|
|
||
| Installation | ||
| Installation with Composer | ||
| ------------ | ||
| 1. edit `composer.json` file with following contents: | ||
| 1. Install composer via via `curl -s http://getcomposer.org/installer | php` (on windows, download | ||
| http://getcomposer.org/installer and execute it with PHP) | ||
| 1. Edit your `composer.json` file with following contents: | ||
|
|
||
| ```json | ||
| "require": { | ||
| "keen-io/keen-io": "dev-master" | ||
| } | ||
| ``` | ||
| 2. install composer via `curl -s http://getcomposer.org/installer | php` (on windows, download | ||
| http://getcomposer.org/installer and execute it with PHP) | ||
| 3. run `php composer.phar install` | ||
| 3. Run `php composer.phar install` | ||
|
|
||
| Use | ||
| Usage | ||
| --- | ||
| Configure the service | ||
|
|
||
| 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/KeenIO/Resources/config/keen-io-3_0.json). 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 | ||
|
|
||
| The factory method accepts an array of configuration settings for the Keen IO Webservice Client. | ||
|
|
||
| Setting | Property Name | Description | ||
| --- | --- | --- | ||
| Project ID | `projectId` | The Keen IO Project Id for your specific project | ||
| Master API Key | `masterKey` | The Keen IO Master API Key - the one API key to rule them all | ||
| Read API Key | `readKey` | The Read API Key - used for access to read only (GET|HEAD) operations of the API | ||
| Write API Key | `writeKey` | The Write API Key - used for write (PUT|POST Requests) operations of the API | ||
| API Version | `version` | The API Version. Currently used to version the API URL and Service Description | ||
|
|
||
| When 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. | ||
|
|
||
| ######Example | ||
| ```php | ||
| use KeenIO\Client\KeenIOClient; | ||
|
|
||
| $client = KeenIOClient::factory([ | ||
| 'projectId' => $projectId, | ||
| 'writeKey' => $writeKey, | ||
| 'readKey' => $readKey | ||
| ]); | ||
| ``` | ||
|
|
||
| ####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 | ||
| ```php | ||
|
|
||
| //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->getScopedKey( $masterKey, $filters, $allowed_operations ); | ||
| $client->setReadKey( $newReadKey ); | ||
|
|
||
| ``` | ||
|
|
||
| ####Send an event to Keen | ||
| Once you've created a `KeenIOClient`, sending events is simple: | ||
|
|
||
| ######Example | ||
| ```php | ||
| $event = [ 'purchase' => [ 'item' => 'Golden Elephant' ] ]; | ||
|
|
||
| $client->addEvent( [ 'event_collection' => 'purchases', 'data' => $event ] ); | ||
| ``` | ||
|
|
||
| ####Send batched events to Keen | ||
| 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 | ||
| ```php | ||
| $purchases = [ | ||
| [ 'purchase' => [ 'item' => 'Golden Elephant' ] ], | ||
| [ 'purchase' => [ 'item' => 'Magenta Elephant' ] ] | ||
| ]; | ||
| $signUps = [ | ||
| [ 'name' => 'foo', 'email' => '[email protected]' ] | ||
| ]; | ||
|
|
||
| $client->addEvents([ 'data' => [ 'purchases' => $purchases, 'sign_ups' => $signUps ] ]); | ||
| ``` | ||
|
|
||
| ####Send batched events in Parallel | ||
| Useful for large batch processing jobs. The client will serialize each request and send them all in parallel. | ||
|
|
||
| If an error is encountered during the transfer, then a `KeenIO\Exception\CommandTransferException` is thrown, which allows | ||
| you to retrieve a list of commands that succeeded and a list of commands that failed. | ||
|
|
||
| For more information on parallel commands, you can check the [Guzzle docs](http://guzzlephp.org/webservice-client/webservice-client.html#executing-commands-in-parallel). | ||
|
|
||
| ######Example: | ||
| ```php | ||
| use KeenIO\Service\KeenIO; | ||
| // Split the events into chunks | ||
| $eventChunks = array_chunk( $events, 500 ); | ||
|
|
||
| KeenIO::configure($projectId, $writeKey, $readKey); | ||
| $commands = []; | ||
| foreach( $eventChunks as $eventChunk ) | ||
| { | ||
| // Using getCommand will create the command with out immediately executing it | ||
| // versus using the magic methods | ||
| $commands[] = $this->getCommand( "sendEvents", [ 'data' => [ 'purchases' => $eventChunk ] ] ); | ||
| } | ||
|
|
||
| try | ||
| { | ||
| // The commands can then be passed to the client's execute method to be run | ||
| // in parallel | ||
| $result = $this->execute( $commands ); | ||
| } | ||
| catch( \KeenIO\Exception\CommandTransferException $e ) | ||
| { | ||
| // Handle any errored commands... | ||
| $failedCommands = $e->getFailedCommands(); | ||
| } | ||
| ``` | ||
|
|
||
| Send a new event | ||
| ####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/KeenIO/Resources/config/keen-io-3_0.json) for configured API Endpoints. | ||
|
|
||
| Below are a few example calls to some of the Analysis methods available. | ||
|
|
||
| ######Example | ||
| ```php | ||
| KeenIO::addEvent('purchases', array( | ||
| 'purchase' => array( | ||
| 'item' => 'Golden Elephant' | ||
| ), | ||
| )); | ||
|
|
||
| //Count | ||
| $totalPurchases = $client->count([ 'event_collection' => 'purchases' ]); | ||
|
|
||
| //Count Unqiue | ||
| $totalItems = $client->countUnique([ | ||
| 'event_collection' => 'purchases', | ||
| 'target_property' => 'purchase.item' | ||
| ]); | ||
|
|
||
| //Select Unique | ||
| $items = $client->selectUnique([ | ||
| 'event_collection' => 'purchases', | ||
| 'target_property' => 'purchase.item' | ||
| ]); | ||
|
|
||
| //Multi Analysis | ||
| $analyses = [ | ||
| 'clicks' => [ "analysis_type" => "count" ], | ||
| 'average price' => [ "analysis_type" => "average", "target_property" => "purchase.price" ] | ||
| ]; | ||
| $stats = $client->multiAnalysis([ 'event_collection' => 'purchases', 'analyses' => $analyses ]); | ||
| ``` | ||
|
|
||
| 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 | ||
| ```php | ||
| $filter = array( | ||
| 'property_name' => 'id', | ||
| 'operator' => 'eq', | ||
| 'property_value' => '123' | ||
| ); | ||
| $filters = array($filter); | ||
| $allowed_operations = array('read'); | ||
|
|
||
| $scopedKey = KeenIO::getScopedKey('master api key', $filters, $allowed_operations); | ||
| $filter = [ | ||
| 'property_name' => 'user_id', | ||
| 'operator' => 'eq', | ||
| 'property_value' => '123' | ||
| ]; | ||
|
|
||
| $filters = [ $filter ]; | ||
| $allowed_operations = [ 'read' ]; | ||
|
|
||
| $scopedKey = $client->getScopedKey( $masterKey, $filters, $allowed_operations ); | ||
| ``` | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,31 +1,36 @@ | ||
| { | ||
| "name": "keen-io/keen-io", | ||
| "description": "A PHP library for reporting events to the Keen IO API", | ||
| "type": "library", | ||
| "license": "MIT", | ||
| "keywords": [ | ||
| "keen io", | ||
| "analytics" | ||
| ], | ||
| "require": { | ||
| "php": ">=5.3.3", | ||
| "ext-mcrypt": "*", | ||
| "zendframework/zend-http": ">=2.2" | ||
| }, | ||
| { | ||
| "name": "keen-io/keen-io", | ||
| "description": "A PHP library for reporting events to the Keen IO API", | ||
| "type": "library", | ||
| "license": "MIT", | ||
| "keywords": [ | ||
| "keen io", | ||
| "analytics" | ||
| ], | ||
| "require": { | ||
| "php": ">=5.3.3", | ||
| "ext-mcrypt": "*", | ||
| "guzzle/guzzle": "~3.7" | ||
| }, | ||
| "require-dev": { | ||
| "phpunit/phpunit": "*" | ||
| }, | ||
| "homepage": "http://keen.io", | ||
| "authors": [ | ||
| { | ||
| "name": "Tom Anderson", | ||
| "email": "[email protected]", | ||
| "homepage": "http://www.soliantconsulting.com" | ||
| } | ||
| ], | ||
| "autoload": { | ||
| "psr-0": { | ||
| "KeenIO": "src/" | ||
| } | ||
| } | ||
| } | ||
| "homepage": "http://keen.io", | ||
| "authors": [ | ||
| { | ||
| "name": "Tom Anderson", | ||
| "email": "[email protected]", | ||
| "homepage": "http://www.soliantconsulting.com" | ||
| }, | ||
| { | ||
| "name": "Keith Kirk", | ||
| "email": "[email protected]", | ||
| "homepage": "http://undergroundelephant.com" | ||
| } | ||
| ], | ||
| "autoload": { | ||
| "psr-0": { | ||
| "KeenIO": "src/" | ||
| } | ||
| } | ||
| } |
Empty file.
Oops, something went wrong.