Joomla Platform  13.1
Documentation des API du framework Joomla Platform
 Tout Classes Espaces de nommage Fichiers Fonctions Variables Pages
statuses.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 Statuses class for the Joomla Platform.
14  *
15  * @package Joomla.Platform
16  * @subpackage Twitter
17  * @since 12.3
18  */
19 class JTwitterStatuses extends JTwitterObject
20 {
21  /**
22  * Method to get a single tweet with the given ID.
23  *
24  * @param integer $id The ID of the tweet to retrieve.
25  * @param boolean $trim_user When set to true, each tweet returned in a timeline will include a user object including only
26  * the status author's numerical ID.
27  * @param boolean $entities When set to true, each tweet will include a node called "entities,". This node offers a variety of metadata
28  * about the tweet in a discreet structure, including: user_mentions, urls, and hashtags.
29  * @param boolean $my_retweet When set to either true, t or 1, any statuses returned that have been retweeted by the authenticating user will
30  * include an additional current_user_retweet node, containing the ID of the source status for the retweet.
31  *
32  * @return array The decoded JSON response
33  *
34  * @since 12.3
35  */
36  public function getTweetById($id, $trim_user = null, $entities = null, $my_retweet = null)
37  {
38  // Check the rate limit for remaining hits
39  $this->checkRateLimit("statuses", "show/:id");
40 
41  // Set the API base
42  $path = '/statuses/show/' . $id . '.json';
43 
44  $data = array();
45 
46  // Check if trim_user is specified
47  if (!is_null($trim_user))
48  {
49  $data['trim_user'] = $trim_user;
50  }
51 
52  // Check if entities is specified
53  if (!is_null($entities))
54  {
55  $data['include_entities'] = $entities;
56  }
57 
58  // Check if my_retweet is specified
59  if (!is_null($my_retweet))
60  {
61  $data['include_my_retweet'] = $my_retweet;
62  }
63 
64  // Send the request.
65  return $this->sendRequest($path, 'GET', $data);
66  }
67 
68  /**
69  * Method to retrieve the latest statuses from the specified user timeline.
70  *
71  * @param mixed $user Either an integer containing the user ID or a string containing the screen name.
72  * @param integer $count Specifies the number of tweets to try and retrieve, up to a maximum of 200. Retweets are always included
73  * in the count, so it is always suggested to set $include_rts to true
74  * @param boolean $include_rts When set to true, the timeline will contain native retweets in addition to the standard stream of tweets.
75  * @param boolean $no_replies This parameter will prevent replies from appearing in the returned timeline. This parameter is only supported
76  * for JSON and XML responses.
77  * @param integer $since_id Returns results with an ID greater than (that is, more recent than) the specified ID.
78  * @param integer $max_id Returns results with an ID less than (that is, older than) the specified ID.
79  * @param boolean $trim_user When set to true, each tweet returned in a timeline will include a user object including only
80  * the status author's numerical ID.
81  * @param boolean $contributor This parameter enhances the contributors element of the status response to include the screen_name of the
82  * contributor. By default only the user_id of the contributor is included.
83  *
84  * @return array The decoded JSON response
85  *
86  * @since 12.3
87  * @throws RuntimeException
88  */
89  public function getUserTimeline($user, $count = 20, $include_rts = null, $no_replies = null, $since_id = 0, $max_id = 0, $trim_user = null,
90  $contributor = null)
91  {
92  // Check the rate limit for remaining hits
93  $this->checkRateLimit('statuses', 'user_timeline');
94 
95  $data = array();
96 
97  // Determine which type of data was passed for $user
98  if (is_numeric($user))
99  {
100  $data['user_id'] = $user;
101  }
102  elseif (is_string($user))
103  {
104  $data['screen_name'] = $user;
105  }
106  else
107  {
108  // We don't have a valid entry
109  throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
110  }
111 
112  // Set the API base
113  $path = '/statuses/user_timeline.json';
114 
115  // Set the count string
116  $data['count'] = $count;
117 
118  // Check if include_rts is specified
119  if (!is_null($include_rts))
120  {
121  $data['include_rts'] = $include_rts;
122  }
123 
124  // Check if no_replies is specified
125  if (!is_null($no_replies))
126  {
127  $data['exclude_replies'] = $no_replies;
128  }
129 
130  // Check if a since_id is specified
131  if ($since_id > 0)
132  {
133  $data['since_id'] = (int) $since_id;
134  }
135 
136  // Check if a max_id is specified
137  if ($max_id > 0)
138  {
139  $data['max_id'] = (int) $max_id;
140  }
141 
142  // Check if trim_user is specified
143  if (!is_null($trim_user))
144  {
145  $data['trim_user'] = $trim_user;
146  }
147 
148  // Check if contributor details is specified
149  if (!is_null($contributor))
150  {
151  $data['contributor_details'] = $contributor;
152  }
153 
154  // Send the request.
155  return $this->sendRequest($path, 'GET', $data);
156  }
157 
158  /**
159  * Method to post a tweet.
160  *
161  * @param string $status The text of the tweet.
162  * @param integer $in_reply_to_status_id The ID of an existing status that the update is in reply to.
163  * @param float $lat The latitude of the location this tweet refers to.
164  * @param float $long The longitude of the location this tweet refers to.
165  * @param string $place_id A place in the world.
166  * @param boolean $display_coordinates Whether or not to put a pin on the exact coordinates a tweet has been sent from.
167  * @param boolean $trim_user When set to true, each tweet returned in a timeline will include a user object including only
168  * the status author's numerical ID.
169  *
170  * @return array The decoded JSON response
171  *
172  * @since 12.3
173  */
174  public function tweet($status, $in_reply_to_status_id = null, $lat = null, $long = null, $place_id = null, $display_coordinates = null,
175  $trim_user = null)
176  {
177  // Set the API base.
178  $path = '/statuses/update.json';
179 
180  // Set POST data.
181  $data = array('status' => utf8_encode($status));
182 
183  // Check if in_reply_to_status_id is specified.
184  if ($in_reply_to_status_id)
185  {
186  $data['in_reply_to_status_id'] = $in_reply_to_status_id;
187  }
188 
189  // Check if lat is specified.
190  if ($lat)
191  {
192  $data['lat'] = $lat;
193  }
194 
195  // Check if long is specified.
196  if ($long)
197  {
198  $data['long'] = $long;
199  }
200 
201  // Check if place_id is specified.
202  if ($place_id)
203  {
204  $data['place_id'] = $place_id;
205  }
206 
207  // Check if display_coordinates is specified.
208  if (!is_null($display_coordinates))
209  {
210  $data['display_coordinates'] = $display_coordinates;
211  }
212 
213  // Check if trim_user is specified.
214  if (!is_null($trim_user))
215  {
216  $data['trim_user'] = $trim_user;
217  }
218 
219  // Send the request.
220  return $this->sendRequest($path, 'POST', $data);
221  }
222 
223  /**
224  * Method to retrieve the most recent mentions for the authenticating user.
225  *
226  * @param integer $count Specifies the number of tweets to try and retrieve, up to a maximum of 200. Retweets are always included
227  * in the count, so it is always suggested to set $include_rts to true
228  * @param boolean $include_rts When set to true, the timeline will contain native retweets in addition to the standard stream of tweets.
229  * @param boolean $entities When set to true, each tweet will include a node called "entities,". This node offers a variety of metadata
230  * about the tweet in a discreet structure, including: user_mentions, urls, and hashtags.
231  * @param integer $since_id Returns results with an ID greater than (that is, more recent than) the specified ID.
232  * @param integer $max_id Returns results with an ID less than (that is, older than) the specified ID.
233  * @param boolean $trim_user When set to true, each tweet returned in a timeline will include a user object including only
234  * the status author's numerical ID.
235  * @param string $contributor This parameter enhances the contributors element of the status response to include the screen_name
236  * of the contributor.
237  *
238  * @return array The decoded JSON response
239  *
240  * @since 12.3
241  * @throws RuntimeException
242  */
243  public function getMentions($count = 20, $include_rts = null, $entities = null, $since_id = 0, $max_id = 0,
244  $trim_user = null, $contributor = null)
245  {
246  // Check the rate limit for remaining hits
247  $this->checkRateLimit('statuses', 'mentions_timeline');
248 
249  // Set the API base
250  $path = '/statuses/mentions_timeline.json';
251 
252  // Set the count string
253  $data['count'] = $count;
254 
255  // Check if include_rts is specified
256  if (!is_null($include_rts))
257  {
258  $data['include_rts'] = $include_rts;
259  }
260 
261  // Check if entities is specified
262  if (!is_null($entities))
263  {
264  $data['include_entities'] = $entities;
265  }
266 
267  // Check if a since_id is specified
268  if ($since_id > 0)
269  {
270  $data['since_id'] = (int) $since_id;
271  }
272 
273  // Check if a max_id is specified
274  if ($max_id > 0)
275  {
276  $data['max_id'] = (int) $max_id;
277  }
278 
279  // Check if trim_user is specified
280  if (!is_null($trim_user))
281  {
282  $data['trim_user'] = $trim_user;
283  }
284 
285  // Check if contributor is specified
286  if (!is_null($contributor))
287  {
288  $data['contributor_details'] = $contributor;
289  }
290 
291  // Send the request.
292  return $this->sendRequest($path, 'GET', $data);
293  }
294 
295  /**
296  * Method to get the most recent tweets of the authenticated user that have been retweeted by others.
297  *
298  * @param integer $count Specifies the number of tweets to try and retrieve, up to a maximum of 200. Retweets are always included
299  * in the count, so it is always suggested to set $include_rts to true
300  * @param integer $since_id Returns results with an ID greater than (that is, more recent than) the specified ID.
301  * @param boolean $entities When set to true, each tweet will include a node called "entities,". This node offers a variety of metadata
302  * about the tweet in a discreet structure, including: user_mentions, urls, and hashtags.
303  * @param boolean $user_entities The user entities node will be disincluded when set to false.
304  * @param integer $max_id Returns results with an ID less than (that is, older than) the specified ID.
305  * @param boolean $trim_user When set to true, each tweet returned in a timeline will include a user object including only
306  * the status author's numerical ID.
307  *
308  * @return array The decoded JSON response
309  *
310  * @since 12.3
311  */
312  public function getRetweetsOfMe($count = 20, $since_id = 0, $entities = null, $user_entities = null, $max_id = 0, $trim_user = null)
313  {
314  // Check the rate limit for remaining hits
315  $this->checkRateLimit('statuses', 'retweets_of_me');
316 
317  // Set the API path
318  $path = '/statuses/retweets_of_me.json';
319 
320  // Set the count string
321  $data['count'] = $count;
322 
323  // Check if a since_id is specified
324  if ($since_id > 0)
325  {
326  $data['since_id'] = (int) $since_id;
327  }
328 
329  // Check if a max_id is specified
330  if ($max_id > 0)
331  {
332  $data['max_id'] = (int) $max_id;
333  }
334 
335  // Check if trim_user is specified
336  if (!is_null($trim_user))
337  {
338  $data['trim_user'] = $trim_user;
339  }
340 
341  // Check if entities is specified
342  if (!is_null($entities))
343  {
344  $data['include_entities'] = $entities;
345  }
346 
347  // Check if entities is specified
348  if (!is_null($user_entities))
349  {
350  $data['include_user_entities'] = $user_entities;
351  }
352 
353  // Send the request.
354  return $this->sendRequest($path, 'GET', $data);
355  }
356 
357  /**
358  * Method to show user objects of up to 100 members who retweeted the status.
359  *
360  * @param integer $id The numerical ID of the desired status.
361  * @param integer $count Specifies the number of retweets to try and retrieve, up to a maximum of 100.
362  * @param integer $cursor Causes the list of IDs to be broken into pages of no more than 100 IDs at a time.
363  * The number of IDs returned is not guaranteed to be 100 as suspended users are
364  * filtered out after connections are queried. If no cursor is provided, a value of
365  * -1 will be assumed, which is the first "page."
366  * @param boolean $stringify_ids Set to true to return IDs as strings, false to return as integers.
367  *
368  * @return array The decoded JSON response
369  *
370  * @since 12.3
371  */
372  public function getRetweeters($id, $count = 20, $cursor = null, $stringify_ids = null)
373  {
374  // Check the rate limit for remaining hits
375  $this->checkRateLimit('statuses', 'retweeters/ids');
376 
377  // Set the API path
378  $path = '/statuses/retweeters/ids.json';
379 
380  // Set the status id.
381  $data['id'] = $id;
382 
383  // Set the count string
384  $data['count'] = $count;
385 
386  // Check if cursor is specified
387  if (!is_null($cursor))
388  {
389  $data['cursor'] = $cursor;
390  }
391 
392  // Check if entities is specified
393  if (!is_null($stringify_ids))
394  {
395  $data['stringify_ids'] = $stringify_ids;
396  }
397 
398  // Send the request.
399  return $this->sendRequest($path, 'GET', $data);
400  }
401 
402  /**
403  * Method to get up to 100 of the first retweets of a given tweet.
404  *
405  * @param integer $id The numerical ID of the desired status.
406  * @param integer $count Specifies the number of tweets to try and retrieve, up to a maximum of 200. Retweets are always included
407  * in the count, so it is always suggested to set $include_rts to true
408  * @param boolean $trim_user When set to true, each tweet returned in a timeline will include a user object including only
409  * the status author's numerical ID.
410  *
411  * @return array The decoded JSON response
412  *
413  * @since 12.3
414  */
415  public function getRetweetsById($id, $count = 20, $trim_user = null)
416  {
417  // Check the rate limit for remaining hits
418  $this->checkRateLimit('statuses', 'retweets/:id');
419 
420  // Set the API path
421  $path = '/statuses/retweets/' . $id . '.json';
422 
423  // Set the count string
424  $data['count'] = $count;
425 
426  // Check if trim_user is specified
427  if (!is_null($trim_user))
428  {
429  $data['trim_user'] = $trim_user;
430  }
431 
432  // Send the request.
433  return $this->sendRequest($path, 'GET', $data);
434  }
435 
436  /**
437  * Method to delete the status specified by the required ID parameter.
438  *
439  * @param integer $id The numerical ID of the desired status.
440  * @param boolean $trim_user When set to true, each tweet returned in a timeline will include a user object including only
441  * the status author's numerical ID.
442  *
443  * @return array The decoded JSON response
444  *
445  * @since 12.3
446  */
447  public function deleteTweet($id, $trim_user = null)
448  {
449  // Set the API path
450  $path = '/statuses/destroy/' . $id . '.json';
451 
452  $data = array();
453 
454  // Check if trim_user is specified
455  if (!is_null($trim_user))
456  {
457  $data['trim_user'] = $trim_user;
458  }
459 
460  // Send the request.
461  return $this->sendRequest($path, 'POST', $data);
462  }
463 
464  /**
465  * Method to retweet a tweet.
466  *
467  * @param integer $id The numerical ID of the desired status.
468  * @param boolean $trim_user When set to true, each tweet returned in a timeline will include a user object including only
469  * the status author's numerical ID.
470  *
471  * @return array The decoded JSON response
472  *
473  * @since 12.3
474  */
475  public function retweet($id, $trim_user = null)
476  {
477  // Set the API path
478  $path = '/statuses/retweet/' . $id . '.json';
479 
480  $data = array();
481 
482  // Check if trim_user is specified
483  if (!is_null($trim_user))
484  {
485  $data['trim_user'] = $trim_user;
486  }
487 
488  // Send the request.
489  return $this->sendRequest($path, 'POST', $data);
490  }
491 
492  /**
493  * Method to post a tweet with media.
494  *
495  * @param string $status The text of the tweet.
496  * @param string $media File to upload
497  * @param integer $in_reply_to_status_id The ID of an existing status that the update is in reply to.
498  * @param float $lat The latitude of the location this tweet refers to.
499  * @param float $long The longitude of the location this tweet refers to.
500  * @param string $place_id A place in the world.
501  * @param boolean $display_coordinates Whether or not to put a pin on the exact coordinates a tweet has been sent from.
502  * @param boolean $sensitive Set to true for content which may not be suitable for every audience.
503  *
504  * @return array The decoded JSON response
505  *
506  * @since 12.3
507  * @throws RuntimeException
508  */
509  public function tweetWithMedia($status, $media, $in_reply_to_status_id = null, $lat = null, $long = null, $place_id = null,
510  $display_coordinates = null, $sensitive = null)
511  {
512  // Set the API request path.
513  $path = '/statuses/update_with_media.json';
514 
515  // Set POST data.
516  $data = array(
517  'status' => utf8_encode($status),
518  'media[]' => "@{$media}"
519  );
520 
521  $header = array('Content-Type' => 'multipart/form-data');
522 
523  // Check if in_reply_to_status_id is specified.
524  if (!is_null($in_reply_to_status_id))
525  {
526  $data['in_reply_to_status_id'] = $in_reply_to_status_id;
527  }
528 
529  // Check if lat is specified.
530  if ($lat)
531  {
532  $data['lat'] = $lat;
533  }
534 
535  // Check if long is specified.
536  if ($long)
537  {
538  $data['long'] = $long;
539  }
540 
541  // Check if place_id is specified.
542  if ($place_id)
543  {
544  $data['place_id'] = $place_id;
545  }
546 
547  // Check if display_coordinates is specified.
548  if (!is_null($display_coordinates))
549  {
550  $data['display_coordinates'] = $display_coordinates;
551  }
552 
553  // Check if sensitive is specified.
554  if (!is_null($sensitive))
555  {
556  $data['possibly_sensitive'] = $sensitive;
557  }
558 
559  // Send the request.
560  return $this->sendRequest($path, 'POST', $data, $header);
561  }
562 
563  /**
564  * Method to get information allowing the creation of an embedded representation of a Tweet on third party sites.
565  * Note: either the id or url parameters must be specified in a request. It is not necessary to include both.
566  *
567  * @param integer $id The Tweet/status ID to return embed code for.
568  * @param string $url The URL of the Tweet/status to be embedded.
569  * @param integer $maxwidth The maximum width in pixels that the embed should be rendered at. This value is constrained to be
570  * between 250 and 550 pixels.
571  * @param boolean $hide_media Specifies whether the embedded Tweet should automatically expand images which were uploaded via
572  * POST statuses/update_with_media.
573  * @param boolean $hide_thread Specifies whether the embedded Tweet should automatically show the original message in the case that
574  * the embedded Tweet is a reply.
575  * @param boolean $omit_script Specifies whether the embedded Tweet HTML should include a <script> element pointing to widgets.js. In cases where
576  * a page already includes widgets.js, setting this value to true will prevent a redundant script element from being included.
577  * @param string $align Specifies whether the embedded Tweet should be left aligned, right aligned, or centered in the page.
578  * Valid values are left, right, center, and none.
579  * @param string $related A value for the TWT related parameter, as described in Web Intents. This value will be forwarded to all
580  * Web Intents calls.
581  * @param string $lang Language code for the rendered embed. This will affect the text and localization of the rendered HTML.
582  *
583  * @return array The decoded JSON response
584  *
585  * @since 12.3
586  * @throws RuntimeException
587  */
588  public function getOembed($id = null, $url = null, $maxwidth = null, $hide_media = null, $hide_thread = null, $omit_script = null,
589  $align = null, $related = null, $lang = null)
590  {
591  // Check the rate limit for remaining hits.
592  $this->checkRateLimit('statuses', 'oembed');
593 
594  // Set the API request path.
595  $path = '/statuses/oembed.json';
596 
597  // Determine which of $id and $url is specified.
598  if ($id)
599  {
600  $data['id'] = $id;
601  }
602  elseif ($url)
603  {
604  $data['url'] = rawurlencode($url);
605  }
606  else
607  {
608  // We don't have a valid entry.
609  throw new RuntimeException('Either the id or url parameters must be specified in a request.');
610  }
611 
612  // Check if maxwidth is specified.
613  if ($maxwidth)
614  {
615  $data['maxwidth'] = $maxwidth;
616  }
617 
618  // Check if hide_media is specified.
619  if (!is_null($hide_media))
620  {
621  $data['hide_media'] = $hide_media;
622  }
623 
624  // Check if hide_thread is specified.
625  if (!is_null($hide_thread))
626  {
627  $data['hide_thread'] = $hide_thread;
628  }
629 
630  // Check if omit_script is specified.
631  if (!is_null($omit_script))
632  {
633  $data['omit_script'] = $omit_script;
634  }
635 
636  // Check if align is specified.
637  if ($align)
638  {
639  $data['align'] = $align;
640  }
641 
642  // Check if related is specified.
643  if ($related)
644  {
645  $data['related'] = $related;
646  }
647 
648  // Check if lang is specified.
649  if ($lang)
650  {
651  $data['lang'] = $lang;
652  }
653 
654  // Send the request.
655  return $this->sendRequest($path, 'GET', $data);
656  }
657 }