Source for file statuses.php

Documentation is available at statuses.php

  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. {
  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. In cases where
  575.      *                                     a page already includes widgets.js, setting this value to true will prevent a redundant script element from being included.
  576.      * @param   string   $align        Specifies whether the embedded Tweet should be left aligned, right aligned, or centered in the page.
  577.      *                                     Valid values are left, right, center, and none.
  578.      * @param   string   $related      A value for the TWT related parameter, as described in Web Intents. This value will be forwarded to all
  579.      *                                     Web Intents calls.
  580.      * @param   string   $lang         Language code for the rendered embed. This will affect the text and localization of the rendered HTML.
  581.      *
  582.      * @return  array  The decoded JSON response
  583.      *
  584.      * @since   12.3
  585.      * @throws  RuntimeException
  586.      */
  587.     public function getOembed($id null$url null$maxwidth null$hide_media null$hide_thread null$omit_script null,
  588.         $align null$related null$lang null)
  589.     {
  590.         // Check the rate limit for remaining hits.
  591.         $this->checkRateLimit('statuses''oembed');
  592.  
  593.         // Set the API request path.
  594.         $path '/statuses/oembed.json';
  595.  
  596.         // Determine which of $id and $url is specified.
  597.         if ($id)
  598.         {
  599.             $data['id'$id;
  600.         }
  601.         elseif ($url)
  602.         {
  603.             $data['url'rawurlencode($url);
  604.         }
  605.         else
  606.         {
  607.             // We don't have a valid entry.
  608.             throw new RuntimeException('Either the id or url parameters must be specified in a request.');
  609.         }
  610.  
  611.         // Check if maxwidth is specified.
  612.         if ($maxwidth)
  613.         {
  614.             $data['maxwidth'$maxwidth;
  615.         }
  616.  
  617.         // Check if hide_media is specified.
  618.         if (!is_null($hide_media))
  619.         {
  620.             $data['hide_media'$hide_media;
  621.         }
  622.  
  623.         // Check if hide_thread is specified.
  624.         if (!is_null($hide_thread))
  625.         {
  626.             $data['hide_thread'$hide_thread;
  627.         }
  628.  
  629.         // Check if omit_script is specified.
  630.         if (!is_null($omit_script))
  631.         {
  632.             $data['omit_script'$omit_script;
  633.         }
  634.  
  635.         // Check if align is specified.
  636.         if ($align)
  637.         {
  638.             $data['align'$align;
  639.         }
  640.  
  641.         // Check if related is specified.
  642.         if ($related)
  643.         {
  644.             $data['related'$related;
  645.         }
  646.  
  647.         // Check if lang is specified.
  648.         if ($lang)
  649.         {
  650.             $data['lang'$lang;
  651.         }
  652.  
  653.         // Send the request.
  654.         return $this->sendRequest($path'GET'$data);
  655.     }
  656. }

Documentation generated on Tue, 19 Nov 2013 15:14:20 +0100 by phpDocumentor 1.4.3