<?php
/**
 * class RestRequest 
 * 
 * A class to simplify REST based requests.
 * The RestRequest class has the following features:
 * 	- Can handle Basic Authentication requests
 * 	- Allows for adding custom header information for special requests
 * 	
 * Example Usage:
 * <code>
 *   // EXAMPLE 1: Request the Public Timeline from Twitter
 *   // NOTE: does not require authentication
 *   $rest = new RestRequest();
 *   $result = $rest->request("http://twitter.com/statuses/public_timeline.xml");
 * 
 *   // EXAMPLE 2: Retrieve your current Timeline from Twitter
 *   // NOTE: This request requires Basic Authentication
 *   $username = "YOUR USERNAME";
 *   $password = "YOUR PASSWORD";
 *   $rest = new RestRequest($username, $password);
 *   $result = $rest->request("http://twitter.com/statuses/friends_timeline.xml");
 * 
 *   // EXAMPLE 3: Post an update to Twitter
 *   // NOTE: This request requires Basic Authentication and demonstrates
 *   // making a post request.
 *   $username = "YOUR USERNAME";
 *   $password = "YOUR PASSWORD";
 *   $rest = new RestRequest($username, $password);
 *   $url = "http://twitter.com/statuses/update.xml";
 *   $post_data = array("status" => "Nothing important happened today.");
 *   $rest->setPostData($post_data);
 *   $result = $rest->request($url, "POST");
 * </code>
 * 
 * @author	Jamie Allison
 * @copyright	Jamie Allison 2009  
 *
 */
class RestRequest
{
	/**
	 * a base64 encoded string containing a username and password
	 */
	protected $authentication;
 
	/**
	 * an array of header strings
	 */
	protected $header_data;
 
	/**
	 * associative array of data used for POST requests
	 */
	protected $post_data;
 
	/**
	 * Class Constructor
	 * 
	 * Initializes class allowing you to pass in an optional 
	 * username and password for authenticated requests.
	 * 
	 * @param String [optional] username
	 * @param String [optional] password
	 * @return void
	 */
	public function __construct($username="", $password="")
	{
		$this->authentication = null;
		$this->header_data = array();
		$this->post_data = array();
 
		if ($username && $password){
			$this->setAuthentication($username, $password);
		}
	}
 
	/**
	 * Sets data used for Basic Authentication requests
	 * 
	 * @param String [required] username
	 * @param String [required] password
	 * @return void
 	 */
	public function setAuthentication($username, $password)
	{
		$this->authentication = base64_encode("$username:$password");
	}
 
	/**
	 * Append a header string to the request
	 * 
	 * When making a POST request, the class automatically
	 * appends the: Content-type: application/x-www-form-urlencoded header 
	 * to the request.
	 *  
	 * 
	 * @param String [required] A header string to add to the request
	 * @return void
	 */
	public function appendHeader($data)
	{
		// strip away any trailing 
 characters from the string
		$data = preg_replace('#
$#', '', $data);
 
		$this->header_data[] = $data;
	}
 
	/**
	 * Add data to a POST request
	 * 
	 * Accepts and associative array of data to pass to a POST request.
	 * NOTE: When a request is made the post data will be url encoded
	 * 
	 * @param Array [required] Associative Array of POST data
	 * @return void
	 */
	public function setPostData($data)
	{
		$this->post_data = $data;
	}
 
	/**
	 * Makes an HTTP request and returns the result as a string
	 * 
	 * @param String [required] URL to request
	 * @param String [optional] Method used to make request defaults to GET
	 * 
	 * @return String The result of the Request. 
	 */
	public function request($url, $method="GET")
	{
		// build a context array to describe this request.
		$context_opts = array(
			'http' => array(
				'method' => $method
			)
		);
 
		// Set up authentication header 
		if($this->authentication != null){
			$this->appendHeader("Authorization: Basic " . $this->authentication);
		}
 
		// If this is a POST or a PUT request then set up post data,
		// if it's supplied.		
		if ( (strtoupper($method) == "POST" || strtoupper($method) == "PUT")){
			if ($this->post_data){
				$this->appendHeader("Content-type: application/x-www-form-urlencoded");
				$context_opts['http']['content'] = http_build_query($this->post_data);
			}
		}
 
		// format header data for the request
		if($this->header_data){
			$context_opts['http']['header'] = implode("
", $this->header_data);
			$context_opts['http']['header'] .= "
";
		}
 
		// create a stream context and make the request.
		$context = stream_context_create($context_opts);
		$handle = fopen ( $url, 'r', false,$context);
 
		$content = stream_get_contents($handle);
 
		fclose($handle);
 
		return $content;
 
	}
 
}
 
?>