3scale-labs / 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/.

Client for 3scale Web Service Management API

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.

Usage

Require the ThreeScaleClient.php file (assuming you placed the library somewhere within the include path):

require_once('lib/ThreeScaleClient.php')

Then create an instance of the client

$client = new ThreeScaleClient();

NOTE: unless you specify ThreeScaleClient(); you will be expected to specify a provider_key parameter, which is deprecated in favor of Service Tokens:

$client = new ThreeScaleClient("your provider key");

Because the object is stateless, you can create just one and store it globally.

Then you can perform calls in the client:

$response = $client->authorize("app id", "app key", new ThreeScaleClientCredentials("service id", "service token"));

$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 service id and optionally the application key:

$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", "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.
}

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()

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];

// 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 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

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"

Authrep

To authorize a particular application, call the authrep method passing it the application id and service id and optionally the application key:

$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:

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()

You can also use other patterns such as user_key mode during the authrep call

$response = $client->authrep_with_user_key("user_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))), new ThreeScaleClientCredentials("service id", "service token"));

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, 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 function. For example:

"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.
}

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"

Custom backend for the 3scale Service Management API

The default URI used for the 3scale Service Management API is http://su1.3scale.net:80. This value can be changed, which is useful when the plugin is used together with the on-premise version of the Red Hat 3scale API Management Platform.

In order to override the URL, pass the custom URI while creating instance an instance of the client

$client = new ThreeScaleClient(null, "http://custom-backend.example.com:8080");

Plugin integration

If you are interested in integrating the plugin with:

• Composer check the packagist. This is kindly maintained by daws.ca tech team.

• Symphony2 check tonivdv's 3scaleBundle. This is kindly maintained by Adlogix tech team.

To Test

To run tests: php test/all.php

Legal

Copyright (c) 2010 3scale networks S.L., released under the MIT license.

3scale_ws_api_for_php's Issues

Syntax error on example authorize and report

Hello,

in the line 26 of file examples/authorize_and_report.php there is a lack of semicolon that breaks the compilation of file.

Best,
Albert

Make it possible to set a custom $host

It should fallback to DEFAULT_ROOT_ENDPOINT but needs to be overridable when initializing client

https://github.com/3scale/3scale_ws_api_for_php/blob/master/lib/ThreeScaleClient.php#L24

service_id required

From November 2016 service_id is mandatory. The code would need to be reviewed to support the use of service_id (it should be optional to avoid breaking change).

Contact Anthony Daws to tag a stable version in packagist

Hello,

I can't find any way to contact @tdaws in order to ask him to tag a stable version.

The thing is that I'de like to use https://github.com/tonivdv/3scaleBundle through composer with the minimum-stability setting set to 'stable', but that is not possible as long as https://github.com/tdaws/3scale_ws_api_for_php has no stable version.

Hope with github notifications, or maybe you guys can help me send this request.

Thx in advance

Cheers

Allow backend host and Port configurable

The default_host = "su1.3scale.net".
To work with on-prem version, the host and the port would need to be configurable.

Add client header

Add the following client header:
X-3scale-User-Agent plugin-php-v{version_number}

Unable to set '#' on the Reporting metrics

For the Reporting API, as seen in the docs, I should be able to pass in '#' with the value in the usage array as below. Instead the PHP SDK encodes '#' into %23 and the call fails.

'usage' => array(
'myMetric' => '#25',
)

incomplete

this client is incomplete and since all of the internal methods are private instead of protected it is not possible to extend it properly.

currently missing the express signup method and I am ending up building a own ThreeScale Client/ duplicating existing code.

Custom backend and port

Set the custom backend while creating the instance of client or performing calls in the client but not from code https://github.com/3scale/3scale_ws_api_for_php/blob/master/lib/ThreeScaleClient.php#L24

service_token should be supported along with provider_key

The plugin would need to be updated to support service_token along with provider_key.

OAuth authrep call missing from client

As reported in THREESCALE-904, the OAuth authrep function is not part of the plugin yet. To avoid having to do 2 separate calls it's necessary to add this function. cc @shannon

authrep_with_user_key metric usage vs report metric usage

Hello,

I have a very small issue with reporting metric usages ...

When I call

$response = $client->authrep_with_user_key('key',  array("some_method_id" => 1));

And the given method id doesn't exist, then it will fail on:

$response->isSuccess()

But if I report the usages through the 'report' method then the isSuccess does not fail but I do get an error in the 3scale error monitoring web console:

$response = $client->authrep_with_user_key('key');

$reportResponse = $client->report(
    array(
         array('user_key' => 'key', 'usage' => array('some_method_id' => 1)),
    )
  );

$reportResponse->isSuccess()

Is there a reason that the behaviour is different? Or is it a bug?

Cheers