Support service token (#15)

* added service token support

* fix failing test cases

* README update

* minor edits

* README edits

* added secure env variables for .travis.yml

* revert to original params defined way

* README edits

* new authrep, tests and readme

* add changelog.md

* support tuple service token and service id in same function

* [poc] send tuple as array

* added class for tuple

* readme edits

* fix test cases

* minor edits per mikz comments

* revert travis changes

* added changed section

* update release version

Author: Vinay Bhalerao

.travis.yml

@@ -1,10 +1,11 @@
 language: php
 php:
-#  - 5.2 # does not have  DateTime::getTimestamp()
-  - 5.3
-  - 5.4
-before_script:
- - export TEST_3SCALE_APP_KEYS=3e05c797ef193fee452b1ddf19defa74
- - export TEST_3SCALE_APP_IDS=75165984
- - export TEST_3SCALE_PROVIDER_KEY=05273bcb282d1d4faafffeb01e224db0
+- 5.3
+- 5.4
+env:
+  global:
+  - TEST_3SCALE_APP_IDS=4d4b20b9 TEST_3SCALE_APP_KEYS=ecce202ecc2eb8dc7a499c34a34d5987
+  - secure: "N4m/jyamokMvS7IuUjDzzexp6hExqFx2b7TZfFsKKBUVvbmdt0OuE/lgh68pFiFgAWNUwqhU8f7QmE6Snz8adqndgw+gaPVbOmLmFSt4/MUW7VjIgRvINZjKJQ6Rw18NjJ3eAl91XxtDK3kkD9pKbcV6Vb7uR1g0khNGxbSdTlI="
+  - secure: "BaSNNNJC62aLH9b1xrOryLDZBtiWLvUcOjKA9pXQq6u1wvUNBMr6cQHwV7MQZTHlxAhGh+fahC9c6VInVVp7SyH4gcMI2Feq2CkAHBIFN4umBZC5rVVAgjM48UOg+qp5cYyyKzUhvFqAhAgmKh0dvoB+hLrY0qfKQ4sufSRTmUk="
+  - secure: "myAM1Jeqrm2AuOiz96g/3KgQtqAxdWNn/0JuTGyKU2bdORtTthrfWZ7L+Sx6NP1e/GsioJ9iuqp0Q4aEvoJ6JtQLJhAXeRSovnuNRvaVnPqAsI/E2530laQOuGw8qgVLr7Kq1BkfoIF2Hc7J74yu7+Tyog+uSA+hpIyadHbFem8="
 script: php test/all.php

CHANGELOG.md

@@ -0,0 +1,11 @@
+# Change Log
+All notable changes to this project will be documented in this file.
+
+##[2.7.0] - 2017-02-16
+### Added
+- Added support for (Service Tokens)[https://support.3scale.net/docs/accounts/tokens]
+
+### Changed
+- The signature for `authrep` method has been changed from `authrep($appId, $appKey = null, $usage = null, $userId = null, $object = null, $no_body = null, $serviceId = null)` to `authrep($appId, $appKey = null, $credentials_or_service_id, $usage = null, $userId = null, $object = null, $no_body = null)`
+- The signature for 'authrep_with_user_key' method has been changed from `authrep_with_user_key($userKey, $usage = null, $userId = null, $object = null, $no_body = null, $serviceId = null)` to `authrep_with_user_key($userKey, $credentials_or_service_id, $usage = null, $userId = null, $object = null, $no_body = null)`
+

README.markdown

@@ -1,6 +1,11 @@
-# Client for 3scale web service management system API [![Build Status](https://secure.travis-ci.org/3scale/3scale_ws_api_for_php.png?branch=master)](http://travis-ci.org/3scale/3scale_ws_api_for_php)
+# Client for 3scale Web Service Management API [![Build Status](https://secure.travis-ci.org/3scale/3scale_ws_api_for_php.png?branch=master)](http://travis-ci.org/3scale/3scale_ws_api_for_php)
 3scale integration plugin for PHP applications. 3scale is an API Infrastructure service which handles API Keys, Rate Limiting, Analytics, Billing Payments and Developer Management. Includes a configurable API dashboard and developer portal CMS. More product stuff at http://www.3scale.net/, support information at http://support.3scale.net/.
 
+### Tutorials
+* Plugin Setup: https://support.3scale.net/docs/deployment-options/plugin-setup
+* Rate Limiting: https://support.3scale.net/docs/access-control/rate-limits
+* Analytics Setup: https://support.3scale.net/quickstarts/3scale-api-analytics
+
 ## Installation
 
 Download the source code from github: http://github.com/3scale/3scale_ws_api_for_php and place it somewhere accessible from your project.
@@ -10,106 +15,182 @@ Download the source code from github: http://github.com/3scale/3scale_ws_api_for
 Require the ThreeScaleClient.php file (assuming you placed the library somewhere within the
 include path):
 
-    require_once('lib/ThreeScaleClient.php')
+```php
+require_once('lib/ThreeScaleClient.php')
+```
 
-Then, create an instance of the client, giving it your provider API key:
+Then create an instance of the client
+```php
+$client = new ThreeScaleClient();
+```
 
-    $client = new ThreeScaleClient("your provider key");
+> NOTE: unless you specify ```ThreeScaleClient();``` you will be expected to specify
+a `provider_key` parameter, which is deprecated in favor of Service Tokens:
+```php
+$client = new ThreeScaleClient("your provider key");
+```
 
 Because the object is stateless, you can create just one and store it globally.
 
-**NOTE: From November 2016 `service_id` is mandatory.**
+Then you can perform calls in the client:
+
+```php
+$response = $client->authorize("app id", "app key", new ThreeScaleClientCredentials("service id", "service token"));
+```
+
+```php
+$response = $client->report(array(array('app_id' => "app's id"],'usage' => array('hits' => 1))), new ThreeScaleClientCredentials("service id", "service token"));
+```
+
+**NOTE:`service_id` is mandatory since November 2016, both when using service tokens and when using provider keys**
 
 ### Authorize
 
 To authorize a particular application, call the `authorize` method passing it the 
-application id and optionally the application key:
+`application id` and `service id` and optionally the application key:
+
+```php
+$response = $client->authorize("app id", "app key", new ThreeScaleClientCredentials("service id", "service token"));
+```
+
+If you had configured a (deprecated) provider key, you would instead use:
 
-    $response = $client->authorize("the app id", "the app key");
-or 
-    $response = $client->authorize("the app id", "the app key", "the service id");
+```php
+$response = $client->authorize("the app id", "the app key", "service id"));
+```
 
 Then call the `isSuccess()` method on the returned object to see if the authorization was
 successful:
 
-    if ($response->isSuccess()) {
-      // All fine, proceeed.
-    } else {
-      // Something's wrong with this app.
-    }
+```php
+if ($response->isSuccess()) {
+  // All fine, proceeed.
+} else {
+  // Something's wrong with this app.
+}
+```
 
 If both provider and app id are valid, the response object contains additional information about the status of the application:
 
-    // Returns the name of the plan the application is signed up to.
-    $response->getPlan()
+```php
+//Returns the name of the plan the application is signed up to.
+$response->getPlan()
+```
 
 If the plan has defined usage limits, the response contains details about the usage broken down by the metrics and usage limit periods.
 
-    // The usageReports array contains one element per each usage limit defined on the plan.
-    $usageReports = $response->getUsageReports();
-    $usageReport  = $usageReports[0];
+```php
+// The usageReports array contains one element per each usage limit defined on the plan.
+$usageReports = $response->getUsageReports();
+$usageReport  = $usageReports[0];
 
-    // The metric
-    $usageReport->getMetric() // "hits"
+// The metric
+$usageReport->getMetric() // "hits"
 
-    // The period the limit applies to
-    $usageReport->getPeriod()       // "day"
-    $usageReport->getPeriodStart()  // 1272405600 (Unix timestamp for April 28, 2010, 00:00:00)
-    $usageReport->getPeriodEnd()    // 1272492000 (Unix timestamp for April 29, 2010, 00:00:00)
+// The period the limit applies to
+$usageReport->getPeriod()       // "day"
+$usageReport->getPeriodStart()  // 1272405600 (Unix timestamp for April 28, 2010, 00:00:00)
+$usageReport->getPeriodEnd()    // 1272492000 (Unix timestamp for April 29, 2010, 00:00:00)
 
-    // The current value the application already consumed in the period
-    $usageReport->getCurrentValue() // 8032
+// The current value the application already consumed in the period
+$usageReport->getCurrentValue() // 8032
 
-    // The maximal value allowed by the limit in the period
-    $usageReport->getMaxValue()     // 10000
-  
-    // If the limit is exceeded, this will be true, otherwise false:
-    $usageReport->isExceeded()      // false
+// The maximal value allowed by the limit in the period
+$usageReport->getMaxValue()     // 10000
+
+// If the limit is exceeded, this will be true, otherwise false:
+$usageReport->isExceeded()      // false
+```
 
 If the authorization failed, the `getErrorCode()` returns system error code and `getErrorMessage()` human readable error description:
 
-    $response->getErrorCode()       // "usage_limits_exceeded"
-    $response->getErrorMessage()    // "Usage limits are exceeded"
+```php    
+$response->getErrorCode()       // "usage_limits_exceeded"
+$response->getErrorMessage()    // "Usage limits are exceeded"
+```
+
+### Authrep
+
+To authorize a particular application, call the `authrep` method passing it the 
+`application id` and `service id` and optionally the application key:
+
+```php
+$response = $client->authrep("app id", "app key", new ThreeScaleClientCredentials("service id", "service token"), array('hits' => 1));
+```
+
+Then call the `isSuccess()` method on the returned object to see if the authorization was
+successful:
+
+```php
+if ($response->isSuccess()) {
+  // All fine, proceeed.
+} else {
+  // Something's wrong with this app.
+}
+```
+
+If both provider and app id are valid, the response object contains additional information about the status of the application:
+
+```php
+//Returns the name of the plan the application is signed up to.
+$response->getPlan()
+```
+
+You can also use other patterns such as `user_key` mode during the authrep call
+
+```php
+$response = $client->authrep_with_user_key("app id", "app key", new ThreeScaleClientCredentials("service id", "service token"), array('hits' => 1));
+```
 
 ### Report
 
 To report usage, use the `report` method. You can report multiple transaction at the same time:
 
-    $response = $client->report(array(
-      array('app_id' => "first app's id",  'usage' => array('hits' => 1)),
-      array('app_id' => "second app's id", 'usage' => array('hits' => 1))), "service id");
+```php    
+$response = $client->report(array(
+      array('app_id' => "first app's id",'usage' => array('hits' => 1)),
+      array('app_id' => "second app's id", 'usage' => array('hits' => 1))), new ThreeScaleClientCredentials("service id", "service token"));
+```
 
-The `"app_id"` and `"usage"` parameters are required. Additionaly, you can specify a timestamp
+The `"app_id"`,  `"usage"` parameters are required alongiwth `service id` and `service token`. Additionaly, you can specify a timestamp
 of the transaction:
 
-    $response = $client->report(array(
-      array('app_id'    => "app's id",
-            'usage'     => array('hits' => 1),
-            'timestamp' => mktime(12, 36, 0, 4, 28, 2010))));
+```php
+$response = $client->report(array(
+  array('app_id'    => "app's id",
+        'usage'     => array('hits' => 1),
+        'timestamp' => mktime(12, 36, 0, 4, 28, 2010, new ThreeScaleClientCredentials("service id", "service token")));
+```
 
 The timestamp can be either an unix timestamp (as integer) or a string. The string has to be in a
 format parseable by the [strtotime](http://php.net/manual/en/function.strtotime.php) function.
 For example:
 
-    "2010-04-28 12:38:33 +0200"
+```php    
+"2010-04-28 12:38:33 +0200"
+```
 
 If the timestamp is not in UTC, you have to specify a time offset. That's the "+0200" 
 (two hours ahead of the Universal Coordinate Time) in the example above.
 
 Then call the `isSuccess()` method on the returned response object to see if the report was
 successful:
 
-    if ($response->isSuccess()) {
-      // All OK.
-    } else {
-      // There was an error.
-    }
+```php    
+if ($response->isSuccess()) {
+  // All OK.
+} else {
+  // There was an error.
+}
+```
 
 In case of error, the `getErrorCode()` returns system error code and `getErrorMessage()`
 human readable error description:
 
-    $response->getErrorCode()    // "provider_key_invalid"
-    $response->getErrorMessage() // "provider key \"foo\" is invalid"
+```php    
+$response->getErrorCode()    // "provider_key_invalid"
+$response->getErrorMessage() // "provider key \"foo\" is invalid"
+```
 
 ## Plugin integration
 
@@ -119,6 +200,10 @@ If you are interested in integrating the plugin with:
 
 * [Symphony2](http://symfony.com/) check [tonivdv's 3scaleBundle](https://github.com/tonivdv/3scaleBundle). This is kindly maintained by [Adlogix](http://www.adlogix.eu) tech team.
 
+## To Test
+
+To run tests: `php test/all.php`
+
 ## Legal
 
 Copyright (c) 2010 3scale networks S.L., released under the MIT license.