forked from gsomoza/KulerPHP
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Api.php
285 lines (254 loc) · 10.1 KB
/
Api.php
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
<?php
/**
* Kuler API library for PHP
*
* @author Gabriel Somoza (me@gabrielsomoza.com)
* @link http://gabrielsomoza.com
* @version 0.1.1
* @category Kuler
* @package PHP Kuler API Library
* @link http://learn.adobe.com/wiki/display/kulerdev/B.+Feeds
*
* @copyright Copyright (c) 2011-2012, Gabriel Somoza
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation; either version 2
* of the License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, see <http://www.gnu.org/licenses/>.
*
*/
define('KULER_PATH', realpath(dirname(__FILE__)));
require_once KULER_PATH . '/Theme.php';
require_once KULER_PATH . '/Comment.php';
require_once KULER_PATH . '/Exception.php';
class Kuler_Api {
/**
* The API base url
*/
const URL_BASE = 'http://kuler-api.adobe.com/';
/**
* Get RSS Feeds
*/
const URL_GET = 'rss/get.cfm?';
/**
* Search RSS Feeds
*/
const URL_SEARCH = 'rss/search.cfm?';
/**
* Comments RSS Feeds
*/
const URL_COMMENTS = 'rss/comments.cfm?';
/**
* Theme Thumbnail Generator
*/
const URL_THUMBNAIL = 'rss/png/generateThemePng.cfm?';
/**
* Theme View URL (for the public website)
*/
const URL_VIEW = '#themeID/';
/**
*
* @var type
*/
protected $key;
/**
* Stores the raw response
* @var SimpleXMLElement
*/
protected $response;
/**
* Allowed listTypes for the 'Get' RSS
* @var Array
*/
protected $listTypes;
/**
* Initializes the Kuler object
* @param string $key Your Kuler API Key
*/
public function __construct($key) {
if (!isset($key) || empty($key))
throw new Kuler_Exception('Please provide an API key to use Kuler');
$this->key = $key;
$this->listTypes = array('recent', 'popular', 'rating', 'random');
}
/**
* Returns a list of feeds of a specified type.
*
* @param string $type One of the strings 'recent' (the default), 'popular', 'rating', or 'random'.
* @param int $startIndex A 0-based index into the list that specifies the first item to display. Default is 0, which displays the first item in the list.
* @param int $itemsPerPage The maximum number of items to display on a page, in the range 1..100. Default is 20.
* @param int $timeSpan Value in days to limit the set of themes retrieved. Default is 0, which retrieves all themes without time limit.
* @return Array An array of KulerItem objects.
*/
public function get($type = 'recent', $startIndex = 0, $itemsPerPage = 20, $timeSpan = 0) {
if (!in_array($type, $this->listTypes))
throw new Kuler_Exception('Invalid List Type: ' . $type);
$params = array_filter(array(
'listType' => $type,
'startIndex' => (int) $startIndex,
'itemsPerPage' => (int) $itemsPerPage,
'timeSpan' => (int) $timeSpan,
));
$this->request(self::URL_GET, $params);
return $this->getItems();
}
/**
* Returns a list of feeds that meet specified search criteria.
*
* @param type $query A search filter. This can be one of the predefined filters listed below, or a simple string term to
* search on; for example, "blue". If you specify a simple term, the search looks for that term in
* theme titles, tags, author names, themeIDs, authorIDs, and hexValues. By default, retrieves all
* available feeds.<br/><br/>
* These filters are available:
* <ul><li>themeID - search on a specific themeID</li>
* <li>userID - search on a specific userID</li>
* <li>email - search on a specific email</li>
* <li>tag - search on a tag word</li>
* <li>hex - search on a hex color value (can be in
* the format "ABCDEF" or "0xABCDEF")</li>
* <li>title - search on a theme title</li></ul>
* @param int $startIndex A 0-based index into the list that specifies the first item to display. Default is 0, which displays the first item in the list.
* @param int $itemsPerPage The maximum number of items to display on a page, in the range 1..100. Default is 20.
* @return Array An array of KulerItem objects.
*
* <b>Example usage:</b>
* <code>
* $kuler->search('email:me@gabrielsomoza.com')
* </code>
*/
public function search($query = '', $startIndex = 0, $itemsPerPage = 20) {
$params = array_filter(array(
'searchQuery' => (string) $query,
'startIndex' => (int) $startIndex,
'itemsPerPage' => (int) $itemsPerPage,
));
$this->request(self::URL_SEARCH, $params);
return $this->getItems();
}
/**
* Returns a list of comments for either a specified theme (if a themeID is
* provided) or for all of a member's themes (if an email is provided).
*
* @param int $themeID When this value is used, all comments are retrieved for the specified theme.
* @param string $email When this value is used, comments are retrieved for themes created by this user
* @param int $startIndex A 0-based index into the list that specifies the first item to display. Default is 0, which displays the first item in the list.
* @param int $itemsPerPage The maximum number of items to display on a page, in the range 1..100. Default is 20.
* @return Array An array of KulerItem objects.
*/
public function comments($themeID = null, $email = null, $startIndex = 0, $itemsPerPage = 20) {
$params = array_filter(array(
'themeID' => (int) $themeID,
'email' => (string) $email,
'startIndex' => (int) $startIndex,
'itemsPerPage' => (int) $itemsPerPage,
));
$this->request(self::URL_COMMENTS, $params);
return $this->getComments();
}
/**
* Retrieves a thumbnail of a specific theme.
*
* @param int $themeID The id of a specified theme.
* @return string The URL of the Theme's thumbnail.
*/
public static function generateThemePng($themeID) {
if (!is_numeric($themeID))
throw new Kuler_Exception('Invalid Theme ID');
$params = array(
'themeid' => (int) $themeID,
'key' => $this->key,
);
return self::buildUrl(self::URL_THUMBNAIL, $params);
}
/**
* A better alias for generateThemePng()
* @see Kuler::generateThemePng()
*/
public static function getThemeThumbnail($themeID) {
return self::generateThemePng($themeID);
}
/**
* Generates the URL used to view a specific theme directly in the kuler public website.
*
* @param int $themeID The id of a specified theme.
* @return string The Theme's public URL
*/
public static function viewThemeUrl($themeID) {
if (!is_numeric($themeID))
throw new Kuler_Exception('Invalid Theme ID');
return self::buildUrl(self::URL_VIEW, (string) $themeID);
}
/**
* A better alias for viewThemeUrl()
* @see Kuler::viewThemeUrl()
*/
public static function getThemeUrl($themeId) {
return self::viewThemeUrl($themeID);
}
/**
* Retrieves data from the Kuler API
*
* @param string $endpoint The API endpoint to query against.
* @param Array $params Parameters that will be parsed by http_build_query and appended to the URL.
* @uses http_build_query()
* @uses SimpleXmlElement
* @see self::URL_* constants
* @return SimpleXmlElement The XML response parsed into a SimpleXmlElement.
*/
protected function request($endpoint, $params) {
if (isset($params['itemsPerPage']) && ($params['itemsPerPage'] > 100 || $params['itemsPerPage'] < 1))
throw new Kuler_Exception('The number of items per page must be between 1 and 100.');
$params = array_merge(array(
'key' => $this->key,
), $params);
try {
$this->response = new SimpleXmlElement(self::buildUrl($endpoint, $params), NULL, true);
} catch (Exception $e) {
throw new Kuler_Exception('Error retrieving the feed: ' . $e->getMessage());
}
return $this->response;
}
/**
* Public accessor to the response element.
* @return SimpleXmlElement
*/
public function getResponse() {
return $this->response;
}
/**
* Builds a URL to communicate with the Kuler API.
*
* @param string $endpoint The API endpoint to query against.
* @param string|Array $params Parameters that will be parsed by http_build_query and appended to the URL.
* @return string The resulting URL
*/
protected static function buildUrl($endpoint, $params) {
if (is_array($params))
$params = http_build_query($params);
$requestUrl = self::URL_BASE . $endpoint;
return $requestUrl . $params;
}
protected function getComments() {
return array_map(array($this, 'createComment'), $this->getXmlItems());
}
protected function createComment($xmlItem) {
return new Kuler_Comment($xmlItem);
}
protected function getItems() {
return array_map(array($this, 'createItem'), $this->getXmlItems());
}
protected function createItem($xmlItem) {
return new Kuler_Theme($xmlItem);
}
protected function getXmlItems() {
return $this->getResponse()->channel->xpath('item');
}
}