Bitly API Class

bitly.class.php

<?php

	/*
	 * ----------------------
	 * bitly.class.php
	 * ----------------------
	 * 
	 * Bitly class used for calling all the different API functions provided by the Bitly API.
	 * 
	 * Author: Alex Saunders
	 * Email: [email protected]
	 * Edits by: Kyle Harrison <[email protected]>
	 * Date Created: December 19, 2011
	 * Date Updated: December 20, 2011
	 * Version: 1.5
	 * 
	 */	
	
	class Bitly {
		
		// Bitly Username
		private $username = 'YOUR_BITLY_USERNAME';
		
		// Bitly API Key
		private $apiKey = 'YOUR_API_KEY';
		
		// Bitly API URL
		private $api = 'http://api.bitly.com/v3/';
		
		// stored request
		private $request	= null;
		
		private $service	= null;
		private $format		= null;
		private $encodeformat=null;
		private $url		= null;
		private $domain		= null;
		
		// Store the return data for later usage
		public $data		= null;
		
		// Valid return format types
		private $formats = array(
			"txt",
			"json",
			"xml",
			"serial",
			"array"
		);
		
		// Valid bitly formats
		private $encodeformats = array(
			"txt",
			"json",
			"xml"
		);
		
		// Valid encoding domains
		private $domains = array(
			"bit.ly",
			"bitly.com",
			"j.mp"
		);
		
		// Valid Services
		private $services = array(
			"shorten",
			"expand"
		);
		
		// Nullary Constructor
		public function __construct() { }
		
		/**
		 * Create an API request of the given service with the paramaters provided.
		 * @param String $service The name of the API service you would like to call.
		 * @param String $params The paramaters the service depends on.
		 */
		public function request( $service = null, $params = null ) {
			
			// Set the service, using this function can override the set service
			if($service == null && $this->service == null) return false;
			if($service == null && $this->service != null) $service = $this->service;
			
			
			// Set the request header with api credentials
			//$request = $this->api . $service . '?login=' . $this->username . '&apiKey=' . $this->apiKey;
			$query[] = "login=".$this->username;
			$query[] = "apiKey=".$this->apiKey;
			
			if($params != null) {
				// Go through the paramaters array, and add the key/value pair to the request.
				foreach( $params as $key => $value ) {
					$query[] = $key . '=' . $value;
				}
			} else {
				
				// We need a URL, if one is not provided at all, return false
				if($this->url == null) return false;
				
				switch($service) {
					default:
					case "shorten":
						$query[] = "longUrl=".$this->url;
						(($this->encodeformat != null) ? $query[] = "format=".$this->encodeformat : null );
						(($this->domain != null) ? $query[] = "domain=".$this->domain : null );
						break;
					case "expand":
						$query[] = "shortUrl=".$this->url;
						(($this->encodeformat != null) ? $query[] = "format=".$this->encodeformat : null );
						break;
				}
				
			}
			
			$this->request = $this->api . $service . '?' . implode("&", $query);
			
			
			
			// Blast the request to curl_get and return the response.
			// curl_get returns an associative array from the json response the Bitly API returns.
			// So this function will return said associative array.
			$this->data = $this->curl_get( $this->request );
			
			if($this->format == null) return $this->data;
			else return $this->returnWithFormat($this->data);
		}
		
		/**
		 * Sets the domain to use (bit.ly, bitly.com, j.mp at present time. These are the ONLY useable values, returns false if otherwise)
		 */
		public function domain($domain = null) {
			if(
				($domain == null || trim($domain) == "" )
				||
				!in_array(strtolower($domain), $this->domains)
			) return false;
			
			$this->domain = $domain;
			
			return true;
		}
		
		/**
		 * Sets the encoding format of the returned data
		 * @param String $format The returned data encoding format, must be within the valid formats, returns false if not.
		 */
		public function format($format = null) {
			if(
				($format == null || trim($format) == "") 
				|| 
				!in_array(strtolower($format), $this->formats)
			) return false;
			
			// These conditions require special return formatting
			if($format == "array" || $format == "serial") {
				$this->format = $format;
				$this->encodeformat = "json";
			} else {
				$this->format = $format;
				$this->encodeformat = $format;
			}
			
			return true;
		}
		
		/**
		 * Returns the data as pure text
		 */
		public function as_txt() {
			return $this->format("txt");
		}
		
		/**
		 * Returns the data as encoded JSON
		 */
		public function as_json() {
			return $this->format("json");
		}
		
		/**
		 * Returns the data as XML
		 */
		public function as_xml() {
			return $this->format("xml");
		}
		
		/**
		 * Returns the data as a serialized php object 
		 */
		public function as_serial() {
			return $this->format("serial");
		}
		
		/**
		 * Returns the data as an array of php objects
		 */
		public function as_array() {
			return $this->format("array");
		}
		
		/**
		 * Service Setter
		 * @param String $service set a service of bitly to be used. This is strict, if service does not exist, it will not be set.
		 * @return bool
		 */
		public function service($service = null) {
			if($service == null || trim($service) == "") return false;
			if(!in_array(strtolower($service), $this->services)) return false;
			
			$this->service = $service;
			
			return true;
		}
		
		/**
		 * Sets the working URL
		 * @param mixed $url A valid URL, will be checked for validity. Returns false if unusable
		 */
		public function url($url) {
			if($url == null || trim($url) == "") return false;
			if(!preg_match("((mailto\:|(news|(ht|f)tp(s?))\://){1}\S+)", $url)) return false;
			
			$this->url = urlencode($url);
			
			return true;
		}
		
		/**
		 * Overrides API Credentials
		 * @param mixed $username your Bit.ly username
		 * @param mixed $key your Bit.ly API Key
		 * @return bool 
		 */
		public function myapi($username = null, $key = null) {
			if( 
				($username == null || trim($username) == "") 
				||
				($key == null || trim($key) == "") 
			) return false;
			
			$this->username	= $username;
			$this->apiKey	= $key;
			
			return true;
		}
		
		/**
		 * CURL to the Bitly API.
		 * @param String $url The URL to query the Bitly API with.
		 */
		private function curl_get( $url ) {
			// Initialize the curl session.
			$curl = curl_init();
			
			// Set Curl Options
			$options = array(
				CURLOPT_URL		=>	$url,
				CURLOPT_RETURNTRANSFER	=>	true,
				CURLOPT_CONNECTTIMEOUT	=>	10
			);
			
			// Set curl options
			curl_setopt_array( $curl, $options );
			
			// Execute the curl request.
			$response = curl_exec( $curl );
			
			// Close curl session.
			curl_close( $curl );
			
			// Return the CURL response.
			// Bitly returns JSON or XML. JSON By default.
			// Decoding the response is up to the user of the class.
			return $response;
		}
		
		/**
		 * Grabs the raw or formatted Bit.ly return data
		 * @param bool $useFormat if set to true, will return with the data formatted by request
		 */
		public function fetch($useFormat = false) {
			if($useFormat == false)	return $this->data;
			else return $this->returnWithFormat($this->data);
		}
		
		/**
		 * Returns raw bit.ly data as the requested format
		 */
		private function returnWithFormat($data) {
			switch($this->format) {
				case "array":
					return json_decode($this->data);
					break;
				case "serial":
					return serialize(json_decode($this->data));
					break;
				default:
					return $this->data;
				break;
			}
		}
		
	}