Source for file users.php

Documentation is available at users.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 Users class for the Joomla Platform.
  14.  *
  15.  * @package     Joomla.Platform
  16.  * @subpackage  Twitter
  17.  * @since       12.3
  18.  */
  19. class JTwitterUsers extends JTwitterObject
  20. {
  21.     /**
  22.      * Method to get up to 100 users worth of extended information, specified by either ID, screen name, or combination of the two.
  23.      *
  24.      * @param   string   $screen_name  A comma separated list of screen names, up to 100 are allowed in a single request.
  25.      * @param   string   $id           A comma separated list of user IDs, up to 100 are allowed in a single request.
  26.      * @param   boolean  $entities     When set to either true, t or 1, each tweet will include a node called "entities,". This node offers a variety of
  27.      *                                     metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags.
  28.      *
  29.      * @return  array  The decoded JSON response
  30.      *
  31.      * @since   12.3
  32.      * @throws  RuntimeException
  33.      */
  34.     public function getUsersLookup($screen_name = null, $id = null, $entities = null)
  35.     {
  36.         // Check the rate limit for remaining hits
  37.         $this->checkRateLimit('users', 'lookup');
  38.  
  39.         // Set user IDs and screen names.
  40.         if ($id)
  41.         {
  42.             $data['user_id'] = $id;
  43.         }
  44.         if ($screen_name)
  45.         {
  46.             $data['screen_name'] = $screen_name;
  47.         }
  48.         if ($id == null && $screen_name == null)
  49.         {
  50.             // We don't have a valid entry
  51.             throw new RuntimeException('You must specify either a comma separated list of screen names, user IDs, or a combination of the two');
  52.         }
  53.  
  54.         // Set the API path
  55.         $path = '/users/lookup.json';
  56.  
  57.         // Check if string_ids is specified
  58.         if (!is_null($entities))
  59.         {
  60.             $data['include_entities'] = $entities;
  61.         }
  62.  
  63.         // Send the request.
  64.         return $this->sendRequest($path, 'POST', $data);
  65.     }
  66.  
  67.     /**
  68.      * Method to access the profile banner in various sizes for the user with the indicated screen_name.
  69.      *
  70.      * @param   mixed  $user  Either an integer containing the user ID or a string containing the screen name.
  71.      *
  72.      * @return  array  The decoded JSON response
  73.      *
  74.      * @since   12.3
  75.      */
  76.     public function getUserProfileBanner($user)
  77.     {
  78.         // Check the rate limit for remaining hits
  79.         $this->checkRateLimit('users', 'profile_banner');
  80.  
  81.         // Set the API path
  82.         $path = '/users/profile_banner.json';
  83.  
  84.         // Determine which type of data was passed for $user
  85.         if (is_numeric($user))
  86.         {
  87.             $data['user_id'] = $user;
  88.         }
  89.         elseif (is_string($user))
  90.         {
  91.             $data['screen_name'] = $user;
  92.         }
  93.         else
  94.         {
  95.             // We don't have a valid entry
  96.             throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
  97.         }
  98.  
  99.         // Send the request.
  100.         return $this->sendRequest($path, 'GET', $data);
  101.     }
  102.  
  103.     /**
  104.      * Method used to search for users
  105.      *
  106.      * @param   string   $query     The search query to run against people search.
  107.      * @param   integer  $page      Specifies the page of results to retrieve.
  108.      * @param   integer  $count     The number of people to retrieve. Maximum of 20 allowed per page.
  109.      * @param   boolean  $entities  When set to either true, t or 1, each tweet will include a node called "entities,". This node offers a
  110.      *                                  variety of metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags.
  111.      *
  112.      * @return  array  The decoded JSON response
  113.      *
  114.      * @since   12.3
  115.      * @throws  RuntimeException
  116.      */
  117.     public function searchUsers($query, $page = 0, $count = 0, $entities = null)
  118.     {
  119.         // Check the rate limit for remaining hits
  120.         $this->checkRateLimit('users', 'search');
  121.  
  122.         $data['q'] = rawurlencode($query);
  123.  
  124.         // Check if page is specified.
  125.         if ($page > 0 )
  126.         {
  127.             $data['page'] = $page;
  128.         }
  129.  
  130.         // Check if per_page is specified
  131.         if ($count > 0)
  132.         {
  133.             $data['count'] = $count;
  134.         }
  135.  
  136.         // Check if entities is specified.
  137.         if (!is_null($entities))
  138.         {
  139.             $data['include_entities'] = $entities;
  140.         }
  141.  
  142.         // Set the API path
  143.         $path = '/users/search.json';
  144.  
  145.         // Send the request.
  146.         return $this->sendRequest($path, 'GET', $data);
  147.     }
  148.  
  149.     /**
  150.      * Method to get extended information of a given user, specified by ID or screen name as per the required id parameter.
  151.      *
  152.      * @param   mixed    $user      Either an integer containing the user ID or a string containing the screen name.
  153.      * @param   boolean  $entities  Set to true to return IDs as strings, false to return as integers.
  154.      *
  155.      * @return  array  The decoded JSON response
  156.      *
  157.      * @since   12.3
  158.      * @throws  RuntimeException
  159.      */
  160.     public function getUser($user, $entities = null)
  161.     {
  162.         // Check the rate limit for remaining hits
  163.         $this->checkRateLimit('users', 'show');
  164.  
  165.         // Determine which type of data was passed for $user
  166.         if (is_numeric($user))
  167.         {
  168.             $data['user_id'] = $user;
  169.         }
  170.         elseif (is_string($user))
  171.         {
  172.             $data['screen_name'] = $user;
  173.         }
  174.         else
  175.         {
  176.             // We don't have a valid entry
  177.             throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
  178.         }
  179.  
  180.         // Set the API path
  181.         $path = '/users/show.json';
  182.  
  183.         // Check if entities is specified
  184.         if (!is_null($entities))
  185.         {
  186.             $data['include_entities'] = $entities;
  187.         }
  188.  
  189.         // Send the request.
  190.         return $this->sendRequest($path, 'GET', $data);
  191.     }
  192.  
  193.     /**
  194.      * Method to get an array of users that the specified user can contribute to.
  195.      *
  196.      * @param   mixed    $user         Either an integer containing the user ID or a string containing the screen name.
  197.      * @param   boolean  $entities     Set to true to return IDs as strings, false to return as integers.
  198.      * @param   boolean  $skip_status  When set to either true, t or 1 statuses will not be included in the returned user objects.
  199.      *
  200.      * @return  array  The decoded JSON response
  201.      *
  202.      * @since   12.3
  203.      * @throws  RuntimeException
  204.      */
  205.     public function getContributees($user, $entities = null, $skip_status = null)
  206.     {
  207.         // Check the rate limit for remaining hits
  208.         $this->checkRateLimit('users', 'contributees');
  209.  
  210.         // Determine which type of data was passed for $user
  211.         if (is_numeric($user))
  212.         {
  213.             $data['user_id'] = $user;
  214.         }
  215.         elseif (is_string($user))
  216.         {
  217.             $data['screen_name'] = $user;
  218.         }
  219.         else
  220.         {
  221.             // We don't have a valid entry
  222.             throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
  223.         }
  224.  
  225.         // Set the API path
  226.         $path = '/users/contributees.json';
  227.  
  228.         // Check if entities is specified
  229.         if (!is_null($entities))
  230.         {
  231.             $data['include_entities'] = $entities;
  232.         }
  233.  
  234.         // Check if skip_status is specified
  235.         if (!is_null($skip_status))
  236.         {
  237.             $data['skip_status'] = $skip_status;
  238.         }
  239.  
  240.         // Send the request.
  241.         return $this->sendRequest($path, 'GET', $data);
  242.     }
  243.  
  244.     /**
  245.      * Method to get an array of users who can contribute to the specified account.
  246.      *
  247.      * @param   mixed    $user         Either an integer containing the user ID or a string containing the screen name.
  248.      * @param   boolean  $entities     Set to true to return IDs as strings, false to return as integers.
  249.      * @param   boolean  $skip_status  When set to either true, t or 1 statuses will not be included in the returned user objects.
  250.      *
  251.      * @return  array  The decoded JSON response
  252.      *
  253.      * @since   12.3
  254.      * @throws  RuntimeException
  255.      */
  256.     public function getContributors($user, $entities = null, $skip_status = null)
  257.     {
  258.         // Check the rate limit for remaining hits
  259.         $this->checkRateLimit('users', 'contributors');
  260.  
  261.         // Determine which type of data was passed for $user
  262.         if (is_numeric($user))
  263.         {
  264.             $data['user_id'] = $user;
  265.         }
  266.         elseif (is_string($user))
  267.         {
  268.             $data['screen_name'] = $user;
  269.         }
  270.         else
  271.         {
  272.             // We don't have a valid entry
  273.             throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
  274.         }
  275.  
  276.         // Set the API path
  277.         $path = '/users/contributors.json';
  278.  
  279.         // Check if entities is specified
  280.         if (!is_null($entities))
  281.         {
  282.             $data['include_entities'] = $entities;
  283.         }
  284.  
  285.         // Check if skip_status is specified
  286.         if (!is_null($skip_status))
  287.         {
  288.             $data['skip_status'] = $skip_status;
  289.         }
  290.  
  291.         // Send the request.
  292.         return $this->sendRequest($path, 'GET', $data);
  293.     }
  294.  
  295.     /**
  296.      * Method access to Twitter's suggested user list.
  297.      *
  298.      * @param   boolean  $lang  Restricts the suggested categories to the requested language.
  299.      *
  300.      * @return  array  The decoded JSON response
  301.      *
  302.      * @since   12.3
  303.      */
  304.     public function getSuggestions($lang = null)
  305.     {
  306.         // Check the rate limit for remaining hits
  307.         $this->checkRateLimit('users', 'suggestions');
  308.  
  309.         // Set the API path
  310.         $path = '/users/suggestions.json';
  311.  
  312.         $data = array();
  313.  
  314.         // Check if entities is true
  315.         if ($lang)
  316.         {
  317.             $data['lang'] = $lang;
  318.         }
  319.  
  320.         // Send the request.
  321.         return $this->sendRequest($path, 'GET', $data);
  322.     }
  323.  
  324.     /**
  325.      * method to access the users in a given category of the Twitter suggested user list.
  326.      *
  327.      * @param   string   $slug  The short name of list or a category.
  328.      * @param   boolean  $lang  Restricts the suggested categories to the requested language.
  329.      *
  330.      * @return  array  The decoded JSON response
  331.      *
  332.      * @since   12.3
  333.      */
  334.     public function getSuggestionsSlug($slug, $lang = null)
  335.     {
  336.         // Check the rate limit for remaining hits
  337.         $this->checkRateLimit('users', 'suggestions/:slug');
  338.  
  339.         // Set the API path
  340.         $path = '/users/suggestions/' . $slug . '.json';
  341.  
  342.         $data = array();
  343.  
  344.         // Check if entities is true
  345.         if ($lang)
  346.         {
  347.             $data['lang'] = $lang;
  348.         }
  349.  
  350.         // Send the request.
  351.         return $this->sendRequest($path, 'GET', $data);
  352.     }
  353.  
  354.     /**
  355.      * Method to access the users in a given category of the Twitter suggested user list and return
  356.      * their most recent status if they are not a protected user.
  357.      *
  358.      * @param   string  $slug  The short name of list or a category.
  359.      *
  360.      * @return  array  The decoded JSON response
  361.      *
  362.      * @since   12.3
  363.      */
  364.     public function getSuggestionsSlugMembers($slug)
  365.     {
  366.         // Check the rate limit for remaining hits
  367.         $this->checkRateLimit('users', 'suggestions/:slug/members');
  368.  
  369.         // Set the API path
  370.         $path = '/users/suggestions/' . $slug . '/members.json';
  371.  
  372.         // Send the request.
  373.         return $this->sendRequest($path);
  374.     }
  375. }

Documentation generated on Tue, 19 Nov 2013 15:16:41 +0100 by phpDocumentor 1.4.3