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