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