Source for file Twitter.php

Documentation is available at Twitter.php

  1. <?php
  2.     /**
  3.      * 
  4.      * SWX Twitter API by Aral Balkan.
  5.      * 
  6.      * You can call this API using SWX, Amfphp, JSON and XML-RPC.
  7.      * 
  8.      * @author    Aral Balkan
  9.      * @copyright    2007 Aral Balkan. All Rights Reserved.
  10.      * @link     http://aralbalkan.com
  11.      * @link     http://swxformat.org
  12.      * @link    mailto://aral@aralbalkan.com
  13.      * 
  14.     ***/
  15.     
  16.     // Require base service class
  17.         require_once("../BaseService.php");
  18.  
  19.     /**
  20.      * SWX Twitter API by Aral Balkan. You can call this API using SWX, Amfphp, JSON and XML-RPC.
  21.     **/
  22.  
  23.     class Twitter extends BaseService
  24.     {
  25.         function Twitter()
  26.         {
  27.             // Nothing.
  28.         }
  29.         
  30.         //
  31.         // Official Twitter API methods: These implement the twitter API exactly
  32.         // See http://groups.google.com/group/twitter-development-talk/web/api-documentation
  33.         // for the full official documentation.
  34.         //
  35.         
  36.                 
  37.         /**
  38.          * Returns the 20 most recent statuses from non-protected users who have set a custom user icon.  Does not require authentication.
  39.          *
  40.          * @param    (optional)    Returns only public statuses with an ID greater than (that is, more recent than) the specified.
  41.          * @param    (optional)    Narrows the returned results to just those statuses created after the specified HTTP-formatted date.
  42.          * 
  43.          * @return Array of statuses.
  44.          * @author Aral Balkan
  45.          ***/
  46.         function publicTimeline($sinceId = NULL)
  47.         {
  48.             $url = 'twitter.com/statuses/public_timeline.json';
  49.  
  50.             $vars = array('since_id' => $sinceId);
  51.  
  52.             $response = $this->_jsonCall($url, $vars, 'GET');
  53.             
  54.             return $response;
  55.         }
  56.         
  57.         /**
  58.          * Returns the 20 most recent statuses posted in the last 24 hours from the authenticating user and that user's friends.  It's also possible to request another user's friends_timeline via the id parameter.
  59.          * 
  60.          * @param    Your username.
  61.          * @param    Your password.
  62.          * @param    (optional)    ID or screen name of the user for whom to return the friends_timeline.
  63.          * @param    (optional)    Narrows the returned results to just those statuses created after the specified HTTP-formatted date.
  64.          * 
  65.          * @return Array of statuses.
  66.          * @author Aral Balkan
  67.          ***/
  68.         function friendsTimeline($user, $pass, $id = NULL, $since = NULL)
  69.         {
  70.             $url = 'twitter.com/statuses/friends_timeline.json';
  71.             
  72.             $vars = array('id' => $id, 'since' => $since);
  73.             
  74.             $response = $this->_jsonCall($url, $vars, 'GET', $user, $pass);
  75.             
  76.             return $response;
  77.         }
  78.         
  79.         /**
  80.          * Returns the 20 most recent statuses posted in the last 24 hours from the authenticating user.  It's also possible to request another user's timeline via the id parameter below.
  81.          * 
  82.          *
  83.          * @return void 
  84.          * @author Aral Balkan
  85.          ***/
  86.         function userTimeline($user, $pass, $id = NULL, $count = NULL, $since = NULL)
  87.         {
  88.             $url = 'twitter.com/statuses/user_timeline.json';
  89.             
  90.             $vars = array('id' => $id, 'count' => $count, 'since' => $since);
  91.             
  92.             $response = $this->_jsonCall($url, $vars, 'GET', $user, $pass);
  93.             
  94.             return $response;
  95.         }
  96.         
  97.         /**
  98.          * Returns a single status, specified by the id parameter below.  The status's author will be returned inline.
  99.          * 
  100.          * @param    The numerical ID of the status you're trying to retrieve.
  101.          *
  102.          * @return void 
  103.          * @author Aral Balkan
  104.          ***/
  105.         function showStatus($id)
  106.         {
  107.             $url = "twitter.com/statuses/show/$id.json";
  108.             
  109.             $response = $this->_jsonCall($url, NULL, 'GET');
  110.             
  111.             return $response;
  112.         }
  113.  
  114.         /**
  115.          * Posts a twitter update.
  116.          *
  117.          * @param (str) Twitter update message
  118.          * @param (str) Your user name
  119.          * @param (str) Your password
  120.          * @param (optional, str) Source string. If enabled by Twitter, this will appear in the "from" section of the update.
  121.          * 
  122.          * @return     (array)    Success/failure message.
  123.          * 
  124.          * @author     Aral Balkan
  125.          ***/
  126.         function update($update, $user, $pass, $source = NULL)
  127.         {
  128.             $url = 'twitter.com/statuses/update.json';
  129.             $args = array('status' => $update);
  130.             
  131.             if ($source != NULL) 
  132.             {
  133.                 error_log("source = ".$source);
  134.                 $args['source'] = $source;    
  135.                 
  136.                 error_log($args['status']);
  137.                 error_log($args['source']);
  138.             }
  139.             
  140.             $response = $this->_jsonCall($url, $args, 'POST', $user, $pass);
  141.             
  142.             return $response;
  143.         }
  144.         
  145.         /**
  146.          * Returns followers who are not friends.
  147.          * 
  148.          * @param     (str) User name.
  149.          * @param    (str) Password.
  150.          *
  151.          * @return (array) List of followers that are not friends.
  152.          * @author Aral Balkan
  153.          ***/
  154.         function followersWhoAreNotFriends($user, $pass)
  155.         {
  156.             // Get list of followers and friends from Twitter
  157.             // (this may take a while if you have lots of them!)
  158.             $followers = $this->followers($user, $pass);
  159.             $friends = $this->friends($user, $pass);
  160.             
  161.             // Create followers id-based hash
  162.             $followerIds = array();
  163.             $numFollowers = count($followers);
  164.             for ($i = 0; $i < $numFollowers; $i++)
  165.             {
  166.                 $follower = $followers[$i];
  167.                 $id = $follower->id;
  168.                 error_log('Followers screen_name = '.$id);
  169.                 $followerIds[$id] = $follower;
  170.             }
  171.             
  172.             // Create friends id-based hash
  173.             $friendIds = array();
  174.             $numFriends = count($friends);
  175.             for ($i = 0; $i < $numFriends; $i ++)
  176.             {
  177.                 $friend = $friends[$i];
  178.                 $id = $friend->id;
  179.                 error_log('Friends ID = '.$id);
  180.                 $friendIds[$id] = $friend;
  181.             }
  182.             
  183.             // Calculate the difference of the id arrays
  184.             $followersWhoAreNotFriends = array();
  185.             foreach ($followerIds as $followerId => $follower)
  186.             {
  187.                 error_log("testing: " . $friendIds[$followerId]);
  188.                 if (!isset($friendIds[$followerId]))
  189.                 {
  190.                     error_log("Friend with id $followerId, does not exist.");
  191.                     array_push($followersWhoAreNotFriends, $follower);
  192.                 }
  193.                 else
  194.                 {
  195.                     error_log("Friend with id $followerId exists.");
  196.                 }
  197.             }
  198.             
  199.             return $followersWhoAreNotFriends;
  200.         }
  201.  
  202.         /**
  203.          * Gets friends for the passed user.
  204.          *
  205.          * @param    (str) Username.
  206.          * @param    (str) Password.
  207.          * 
  208.          * @return     (array)    List of friends.
  209.          * @author Aral Balkan
  210.          ***/
  211.         function friends($user, $pass)
  212.         {
  213.             $url = "twitter.com/statuses/friends/$user.json";
  214.             $response = $this->_jsonCall($url,  NULL, 'GET', $user, $pass);
  215.             return $response;
  216.         }
  217.         
  218.         /**
  219.          * Gets friends for the passed user name. Doesn't
  220.          * require authentication but will not return friends
  221.          * who have set themselves to private.
  222.          *
  223.          * @param    (str) User name
  224.          * 
  225.          * @return     (array)    List of friends.
  226.          * @author Aral Balkan
  227.          ***/
  228.         function friendsNoAuth($user)
  229.         {
  230.             $url = "twitter.com/statuses/friends/$userName.json";
  231.             $response = $this->_jsonCall($url,  NULL, 'GET');
  232.             return $response;
  233.         }        
  234.  
  235.         /**
  236.          * Gets followers for authenticated user.
  237.          * 
  238.          * @param    (str) Your username.
  239.          * @param    (str) Your password.
  240.          * 
  241.          * @return (array) List of followers.
  242.          * @author Aral Balkan
  243.          ***/
  244.         function followers($user, $pass)
  245.         {
  246.             $url = 'twitter.com/statuses/followers.json';
  247.             
  248.             $response = $this->_jsonCall($url, NULL, 'GET', $user, $pass);
  249.             
  250.             return $response;    
  251.         }
  252.         
  253.         /**
  254.          * Returns currently featured users on the site and their latest update.
  255.          * (You must be authenticated to get this for some reason.)
  256.          * 
  257.          * This call is currently not working as the Twitter API returns a
  258.          * callback method for this. I've raised this issue with the Twitter devs and
  259.          * I'm waiting to hear back from them about this inconsistent behavior.
  260.          *
  261.          * @param    (str) Your username
  262.          * @param    (str) Your password
  263.          * 
  264.          * @return     (array) List of featured users and their current update.
  265.          * @author Aral Balkan
  266.          ***/
  267.         /*
  268.         function featured($user, $pass)
  269.         {
  270.             $url = 'twitter.com/statuses/featured.json';
  271.             
  272.             $response = $this->_jsonCall($url, NULL, 'GET', $user, $pass);
  273.             
  274.             return $response;    
  275.         }
  276.         */
  277.         
  278.         /**
  279.          * Returns extended information of a given user, specified by ID or screen name as per the required id parameter below.  This information includes design settings, so third party developers can theme their widgets according to a given user's preferences.
  280.          * 
  281.          * @param    (str/int)    The ID or screen name of a user.
  282.          * @param    (str)    Your username.
  283.          * @param    (str)    Your password.
  284.          *
  285.          * @return Information on user.
  286.          * @author Aral Balkan
  287.          ***/
  288.         function showUser($id, $user, $pass)
  289.         {
  290.             $url = "twitter.com/users/show/$id.json";
  291.             $response = $this->_jsonCall($url, NULL, 'GET', $user, $pass);
  292.             return $response;
  293.         }
  294.  
  295.  
  296.         /**
  297.          * Returns the list of direct messages for the passed user.
  298.          *
  299.          * @param    (str) Your user name
  300.          * @param    (str) Your password
  301.          * @param     (str) Since (optional)
  302.           * 
  303.          * @return     (array)    List of direct messages
  304.          * 
  305.          * @author     Aral Balkan
  306.          ***/
  307.         function directMessages($user, $pass, $since = NULL)
  308.         {
  309.             $url = 'twitter.com/direct_messages.json';
  310.                         
  311.             $vars = array('since' => $since);
  312.             
  313.             $response = $this->_jsonCall($url, $vars, 'GET', $user, $pass);
  314.             
  315.             return $response;
  316.         }
  317.  
  318.         
  319.         /**
  320.          * Sends a direct message
  321.          * 
  322.          * @param    User name of recipient
  323.          * @param    Message to send
  324.          * @param    Your username
  325.          * @param    Your password
  326.          *
  327.          * @return     The sent direct message.
  328.          * @author Aral Balkan
  329.          ***/
  330.         function newDirectMessage($recipient, $message, $user, $pass)
  331.         {
  332.             $url = 'twitter.com/direct_messages/new.json';
  333.             
  334.             $vars = array('user' => $recipient, 'text' => $message);
  335.             
  336.             $response = $this->_jsonCall($url, $vars, 'POST', $user, $pass);
  337.             
  338.             return $response;
  339.         }
  340.  
  341.         
  342.         //
  343.         // Custom methods
  344.         //
  345.  
  346.         
  347.         /**
  348.          * Returns the number of requested updates from the public timeline (max 20).
  349.          *
  350.          * @param    (int)    Number of updates to get (max 20)
  351.          * @param    (str)    URL-encoded date
  352.          *
  353.          * @return array Updates
  354.          * 
  355.          * @author Aral Balkan
  356.          ***/
  357.         function getNumPublicTimelineUpdates($n = 20, $since = NULL)
  358.         {
  359.             $url = 'twitter.com/statuses/public_timeline.json';
  360.             
  361.             $vars = array('since' => $since);
  362.  
  363.             $response = $this->_jsonCall($url, $vars, 'GET');
  364.             
  365.             // Error?
  366.             if (isset($response['error']))
  367.             {
  368.                 return $response;
  369.             }
  370.  
  371.             if ($response === NULL)
  372.             {
  373.                 if ($since === NULL)
  374.                 {
  375.                     // There was an error in the call.
  376.                     trigger_error("getNumPublicTimelineUpdates() - Twitter returned null", E_USER_ERROR);
  377.                 }
  378.                 else
  379.                 {
  380.                     // There just weren't any updates since the user last checked.
  381.                     $response = array();
  382.                 }
  383.             }
  384.             else
  385.             {
  386.                 $response = array_slice($response, 0, $n);
  387.             }
  388.                         
  389.             // Error conditions:
  390.             //return array(false);
  391.             //syntax_error
  392.             
  393.             return $response;            
  394.         }
  395.  
  396.  
  397.         /**
  398.          * Returns the number of updates for the user and her friends (up to 20) for the passed user name (or email).
  399.          *
  400.          * Note that when calling this without the since parameter, the results appear to be affected
  401.          * by the caching that Twitter has implemented and the results may not be the most recent.
  402.          *
  403.          * @param    (str)    User name (or email)
  404.          * @param    (int)    Number of updates to get (max 20)
  405.          * @param    (str)    (optional) URL-encoded date
  406.          *
  407.          * @return array Updates
  408.          * 
  409.          * @author Aral Balkan
  410.          ***/
  411.         function getNumFriendsUpdates($userName, $n = 20, $since = NULL)
  412.         {
  413.             if ($n === NULL) $n = 20;
  414.             
  415.             $url = "twitter.com/statuses/friends_timeline/$userName.json";
  416.  
  417.             $vars = array('since' => $since);
  418.  
  419.             $response = $this->_jsonCall($url, $vars, 'GET');     
  420.  
  421.             if (isset($response['error']))
  422.             {
  423.                 return $response;
  424.             }
  425.             
  426.             if ($response === NULL)
  427.             {
  428.                 if ($since === NULL)
  429.                 {
  430.                     // There was an error in the call.
  431.                     trigger_error("getNumFriendsUpdates() - Twitter returned null; make sure that the user name you requested ('$userName') exists", E_USER_ERROR);
  432.                 }
  433.                 else
  434.                 {
  435.                     // There just weren't any updates since the user last checked.
  436.                     $response = array();
  437.                 }
  438.             }
  439.             else
  440.             {
  441.                 $response = array_slice($response, 0, $n);
  442.             }
  443.             
  444.             // Error conditions:
  445.             //return array(false);
  446.             //syntax_error
  447.             
  448.             return $response;            
  449.         }
  450.  
  451.  
  452.  
  453.  
  454.         /**
  455.          * Adds friend with passed friend ID and user name.
  456.          * This method is *not* in the official Twitter API and uses cURL.
  457.          *
  458.          * @param    (int)    Friend ID
  459.          * @param    (str)    Friend's user name
  460.          * @param    (str)    Your user name
  461.          * @param     (str)     Your password
  462.          * 
  463.          * @return     (bool)    Success (true/false).
  464.          * 
  465.          * @author Aral Balkan
  466.          ***/
  467.         function addFriend($friendId, $friendUserName, $yourUserName, $yourPassWord)
  468.         {
  469.             $url = "http://twitter.com/friendships/create/$friendId";
  470.             
  471.             $response = $this->_call($url, NULL, 'GET', $yourUserName, $yourPassWord, "http://twitter.com/$friendUserName");
  472.             
  473.             $success = (strpos($response, 'is a friend      you are') !== false);
  474.             
  475.             return $success;            
  476.         }
  477.  
  478.         /**
  479.          * Follows friend with passed friend ID and user name.
  480.          * This method is *not* in the official Twitter API and uses cURL.
  481.          *
  482.          * @param    (int)    Friend ID
  483.          * @param    (str)    Friend's user name
  484.          * @param    (str)    Your user name
  485.          * @param     (str)     Your password
  486.          * 
  487.          * @return     (bool)    Success (true/false).
  488.          * 
  489.          * @author Aral Balkan
  490.          ***/
  491.         function followFriend($friendId, $friendUserName, $yourUserName, $yourPassWord)
  492.         {
  493.             $url = "http://twitter.com/friends/follow/$friendId";
  494.             
  495.             $response = $this->_call($url, NULL, 'GET', $yourUserName, $yourPassWord, "http://twitter.com/$friendUserName");
  496.             
  497.             $success = (strpos($response, '>leave</a>') !== false);
  498.             
  499.             return $success;
  500.         }
  501.  
  502.         /**
  503.          * Leaves friend with passed friend ID and user name.
  504.          * This method is *not* in the official Twitter API and uses cURL.
  505.          *
  506.          * @param    (int)    Friend ID
  507.          * @param    (str)    Friend's user name
  508.          * @param    (str)    Your user name
  509.          * @param     (str)     Your password
  510.          * 
  511.          * @return     (bool)    Success (true/false).
  512.          * 
  513.          * @author Aral Balkan
  514.          ***/
  515.         function leaveFriend($friendId, $friendUserName, $yourUserName, $yourPassWord)
  516.         {
  517.             $url = "http://twitter.com/friends/leave/$friendId";
  518.             
  519.             $response = $this->_call($url, NULL, 'GET', $yourUserName, $yourPassWord, "http://twitter.com/$friendUserName");
  520.             
  521.             $success = (strpos($response, '>follow</a>') !== false);
  522.             
  523.             return $success;
  524.         }
  525.  
  526.         /**
  527.          * Removes friend with passed friend ID and user name.
  528.          * This method is *not* in the official Twitter API and uses cURL.
  529.          *
  530.          * @param    (int)    Friend ID
  531.          * @param    (str)    Friend's user name
  532.          * @param    (str)    Your user name
  533.          * @param     (str)     Your password
  534.          * 
  535.          * @return     (bool)    Success (true/false).
  536.          * 
  537.          * @author Aral Balkan
  538.          ***/
  539.         function removeFriend($friendId, $friendUserName, $yourUserName, $yourPassWord)
  540.         {
  541.             $url = "http://twitter.com/friendships/destroy/$friendId";
  542.             
  543.             $response = $this->_call($url, NULL, 'GET', $yourUserName, $yourPassWord, "http://twitter.com/$friendUserName");
  544.             
  545.             $success = (strpos($response, 'add</a>') !== false);
  546.             
  547.             return $success;
  548.         }
  549.     }
  550. ?>
Documentation generated on Fri, 06 Jul 2007 19:54:54 +0100 by phpDocumentor 1.3.1