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 Friends 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 JTwitterFriends extends JTwitterObject
19 {
20 /**
21 * Method to get an array of user IDs the specified user follows.
22 *
23 * @param mixed $user Either an integer containing the user ID or a string containing the screen name.
24 * @param integer $cursor Causes the list of connections to be broken into pages of no more than 5000 IDs at a time.
25 * The number of IDs returned is not guaranteed to be 5000 as suspended users are filtered out
26 * after connections are queried. If no cursor is provided, a value of -1 will be assumed, which is the first "page."
27 * @param boolean $string_ids Set to true to return IDs as strings, false to return as integers.
28 * @param integer $count Specifies the number of IDs attempt retrieval of, up to a maximum of 5,000 per distinct request.
29 *
30 * @return array The decoded JSON response
31 *
32 * @since 12.3
33 * @throws RuntimeException
34 */
35 public function getFriendIds($user, $cursor = null, $string_ids = null, $count = 0)
36 {
37 // Check the rate limit for remaining hits
38 $this->checkRateLimit('friends', 'ids');
39
40 // Determine which type of data was passed for $user
41 if (is_numeric($user))
42 {
43 $data['user_id'] = $user;
44 }
45 elseif (is_string($user))
46 {
47 $data['screen_name'] = $user;
48 }
49 else
50 {
51 // We don't have a valid entry
52 throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
53 }
54
55 // Check if cursor is specified
56 if (!is_null($cursor))
57 {
58 $data['cursor'] = $cursor;
59 }
60
61 // Check if string_ids is true
62 if ($string_ids)
63 {
64 $data['stringify_ids'] = $string_ids;
65 }
66
67 // Check if count is specified
68 if ($count > 0)
69 {
70 $data['count'] = $count;
71 }
72
73 // Set the API path
74 $path = '/friends/ids.json';
75
76 // Send the request.
77 return $this->sendRequest($path, 'GET', $data);
78 }
79
80 /**
81 * Method to display detailed friend information between two users.
82 *
83 * @param mixed $user_a Either an integer containing the user ID or a string containing the screen name of the first user.
84 * @param mixed $user_b Either an integer containing the user ID or a string containing the screen name of the second user.
85 *
86 * @return array The decoded JSON response
87 *
88 * @since 12.3
89 * @throws RuntimeException
90 */
91 public function getFriendshipDetails($user_a, $user_b)
92 {
93 // Check the rate limit for remaining hits
94 $this->checkRateLimit('friendships', 'show');
95
96 // Determine which type of data was passed for $user_a
97 if (is_numeric($user_a))
98 {
99 $data['source_id'] = $user_a;
100 }
101 elseif (is_string($user_a))
102 {
103 $data['source_screen_name'] = $user_a;
104 }
105 else
106 {
107 // We don't have a valid entry
108 throw new RuntimeException('The first specified username is not in the correct format; must use integer or string');
109 }
110
111 // Determine which type of data was passed for $user_b
112 if (is_numeric($user_b))
113 {
114 $data['target_id'] = $user_b;
115 }
116 elseif (is_string($user_b))
117 {
118 $data['target_screen_name'] = $user_b;
119 }
120 else
121 {
122 // We don't have a valid entry
123 throw new RuntimeException('The second specified username is not in the correct format; must use integer or string');
124 }
125
126 // Set the API path
127 $path = '/friendships/show.json';
128
129 // Send the request.
130 return $this->sendRequest($path, 'GET', $data);
131 }
132
133 /**
134 * Method to get an array of user IDs the specified user is followed by.
135 *
136 * @param mixed $user Either an integer containing the user ID or a string containing the screen name.
137 * @param integer $cursor Causes the list of IDs to be broken into pages of no more than 5000 IDs at a time. The number of IDs returned
138 * is not guaranteed to be 5000 as suspended users are filtered out after connections are queried. If no cursor
139 * is provided, a value of -1 will be assumed, which is the first "page."
140 * @param boolean $string_ids Set to true to return IDs as strings, false to return as integers.
141 * @param integer $count Specifies the number of IDs attempt retrieval of, up to a maximum of 5,000 per distinct request.
142 *
143 * @return array The decoded JSON response
144 *
145 * @since 12.3
146 * @throws RuntimeException
147 */
148 public function getFollowerIds($user, $cursor = null, $string_ids = null, $count = 0)
149 {
150 // Check the rate limit for remaining hits
151 $this->checkRateLimit('followers', 'ids');
152
153 // Determine which type of data was passed for $user
154 if (is_numeric($user))
155 {
156 $data['user_id'] = $user;
157 }
158 elseif (is_string($user))
159 {
160 $data['screen_name'] = $user;
161 }
162 else
163 {
164 // We don't have a valid entry
165 throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
166 }
167
168 // Set the API path
169 $path = '/followers/ids.json';
170
171 // Check if cursor is specified
172 if (!is_null($cursor))
173 {
174 $data['cursor'] = $cursor;
175 }
176
177 // Check if string_ids is specified
178 if (!is_null($string_ids))
179 {
180 $data['stringify_ids'] = $string_ids;
181 }
182
183 // Check if count is specified
184 if (!is_null($count))
185 {
186 $data['count'] = $count;
187 }
188
189 // Send the request.
190 return $this->sendRequest($path, 'GET', $data);
191 }
192
193 /**
194 * Method to determine pending requests to follow the authenticating user.
195 *
196 * @param integer $cursor Causes the list of IDs to be broken into pages of no more than 5000 IDs at a time. The number of IDs returned
197 * is not guaranteed to be 5000 as suspended users are filtered out after connections are queried. If no cursor
198 * is provided, a value of -1 will be assumed, which is the first "page."
199 * @param boolean $string_ids Set to true to return IDs as strings, false to return as integers.
200 *
201 * @return array The decoded JSON response
202 *
203 * @since 12.3
204 */
205 public function getFriendshipsIncoming($cursor = null, $string_ids = null)
206 {
207 // Check the rate limit for remaining hits
208 $this->checkRateLimit('friendships', 'incoming');
209
210 $data = array();
211
212 // Check if cursor is specified
213 if (!is_null($cursor))
214 {
215 $data['cursor'] = $cursor;
216 }
217
218 // Check if string_ids is specified
219 if (!is_null($string_ids))
220 {
221 $data['stringify_ids'] = $string_ids;
222 }
223
224 // Set the API path
225 $path = '/friendships/incoming.json';
226
227 // Send the request.
228 return $this->sendRequest($path, 'GET', $data);
229 }
230
231 /**
232 * Method to determine every protected user for whom the authenticating user has a pending follow request.
233 *
234 * @param integer $cursor Causes the list of IDs to be broken into pages of no more than 5000 IDs at a time. The number of IDs returned
235 * is not guaranteed to be 5000 as suspended users are filtered out after connections are queried. If no cursor
236 * is provided, a value of -1 will be assumed, which is the first "page."
237 * @param boolean $string_ids Set to true to return IDs as strings, false to return as integers.
238 *
239 * @return array The decoded JSON response
240 *
241 * @since 12.3
242 */
243 public function getFriendshipsOutgoing($cursor = null, $string_ids = null)
244 {
245 // Check the rate limit for remaining hits
246 $this->checkRateLimit('friendships', 'outgoing');
247
248 $data = array();
249
250 // Check if cursor is specified
251 if (!is_null($cursor))
252 {
253 $data['cursor'] = $cursor;
254 }
255
256 // Check if string_ids is specified
257 if (!is_null($string_ids))
258 {
259 $data['stringify_ids'] = $string_ids;
260 }
261
262 // Set the API path
263 $path = '/friendships/outgoing.json';
264
265 // Send the request.
266 return $this->sendRequest($path, 'GET', $data);
267 }
268
269 /**
270 * Allows the authenticating users to follow the user specified in the ID parameter.
271 *
272 * @param mixed $user Either an integer containing the user ID or a string containing the screen name.
273 * @param boolean $follow Enable notifications for the target user.
274 *
275 * @return array The decoded JSON response
276 *
277 * @since 12.3
278 * @throws RuntimeException
279 */
280 public function follow($user, $follow = false)
281 {
282 // Determine which type of data was passed for $user
283 if (is_numeric($user))
284 {
285 $data['user_id'] = $user;
286 }
287 elseif (is_string($user))
288 {
289 $data['screen_name'] = $user;
290 }
291 else
292 {
293 // We don't have a valid entry
294 throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
295 }
296
297 // Check if follow is true
298 if ($follow)
299 {
300 $data['follow'] = $follow;
301 }
302
303 // Set the API path
304 $path = '/friendships/create.json';
305
306 // Send the request.
307 return $this->sendRequest($path, 'POST', $data);
308 }
309
310 /**
311 * Allows the authenticating users to unfollow the user specified in the ID parameter.
312 *
313 * @param mixed $user Either an integer containing the user ID or a string containing the screen name.
314 *
315 * @return array The decoded JSON response
316 *
317 * @since 12.3
318 * @throws RuntimeException
319 */
320 public function unfollow($user)
321 {
322 // Determine which type of data was passed for $user
323 if (is_numeric($user))
324 {
325 $data['user_id'] = $user;
326 }
327 elseif (is_string($user))
328 {
329 $data['screen_name'] = $user;
330 }
331 else
332 {
333 // We don't have a valid entry
334 throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
335 }
336
337 // Set the API path
338 $path = '/friendships/destroy.json';
339
340 // Send the request.
341 return $this->sendRequest($path, 'POST', $data);
342 }
343
344 /**
345 * Method to get the relationship of the authenticating user to the comma separated list of up to 100 screen_names or user_ids provided.
346 *
347 * @param string $screen_name A comma separated list of screen names, up to 100 are allowed in a single request.
348 * @param string $id A comma separated list of user IDs, up to 100 are allowed in a single request.
349 *
350 * @return array The decoded JSON response
351 *
352 * @since 12.3
353 * @throws RuntimeException
354 */
355 public function getFriendshipsLookup($screen_name = null, $id = null)
356 {
357 // Check the rate limit for remaining hits
358 $this->checkRateLimit('friendships', 'lookup');
359
360 // Set user IDs and screen names.
361 if ($id)
362 {
363 $data['user_id'] = $id;
364 }
365
366 if ($screen_name)
367 {
368 $data['screen_name'] = $screen_name;
369 }
370
371 if ($id == null && $screen_name == null)
372 {
373 // We don't have a valid entry
374 throw new RuntimeException('You must specify either a comma separated list of screen names, user IDs, or a combination of the two');
375 }
376
377 // Set the API path
378 $path = '/friendships/lookup.json';
379
380 // Send the request.
381 return $this->sendRequest($path, 'GET', $data);
382 }
383
384 /**
385 * Allows one to enable or disable retweets and device notifications from the specified user.
386 *
387 * @param mixed $user Either an integer containing the user ID or a string containing the screen name.
388 * @param boolean $device Enable/disable device notifications from the target user.
389 * @param boolean $retweets Enable/disable retweets from the target user.
390 *
391 * @return array The decoded JSON response
392 *
393 * @since 12.3
394 * @throws RuntimeException
395 */
396 public function updateFriendship($user, $device = null, $retweets = null)
397 {
398 // Determine which type of data was passed for $user
399 if (is_numeric($user))
400 {
401 $data['user_id'] = $user;
402 }
403 elseif (is_string($user))
404 {
405 $data['screen_name'] = $user;
406 }
407 else
408 {
409 // We don't have a valid entry
410 throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
411 }
412
413 // Check if device is specified.
414 if (!is_null($device))
415 {
416 $data['device'] = $device;
417 }
418
419 // Check if retweets is specified.
420 if (!is_null($retweets))
421 {
422 $data['retweets'] = $retweets;
423 }
424
425 // Set the API path
426 $path = '/friendships/update.json';
427
428 // Send the request.
429 return $this->sendRequest($path, 'POST', $data);
430 }
431
432 /**
433 * Method to get the user ids that currently authenticated user does not want to see retweets from.
434 *
435 * @param boolean $string_ids Set to true to return IDs as strings, false to return as integers.
436 *
437 * @return array The decoded JSON response
438 *
439 * @since 12.3
440 */
441 public function getFriendshipNoRetweetIds($string_ids = null)
442 {
443 // Check the rate limit for remaining hits
444 $this->checkRateLimit('friendships', 'no_retweets/ids');
445
446 $data = array();
447
448 // Check if string_ids is specified
449 if (!is_null($string_ids))
450 {
451 $data['stringify_ids'] = $string_ids;
452 }
453
454 // Set the API path
455 $path = '/friendships/no_retweets/ids.json';
456
457 // Send the request.
458 return $this->sendRequest($path, 'GET', $data);
459 }
460 }
461