/src/Joomla/Twitter/Users.php

<?php
/**
 * Part of the Joomla Framework Twitter Package
 *
 * @copyright  Copyright (C) 2005 - 2013 Open Source Matters, Inc. All rights reserved.
 * @license    GNU General Public License version 2 or later; see LICENSE
 */

namespace Joomla\Twitter;

/**
 * Twitter API Users class for the Joomla Framework.
 *
 * @since  1.0
 */
class Users extends Object
{
	/**
	 * Method to get up to 100 users worth of extended information, specified by either ID, screen name, or combination of the two.
	 *
	 * @param   string   $screen_name  A comma separated list of screen names, up to 100 are allowed in a single request.
	 * @param   string   $id           A comma separated list of user IDs, up to 100 are allowed in a single request.
	 * @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
	 * 								   metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags.
	 *
	 * @return  array  The decoded JSON response
	 *
	 * @since   1.0
	 * @throws  \RuntimeException
	 */
	public function getUsersLookup($screen_name = null, $id = null, $entities = null)
	{
		// Check the rate limit for remaining hits
		$this->checkRateLimit('users', 'lookup');

		$data = array();

		// Set user IDs and screen names.
		if ($id)
		{
			$data['user_id'] = $id;
		}

		if ($screen_name)
		{
			$data['screen_name'] = $screen_name;
		}

		if ($id == null && $screen_name == null)
		{
			// We don't have a valid entry
			throw new \RuntimeException('You must specify either a comma separated list of screen names, user IDs, or a combination of the two');
		}

		// Set the API path
		$path = '/users/lookup.json';

		// Check if string_ids is specified
		if (!is_null($entities))
		{
			$data['include_entities'] = $entities;
		}

		// Send the request.
		return $this->sendRequest($path, 'POST', $data);
	}

	/**
	 * Method to access the profile banner in various sizes for the user with the indicated screen_name.
	 *
	 * @param   mixed  $user  Either an integer containing the user ID or a string containing the screen name.
	 *
	 * @return  array  The decoded JSON response
	 *
	 * @since   1.0
	 * @throws  \RuntimeException
	 */
	public function getUserProfileBanner($user)
	{
		// Check the rate limit for remaining hits
		$this->checkRateLimit('users', 'profile_banner');

		// Set the API path
		$path = '/users/profile_banner.json';

		// Determine which type of data was passed for $user
		if (is_numeric($user))
		{
			$data['user_id'] = $user;
		}
		elseif (is_string($user))
		{
			$data['screen_name'] = $user;
		}
		else
		{
			// We don't have a valid entry
			throw new \RuntimeException('The specified username is not in the correct format; must use integer or string');
		}

		// Send the request.
		return $this->sendRequest($path, 'GET', $data);
	}

	/**
	 * Method used to search for users
	 *
	 * @param   string   $query     The search query to run against people search.
	 * @param   integer  $page      Specifies the page of results to retrieve.
	 * @param   integer  $count     The number of people to retrieve. Maximum of 20 allowed per page.
	 * @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 metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags.
	 *
	 * @return  array  The decoded JSON response
	 *
	 * @since   1.0
	 * @throws  \RuntimeException
	 */
	public function searchUsers($query, $page = 0, $count = 0, $entities = null)
	{
		// Check the rate limit for remaining hits
		$this->checkRateLimit('users', 'search');

		$data['q'] = rawurlencode($query);

		// Check if page is specified.
		if ($page > 0 )
		{
			$data['page'] = $page;
		}

		// Check if per_page is specified
		if ($count > 0)
		{
			$data['count'] = $count;
		}

		// Check if entities is specified.
		if (!is_null($entities))
		{
			$data['include_entities'] = $entities;
		}

		// Set the API path
		$path = '/users/search.json';

		// Send the request.
		return $this->sendRequest($path, 'GET', $data);
	}

	/**
	 * Method to get extended information of a given user, specified by ID or screen name as per the required id parameter.
	 *
	 * @param   mixed    $user      Either an integer containing the user ID or a string containing the screen name.
	 * @param   boolean  $entities  Set to true to return IDs as strings, false to return as integers.
	 *
	 * @return  array  The decoded JSON response
	 *
	 * @since   1.0
	 * @throws  \RuntimeException
	 */
	public function getUser($user, $entities = null)
	{
		// Check the rate limit for remaining hits
		$this->checkRateLimit('users', 'show');

		// Determine which type of data was passed for $user
		if (is_numeric($user))
		{
			$data['user_id'] = $user;
		}
		elseif (is_string($user))
		{
			$data['screen_name'] = $user;
		}
		else
		{
			// We don't have a valid entry
			throw new \RuntimeException('The specified username is not in the correct format; must use integer or string');
		}

		// Set the API path
		$path = '/users/show.json';

		// Check if entities is specified
		if (!is_null($entities))
		{
			$data['include_entities'] = $entities;
		}

		// Send the request.
		return $this->sendRequest($path, 'GET', $data);
	}

	/**
	 * Method to get an array of users that the specified user can contribute to.
	 *
	 * @param   mixed    $user         Either an integer containing the user ID or a string containing the screen name.
	 * @param   boolean  $entities     Set to true to return IDs as strings, false to return as integers.
	 * @param   boolean  $skip_status  When set to either true, t or 1 statuses will not be included in the returned user objects.
	 *
	 * @return  array  The decoded JSON response
	 *
	 * @since   1.0
	 * @throws  \RuntimeException
	 */
	public function getContributees($user, $entities = null, $skip_status = null)
	{
		// Check the rate limit for remaining hits
		$this->checkRateLimit('users', 'contributees');

		// Determine which type of data was passed for $user
		if (is_numeric($user))
		{
			$data['user_id'] = $user;
		}
		elseif (is_string($user))
		{
			$data['screen_name'] = $user;
		}
		else
		{
			// We don't have a valid entry
			throw new \RuntimeException('The specified username is not in the correct format; must use integer or string');
		}

		// Set the API path
		$path = '/users/contributees.json';

		// Check if entities is specified
		if (!is_null($entities))
		{
			$data['include_entities'] = $entities;
		}

		// Check if skip_status is specified
		if (!is_null($skip_status))
		{
			$data['skip_status'] = $skip_status;
		}

		// Send the request.
		return $this->sendRequest($path, 'GET', $data);
	}

	/**
	 * Method to get an array of users who can contribute to the specified account.
	 *
	 * @param   mixed    $user         Either an integer containing the user ID or a string containing the screen name.
	 * @param   boolean  $entities     Set to true to return IDs as strings, false to return as integers.
	 * @param   boolean  $skip_status  When set to either true, t or 1 statuses will not be included in the returned user objects.
	 *
	 * @return  array  The decoded JSON response
	 *
	 * @since   1.0
	 * @throws  \RuntimeException
	 */
	public function getContributors($user, $entities = null, $skip_status = null)
	{
		// Check the rate limit for remaining hits
		$this->checkRateLimit('users', 'contributors');

		// Determine which type of data was passed for $user
		if (is_numeric($user))
		{
			$data['user_id'] = $user;
		}
		elseif (is_string($user))
		{
			$data['screen_name'] = $user;
		}
		else
		{
			// We don't have a valid entry
			throw new \RuntimeException('The specified username is not in the correct format; must use integer or string');
		}

		// Set the API path
		$path = '/users/contributors.json';

		// Check if entities is specified
		if (!is_null($entities))
		{
			$data['include_entities'] = $entities;
		}

		// Check if skip_status is specified
		if (!is_null($skip_status))
		{
			$data['skip_status'] = $skip_status;
		}

		// Send the request.
		return $this->sendRequest($path, 'GET', $data);
	}

	/**
	 * Method access to Twitter's suggested user list.
	 *
	 * @param   boolean  $lang  Restricts the suggested categories to the requested language.
	 *
	 * @return  array  The decoded JSON response
	 *
	 * @since   1.0
	 */
	public function getSuggestions($lang = null)
	{
		// Check the rate limit for remaining hits
		$this->checkRateLimit('users', 'suggestions');

		// Set the API path
		$path = '/users/suggestions.json';

		$data = array();

		// Check if entities is true
		if ($lang)
		{
			$data['lang'] = $lang;
		}

		// Send the request.
		return $this->sendRequest($path, 'GET', $data);
	}

	/**
	 * method to access the users in a given category of the Twitter suggested user list.
	 *
	 * @param   string   $slug  The short name of list or a category.
	 * @param   boolean  $lang  Restricts the suggested categories to the requested language.
	 *
	 * @return  array  The decoded JSON response
	 *
	 * @since   1.0
	 */
	public function getSuggestionsSlug($slug, $lang = null)
	{
		// Check the rate limit for remaining hits
		$this->checkRateLimit('users', 'suggestions/:slug');

		// Set the API path
		$path = '/users/suggestions/' . $slug . '.json';

		$data = array();

		// Check if entities is true
		if ($lang)
		{
			$data['lang'] = $lang;
		}

		// Send the request.
		return $this->sendRequest($path, 'GET', $data);
	}

	/**
	 * Method to access the users in a given category of the Twitter suggested user list and return
	 * their most recent status if they are not a protected user.
	 *
	 * @param   string  $slug  The short name of list or a category.
	 *
	 * @return  array  The decoded JSON response
	 *
	 * @since   1.0
	 */
	public function getSuggestionsSlugMembers($slug)
	{
		// Check the rate limit for remaining hits
		$this->checkRateLimit('users', 'suggestions/:slug/members');

		// Set the API path
		$path = '/users/suggestions/' . $slug . '/members.json';

		// Send the request.
		return $this->sendRequest($path);
	}
}