Source for file friends.php

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

Documentation generated on Tue, 19 Nov 2013 15:03:48 +0100 by phpDocumentor 1.4.3