Location: PHPKode > scripts > Colour Lovers PHP > brianhaveri-Colour-Lovers-PHP-f9030cb/ColourLovers.php
<?php

/**
 * --------------------------------------------------
 * PHP Client Library for the COLOURlovers API
 *  
 * @author Brian Haveri
 * @link http://github.com/brianhaveri/Colour-Lovers-PHP
 * @license MIT License http://en.wikipedia.org/wiki/MIT_License
 * 
 * Related COLOURlovers API documentation: http://www.colourlovers.com/api
 * --------------------------------------------------
 */
class ColourLovers {

	/**
	 * --------------------------------------------------
	 * Class variables defining default behavior
	 * You can change these (optional)
	 * --------------------------------------------------
	 */
	private $_defaultResponseFormat = 'xml'; // xml or json
	private $_resultType = 'array'; // array, object, or raw (JSON or XML response directly from server)
	private $_convertResponse = TRUE; // TRUE or FALSE
	
	
	/**
	 * --------------------------------------------------
	 * Don't change these
	 * --------------------------------------------------
	 */
	private $_apiUrl = 'http://www.colourlovers.com/api/'; // Root API address including trailing slash
	private $_validResponseFormats = array('xml', 'json');
	private $_validResultTypes = array('array', 'object', 'raw');
	private $_lastRequest = NULL;
	
	
	/**
	 * --------------------------------------------------
	 * Provides access to _resultType
	 * @param string $type
	 * --------------------------------------------------
	 */
	public function set_result_type($type) {
		if(in_array($type, $this->_validResultTypes)) {
			$this->_resultType = strtolower($type);
		}
	}
	
	
	/**
	 * --------------------------------------------------
	 * Returns the last request submittd to the API
	 * @return string
	 * --------------------------------------------------
	 */
	public function last_request() {
		return $this->_lastRequest;
	}

	
	/**
	 * --------------------------------------------------
	 * Query colors
	 * @param array $query
	 * @return object
	 * --------------------------------------------------
	 */
	public function colors($query=array()) {
		return $this->_callMethod(__FUNCTION__, $query);
	}
	
	
	/**
	 * --------------------------------------------------
	 * Query new colors
	 * @param array $query
	 * @return object
	 * --------------------------------------------------
	 */
	public function colors_new($query=array()) {
		return $this->_callMethod(__FUNCTION__, $query);
	}
	
	
	/**
	 * --------------------------------------------------
	 * Query top colors
	 * @param array $queryhttp://www.colourlovers.com/api
	 * @return object
	 * --------------------------------------------------
	 */
	public function colors_top($query=array()) {
		return $this->_callMethod(__FUNCTION__, $query);
	}
	
	
	/**
	 * --------------------------------------------------
	 * Query random colors
	 * @return object
	 * --------------------------------------------------
	 */
	public function colors_random() {
		return $this->_callMethod(__FUNCTION__, array());
	}
	
	
	/**
	 * --------------------------------------------------
	 * Query one color
	 * @param array $query
	 * @return object
	 * --------------------------------------------------
	 */
	public function color($query) {
		list($call, $args) = $this->_singleQuery('hex', $query);
		return $this->_callMethod(__FUNCTION__.$call, $args);
	}
	
	
	/**
	 * --------------------------------------------------
	 * Query palettes
	 * @param array $query
	 * @return object
	 * --------------------------------------------------
	 */
	public function palettes($query=array()) {
		return $this->_callMethod(__FUNCTION__, $query);
	}
	
	
	/**
	 * --------------------------------------------------
	 * Query new palettes
	 * @param array $query
	 * @return object
	 * --------------------------------------------------
	 */
	public function palettes_new($query=array()) {
		return $this->_callMethod(__FUNCTION__, $query);
	}
	
	
	/**
	 * --------------------------------------------------
	 * Query top palettes
	 * @param array $query
	 * @return object
	 * --------------------------------------------------
	 */
	public function palettes_top($query=array()) {
		return $this->_callMethod(__FUNCTION__, $query);
	}
	
	
	/**
	 * --------------------------------------------------
	 * Query random palettes
	 * @return object
	 * --------------------------------------------------
	 */
	public function palettes_random() {
		return $this->_callMethod(__FUNCTION__, array());
	}
	
	
	/**
	 * --------------------------------------------------
	 * Query one palette
	 * @param array $query
	 * @return object
	 * --------------------------------------------------
	 */
	public function palette($query) {
		list($call, $args) = $this->_singleQuery('id', $query);
		return $this->_callMethod(__FUNCTION__.$call, $args);
	}
	
	
	/**
	 * --------------------------------------------------
	 * Query patterns
	 * @param array $query
	 * @return object
	 * --------------------------------------------------
	 */
	public function patterns($query=array()) {
		return $this->_callMethod(__FUNCTION__, $query);
	}
	
	
	/**
	 * --------------------------------------------------
	 * Query new palettes
	 * @param array $query
	 * @return object
	 * --------------------------------------------------
	 */
	public function patterns_new($query=array()) {
		return $this->_callMethod(__FUNCTION__, $query);
	}
	
	
	/**
	 * --------------------------------------------------
	 * Query top palettes
	 * @param array $query
	 * @return object
	 * --------------------------------------------------
	 */
	public function patterns_top($query=array()) {
		return $this->_callMethod(__FUNCTION__, $query);
	}
	
	
	/**
	 * --------------------------------------------------
	 * Query random palettes
	 * @return object
	 * --------------------------------------------------
	 */
	public function patterns_random() {
		return $this->_callMethod(__FUNCTION__, array());
	}
	
	
	/**
	 * --------------------------------------------------
	 * Query one pattern
	 * @param array $query
	 * @return object
	 * --------------------------------------------------
	 */
	public function pattern($query) {
		list($call, $args) = $this->_singleQuery('id', $query);
		return $this->_callMethod(__FUNCTION__.$call, $args);
	}
	
	
	/**
	 * --------------------------------------------------
	 * Query lovers
	 * @param array $query
	 * @return object
	 * --------------------------------------------------
	 */
	public function lovers($query=array()) {
		return $this->_callMethod(__FUNCTION__, $query);
	}
	
	
	/**
	 * --------------------------------------------------
	 * Query new lovers
	 * @param array $query
	 * @return object
	 * --------------------------------------------------
	 */
	public function lovers_new($query=array()) {
		return $this->_callMethod(__FUNCTION__, $query);
	}
	
	
	/**
	 * --------------------------------------------------
	 * Query top lovers
	 * @param array $query
	 * @return object
	 * --------------------------------------------------
	 */
	public function lovers_top($query=array()) {
		return $this->_callMethod(__FUNCTION__, $query);
	}
	
	
	/**
	 * --------------------------------------------------
	 * Query one lover
	 * @param array $query
	 * @return object
	 * --------------------------------------------------
	 */
	public function lover($query) {
		list($call, $args) = $this->_singleQuery('username', $query);
		return $this->_callMethod(__FUNCTION__.$call, $args);
	}
	
	
	/**
	 * --------------------------------------------------
	 * Query stats for colors
	 * @param array $query
	 * @return object
	 * --------------------------------------------------
	 */
	public function stats_colors($query=array()) {
		return $this->_callMethod(__FUNCTION__, $query);
	}
	
	
	/**
	 * --------------------------------------------------
	 * Query stats for palettes
	 * @param array $query
	 * @return object
	 * --------------------------------------------------
	 */
	public function stats_palettes($query=array()) {
		return $this->_callMethod(__FUNCTION__, $query);
	}
	
	
	/**
	 * --------------------------------------------------
	 * Query stats for patterns
	 * @param array $query
	 * @return object
	 * --------------------------------------------------
	 */
	public function stats_patterns($query=array()) {
		return $this->_callMethod(__FUNCTION__, $query);
	}
	
	
	/**
	 * --------------------------------------------------
	 * Query stats for lovers
	 * @param array $query
	 * @return object
	 * --------------------------------------------------
	 */
	public function stats_lovers($query=array()) {
		return $this->_callMethod(__FUNCTION__, $query);
	}
	
	
	/**
	 * --------------------------------------------------
	 * Calls the appropriate API method
	 * @param string $method
	 * @param array $query
	 * @return object
	 * --------------------------------------------------
	 */
	private function _callMethod($method, $query=array()) {
		$request = $this->_getRequest($method, $query);
		$response = $this->_getResponse($request);
		
		// _convertResponse() can only handle
		// formats identified in _validFormats
		$format = $this->_defaultResponseFormat;
		if(is_array($query) && array_key_exists('format', $query)) {
			if(in_array($query['format'], $this->_validResponseFormats)) {
				$format = $query['format'];
			}
		}
		
		if($this->_resultType !== 'raw') {
			$response = $this->_convertResponse($format, $response);
		}
		return $response;
	}
	
	
	/**
	 * --------------------------------------------------
	 * Performs the API query
	 * @param string $request
	 * @return string
	 * --------------------------------------------------
	 */
	private function _getResponse($request) {
		$options = array(
			CURLOPT_URL => $request,
			CURLOPT_RETURNTRANSFER => TRUE,
			CURLOPT_USERAGENT => __CLASS__.' PHP Client Library'
		);
		$ch = curl_init();
		curl_setopt_array($ch, $options);
		$query = curl_exec($ch);
		$this->_lastRequest = $request;
		curl_close($ch);
		return $query;
	}
	
	
	/**
	 * --------------------------------------------------
	 * Converts the API response into an object
	 * @param string $response
	 * @return object|array
	 * --------------------------------------------------
	 */
	private function _convertResponse($format, $response) {
		switch($format) {
			case 'json': return $this->_convertResponseJSON($response);
			case 'xml': return $this->_convertResponseXML($response);
		}
		return FALSE;
	}
	
	
	/**
	 * --------------------------------------------------
	 * Converts a JSON response
	 * @param string $response
	 * @return object|array
	 * --------------------------------------------------
	 */
	private function _convertResponseJSON($response) {
		$returnArray = FALSE;
		if($this->_resultType === 'array') {
			$returnArray = TRUE;
		}
		return json_decode($response, $returnArray);
	}
	
	
	/**
	 * --------------------------------------------------
	 * Converts a XML response into a SimpleXML object
	 * @param string $response
	 * @return object|array
	 * --------------------------------------------------
	 */
	private function _convertResponseXML($response) {
		$simple = simplexml_load_string($response, 'SimpleXMLElement', LIBXML_NOCDATA);
		if($this->_resultType === 'array') {
			return $this->_simpleXMLToArray($simple);
		}
		return $simple;
	}
	
	
	/**
	 * --------------------------------------------------
	 * Recursively finds any objects and converts them to non-objects
	 * This could be carved out into a separate class
	 * @param mixed $element
	 * @return mixed
	 * --------------------------------------------------
	 */
	private function _simpleXMLToArray($element) {
		$out = $element;
		if(is_object($element) || is_array($element)) {
			if(count((array) $element) > 0) {
				$out = array();
				$arr = (array) $element;
				foreach($arr as $k=>$v) {
					$out[$k] = $this->_simpleXMLToArray($v);
				}
				return $out;
			}
			return NULL;
		}
		return $out;
	}									
	
	
	/**
	 * --------------------------------------------------
	 * Generates a request string
	 * @param string $method
	 * @param array $query
	 * @return string
	 * --------------------------------------------------
	 */
	private function _getRequest($method, $query=array()) {
		$out = array(
			$this->_apiUrl,
			$this->_convertMethod($method)
		);
		if(is_array($query) && count($query) > 0) {
			$out[] = '?';
			$out[] = http_build_query($query);
		}
		return join('', $out);
	}
	
	
	/**
	 * --------------------------------------------------
	 * Converts a method name into the API's format
	 * Ex: color_random => color/random
	 * @param string $method
	 * @return string
	 * --------------------------------------------------
	 */
	private function _convertMethod($method) {
		return str_replace('_', '/', $method);
	}
	
	
	/**
	 * --------------------------------------------------
	 * Turns a query into the correct format for singular methods (color, palette, pattern, lover)
	 * @param array|string $query
	 * @return array
	 * --------------------------------------------------
	 */
	private function _singleQuery($keyToFind, $query) {
		if(is_array($query) && array_key_exists($keyToFind, $query)) {
			$out = array('/'.$query[$keyToFind]);
			unset($query[$keyToFind]);
			$out[] = $query;
			return $out;
		}
		else {
			$query = (string) $query;
			return array('/'.$query, array());
		}
		return array(NULL, NULL);
	}
}

?>
Return current item: Colour Lovers PHP