1 <?php
2 /**
3 * @package Joomla.Platform
4 * @subpackage Twitter
5 *
6 * @copyright Copyright (C) 2005 - 2017 Open Source Matters, Inc. All rights reserved.
7 * @license GNU General Public License version 2 or later; see LICENSE
8 */
9
10 defined('JPATH_PLATFORM') or die();
11
12 /**
13 * Twitter API Users class for the Joomla Platform.
14 *
15 * @since 12.3
16 * @deprecated 4.0 Use the `joomla/twitter` package via Composer instead
17 */
18 class JTwitterUsers extends JTwitterObject
19 {
20 /**
21 * Method to get up to 100 users worth of extended information, specified by either ID, screen name, or combination of the two.
22 *
23 * @param string $screen_name A comma separated list of screen names, up to 100 are allowed in a single request.
24 * @param string $id A comma separated list of user IDs, up to 100 are allowed in a single request.
25 * @param boolean $entities When set to either true, t or 1, each tweet will include a node called "entities,". This node offers a variety of
26 * metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags.
27 *
28 * @return array The decoded JSON response
29 *
30 * @since 12.3
31 * @throws RuntimeException
32 */
33 public function getUsersLookup($screen_name = null, $id = null, $entities = null)
34 {
35 // Check the rate limit for remaining hits
36 $this->checkRateLimit('users', 'lookup');
37
38 // Set user IDs and screen names.
39 if ($id)
40 {
41 $data['user_id'] = $id;
42 }
43
44 if ($screen_name)
45 {
46 $data['screen_name'] = $screen_name;
47 }
48
49 if ($id == null && $screen_name == null)
50 {
51 // We don't have a valid entry
52 throw new RuntimeException('You must specify either a comma separated list of screen names, user IDs, or a combination of the two');
53 }
54
55 // Set the API path
56 $path = '/users/lookup.json';
57
58 // Check if string_ids is specified
59 if (!is_null($entities))
60 {
61 $data['include_entities'] = $entities;
62 }
63
64 // Send the request.
65 return $this->sendRequest($path, 'POST', $data);
66 }
67
68 /**
69 * Method to access the profile banner in various sizes for the user with the indicated screen_name.
70 *
71 * @param mixed $user Either an integer containing the user ID or a string containing the screen name.
72 *
73 * @return array The decoded JSON response
74 *
75 * @since 12.3
76 */
77 public function getUserProfileBanner($user)
78 {
79 // Check the rate limit for remaining hits
80 $this->checkRateLimit('users', 'profile_banner');
81
82 // Set the API path
83 $path = '/users/profile_banner.json';
84
85 // Determine which type of data was passed for $user
86 if (is_numeric($user))
87 {
88 $data['user_id'] = $user;
89 }
90 elseif (is_string($user))
91 {
92 $data['screen_name'] = $user;
93 }
94 else
95 {
96 // We don't have a valid entry
97 throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
98 }
99
100 // Send the request.
101 return $this->sendRequest($path, 'GET', $data);
102 }
103
104 /**
105 * Method used to search for users
106 *
107 * @param string $query The search query to run against people search.
108 * @param integer $page Specifies the page of results to retrieve.
109 * @param integer $count The number of people to retrieve. Maximum of 20 allowed per page.
110 * @param boolean $entities When set to either true, t or 1, each tweet will include a node called "entities,". This node offers a
111 * variety of metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags.
112 *
113 * @return array The decoded JSON response
114 *
115 * @since 12.3
116 * @throws RuntimeException
117 */
118 public function searchUsers($query, $page = 0, $count = 0, $entities = null)
119 {
120 // Check the rate limit for remaining hits
121 $this->checkRateLimit('users', 'search');
122
123 $data['q'] = rawurlencode($query);
124
125 // Check if page is specified.
126 if ($page > 0)
127 {
128 $data['page'] = $page;
129 }
130
131 // Check if per_page is specified
132 if ($count > 0)
133 {
134 $data['count'] = $count;
135 }
136
137 // Check if entities is specified.
138 if (!is_null($entities))
139 {
140 $data['include_entities'] = $entities;
141 }
142
143 // Set the API path
144 $path = '/users/search.json';
145
146 // Send the request.
147 return $this->sendRequest($path, 'GET', $data);
148 }
149
150 /**
151 * Method to get extended information of a given user, specified by ID or screen name as per the required id parameter.
152 *
153 * @param mixed $user Either an integer containing the user ID or a string containing the screen name.
154 * @param boolean $entities Set to true to return IDs as strings, false to return as integers.
155 *
156 * @return array The decoded JSON response
157 *
158 * @since 12.3
159 * @throws RuntimeException
160 */
161 public function getUser($user, $entities = null)
162 {
163 // Check the rate limit for remaining hits
164 $this->checkRateLimit('users', 'show/:id');
165
166 // Determine which type of data was passed for $user
167 if (is_numeric($user))
168 {
169 $data['user_id'] = $user;
170 }
171 elseif (is_string($user))
172 {
173 $data['screen_name'] = $user;
174 }
175 else
176 {
177 // We don't have a valid entry
178 throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
179 }
180
181 // Set the API path
182 $path = '/users/show.json';
183
184 // Check if entities is specified
185 if (!is_null($entities))
186 {
187 $data['include_entities'] = $entities;
188 }
189
190 // Send the request.
191 return $this->sendRequest($path, 'GET', $data);
192 }
193
194 /**
195 * Method to get an array of users that the specified user can contribute to.
196 *
197 * @param mixed $user Either an integer containing the user ID or a string containing the screen name.
198 * @param boolean $entities Set to true to return IDs as strings, false to return as integers.
199 * @param boolean $skip_status When set to either true, t or 1 statuses will not be included in the returned user objects.
200 *
201 * @return array The decoded JSON response
202 *
203 * @since 12.3
204 * @throws RuntimeException
205 */
206 public function getContributees($user, $entities = null, $skip_status = null)
207 {
208 // Check the rate limit for remaining hits
209 $this->checkRateLimit('users', 'contributees');
210
211 // Determine which type of data was passed for $user
212 if (is_numeric($user))
213 {
214 $data['user_id'] = $user;
215 }
216 elseif (is_string($user))
217 {
218 $data['screen_name'] = $user;
219 }
220 else
221 {
222 // We don't have a valid entry
223 throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
224 }
225
226 // Set the API path
227 $path = '/users/contributees.json';
228
229 // Check if entities is specified
230 if (!is_null($entities))
231 {
232 $data['include_entities'] = $entities;
233 }
234
235 // Check if skip_status is specified
236 if (!is_null($skip_status))
237 {
238 $data['skip_status'] = $skip_status;
239 }
240
241 // Send the request.
242 return $this->sendRequest($path, 'GET', $data);
243 }
244
245 /**
246 * Method to get an array of users who can contribute to the specified account.
247 *
248 * @param mixed $user Either an integer containing the user ID or a string containing the screen name.
249 * @param boolean $entities Set to true to return IDs as strings, false to return as integers.
250 * @param boolean $skip_status When set to either true, t or 1 statuses will not be included in the returned user objects.
251 *
252 * @return array The decoded JSON response
253 *
254 * @since 12.3
255 * @throws RuntimeException
256 */
257 public function getContributors($user, $entities = null, $skip_status = null)
258 {
259 // Check the rate limit for remaining hits
260 $this->checkRateLimit('users', 'contributors');
261
262 // Determine which type of data was passed for $user
263 if (is_numeric($user))
264 {
265 $data['user_id'] = $user;
266 }
267 elseif (is_string($user))
268 {
269 $data['screen_name'] = $user;
270 }
271 else
272 {
273 // We don't have a valid entry
274 throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
275 }
276
277 // Set the API path
278 $path = '/users/contributors.json';
279
280 // Check if entities is specified
281 if (!is_null($entities))
282 {
283 $data['include_entities'] = $entities;
284 }
285
286 // Check if skip_status is specified
287 if (!is_null($skip_status))
288 {
289 $data['skip_status'] = $skip_status;
290 }
291
292 // Send the request.
293 return $this->sendRequest($path, 'GET', $data);
294 }
295
296 /**
297 * Method access to Twitter's suggested user list.
298 *
299 * @param boolean $lang Restricts the suggested categories to the requested language.
300 *
301 * @return array The decoded JSON response
302 *
303 * @since 12.3
304 */
305 public function getSuggestions($lang = null)
306 {
307 // Check the rate limit for remaining hits
308 $this->checkRateLimit('users', 'suggestions');
309
310 // Set the API path
311 $path = '/users/suggestions.json';
312
313 $data = array();
314
315 // Check if entities is true
316 if ($lang)
317 {
318 $data['lang'] = $lang;
319 }
320
321 // Send the request.
322 return $this->sendRequest($path, 'GET', $data);
323 }
324
325 /**
326 * method to access the users in a given category of the Twitter suggested user list.
327 *
328 * @param string $slug The short name of list or a category.
329 * @param boolean $lang Restricts the suggested categories to the requested language.
330 *
331 * @return array The decoded JSON response
332 *
333 * @since 12.3
334 */
335 public function getSuggestionsSlug($slug, $lang = null)
336 {
337 // Check the rate limit for remaining hits
338 $this->checkRateLimit('users', 'suggestions/:slug');
339
340 // Set the API path
341 $path = '/users/suggestions/' . $slug . '.json';
342
343 $data = array();
344
345 // Check if entities is true
346 if ($lang)
347 {
348 $data['lang'] = $lang;
349 }
350
351 // Send the request.
352 return $this->sendRequest($path, 'GET', $data);
353 }
354
355 /**
356 * Method to access the users in a given category of the Twitter suggested user list and return
357 * their most recent status if they are not a protected user.
358 *
359 * @param string $slug The short name of list or a category.
360 *
361 * @return array The decoded JSON response
362 *
363 * @since 12.3
364 */
365 public function getSuggestionsSlugMembers($slug)
366 {
367 // Check the rate limit for remaining hits
368 $this->checkRateLimit('users', 'suggestions/:slug/members');
369
370 // Set the API path
371 $path = '/users/suggestions/' . $slug . '/members.json';
372
373 // Send the request.
374 return $this->sendRequest($path);
375 }
376 }
377