Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 125 lines (81 sloc) 5.005 kb
16d13eb @mikz updated readme
mikz authored
1 # 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)
2 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/.
ac1011c @madadam Updates documentation
madadam authored
3
4 ## Installation
5
2ad8a9b Adding a disclaimer to contact support before using v2.0
Tiago Macedo authored
6 Download the source code from github: http://github.com/3scale/3scale_ws_api_for_php and place it somewhere accessible from your project.
ac1011c @madadam Updates documentation
madadam authored
7
8 ## Usage
9
10 Require the ThreeScaleClient.php file (assuming you placed the library somewhere within the
11 include path):
12
13 require_once('lib/ThreeScaleClient.php')
14
15 Then, create an instance of the client, giving it your provider API key:
16
17 $client = new ThreeScaleClient("your provider key");
18
19 Because the object is stateless, you can create just one and store it globally.
20
21 ### Authorize
22
3985428 @madadam More changes to confirm to the new API version
madadam authored
23 To authorize a particular application, call the `authorize` method passing it the
24 application id and optionally the application key:
ac1011c @madadam Updates documentation
madadam authored
25
3985428 @madadam More changes to confirm to the new API version
madadam authored
26 $response = $client->authorize("the app id", "the app key");
ac1011c @madadam Updates documentation
madadam authored
27
28 Then call the `isSuccess()` method on the returned object to see if the authorization was
29 successful:
30
31 if ($response->isSuccess()) {
32 // All fine, proceeed.
33 } else {
3985428 @madadam More changes to confirm to the new API version
madadam authored
34 // Something's wrong with this app.
ac1011c @madadam Updates documentation
madadam authored
35 }
36
3985428 @madadam More changes to confirm to the new API version
madadam authored
37 If both provider and app id are valid, the response object contains additional information
38 about the status of the application:
ac1011c @madadam Updates documentation
madadam authored
39
3985428 @madadam More changes to confirm to the new API version
madadam authored
40 // Returns the name of the plan the application is signed up to.
ac1011c @madadam Updates documentation
madadam authored
41 $response->getPlan()
42
3f5731c @madadam Changes to conform to the new API version
madadam authored
43 If the plan has defined usage limits, the response contains details about the usage broken
44 down by the metrics and usage limit periods.
ac1011c @madadam Updates documentation
madadam authored
45
3f5731c @madadam Changes to conform to the new API version
madadam authored
46 // The usageReports array contains one element per each usage limit defined on the plan.
47 $usageReports = $response->getUsageReports();
48 $usageReport = $usageReports[0];
ac1011c @madadam Updates documentation
madadam authored
49
50 // The metric
3f5731c @madadam Changes to conform to the new API version
madadam authored
51 $usageReport->getMetric() // "hits"
ac1011c @madadam Updates documentation
madadam authored
52
53 // The period the limit applies to
3f5731c @madadam Changes to conform to the new API version
madadam authored
54 $usageReport->getPeriod() // "day"
55 $usageReport->getPeriodStart() // 1272405600 (Unix timestamp for April 28, 2010, 00:00:00)
56 $usageReport->getPeriodEnd() // 1272492000 (Unix timestamp for April 29, 2010, 00:00:00)
ac1011c @madadam Updates documentation
madadam authored
57
3985428 @madadam More changes to confirm to the new API version
madadam authored
58 // The current value the application already consumed in the period
3f5731c @madadam Changes to conform to the new API version
madadam authored
59 $usageReport->getCurrentValue() // 8032
ac1011c @madadam Updates documentation
madadam authored
60
61 // The maximal value allowed by the limit in the period
3f5731c @madadam Changes to conform to the new API version
madadam authored
62 $usageReport->getMaxValue() // 10000
63
64 // If the limit is exceeded, this will be true, otherwise false:
65 $usageReport->isExceeded() // false
ac1011c @madadam Updates documentation
madadam authored
66
3f5731c @madadam Changes to conform to the new API version
madadam authored
67 If the authorization failed, the `getErrorCode()` returns system error code and
68 `getErrorMessage()` human readable error description:
69
70 $response->getErrorCode() // "usage_limits_exceeded"
71 $response->getErrorMessage() // "Usage limits are exceeded"
ac1011c @madadam Updates documentation
madadam authored
72
73 ### Report
74
75 To report usage, use the `report` method. You can report multiple transaction at the same time:
76
77 $response = $client->report(array(
3985428 @madadam More changes to confirm to the new API version
madadam authored
78 array('app_id' => "first app's id", 'usage' => array('hits' => 1)),
79 array('app_id' => "second app's id", 'usage' => array('hits' => 1))));
ac1011c @madadam Updates documentation
madadam authored
80
3985428 @madadam More changes to confirm to the new API version
madadam authored
81 The `"app_id"` and `"usage"` parameters are required. Additionaly, you can specify a timestamp
ac1011c @madadam Updates documentation
madadam authored
82 of the transaction:
83
84 $response = $client->report(array(
3985428 @madadam More changes to confirm to the new API version
madadam authored
85 array('app_id' => "app's id",
ac1011c @madadam Updates documentation
madadam authored
86 'usage' => array('hits' => 1),
87 'timestamp' => mktime(12, 36, 0, 4, 28, 2010))));
88
89 The timestamp can be either an unix timestamp (as integer) or a string. The string has to be in a
90 format parseable by the [strtotime](http://php.net/manual/en/function.strtotime.php) function.
91 For example:
92
3f5731c @madadam Changes to conform to the new API version
madadam authored
93 "2010-04-28 12:38:33 +0200"
ac1011c @madadam Updates documentation
madadam authored
94
3f5731c @madadam Changes to conform to the new API version
madadam authored
95 If the timestamp is not in UTC, you have to specify a time offset. That's the "+0200"
ac1011c @madadam Updates documentation
madadam authored
96 (two hours ahead of the Universal Coordinate Time) in the example above.
97
98 Then call the `isSuccess()` method on the returned response object to see if the report was
99 successful:
100
101 if ($response->isSuccess()) {
3f5731c @madadam Changes to conform to the new API version
madadam authored
102 // All OK.
ac1011c @madadam Updates documentation
madadam authored
103 } else {
3f5731c @madadam Changes to conform to the new API version
madadam authored
104 // There was an error.
ac1011c @madadam Updates documentation
madadam authored
105 }
106
3f5731c @madadam Changes to conform to the new API version
madadam authored
107 In case of error, the `getErrorCode()` returns system error code and `getErrorMessage()`
108 human readable error description:
109
110 $response->getErrorCode() // "provider_key_invalid"
111 $response->getErrorMessage() // "provider key \"foo\" is invalid"
ac1011c @madadam Updates documentation
madadam authored
112
8e2b785 @joahking giving credit to Adlogix for it's symphony2 bundler
joahking authored
113 ## Plugin integration
d01f808 @joahking README updated with integration with Composer
joahking authored
114
8e2b785 @joahking giving credit to Adlogix for it's symphony2 bundler
joahking authored
115 If you are interested in integrating the plugin with:
116
117 * [Composer](http://getcomposer.org/) check [the packagist](https://packagist.org/packages/tdaws/3scale_ws_api_for_php). This is kindly maintained by [daws.ca](http://daws.ca) tech team.
118
119 * [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.
d01f808 @joahking README updated with integration with Composer
joahking authored
120
ac1011c @madadam Updates documentation
madadam authored
121 ## Legal
122
123 Copyright (c) 2010 3scale networks S.L., released under the MIT license.
124
Something went wrong with that request. Please try again.