<?php
/**
 * PHP5 Bindings for carma.org API
 *
 * If you have the json extension, this client class will default to using it to
 * retrieve data and convert it to PHP types. Otherwise, SimpleXML will be used
 * to parse the data.  Call results will be cached locally.
 *
 * Released under MIT License
 * @author Oscar Merida
 *
 * REQUIREMENTS
 *   1. PHP 5.2 w/SimpleXML support
 *
 * USAGE:
 *
 * $carma = CarmaClient::create();
 *
 * TODO: implement caching
 * $carma->cache_path = '/carma.www/tmp/';
 *
 */
class CarmaClient
{
    private $carma_url = 'http://carma.org/api/1.2/';
    private $decoder;
    private $fetcher;
    private $http_params = array();

    /**
     * Path to store cached data.
     * $client->cache_path = '/tmp/';
     * @var string
     */
    private $cache_path;

    public function __construct()
    {
        $this->decoder = CarmaDecoderFactory::create();
        $this->fetcher = CarmaFetcherFactory::create();

        if (isset($this->decoder->http_params))
        {
            $this->http_params = array_merge($this->http_params, $this->decoder->http_params);
        }

        if ($tmp = sys_get_temp_dir())
        {
            // make sure a trailing dir is there
            $this->cache_path = $tmp;
        }
    }

    public function __set($field, $val)
    {
        switch ($field)
        {
            case 'cache_path':

                try
                {
                    $this->setCachePath($val);
                }
                catch (Excetion $e)
                {
                    throw $e;
                }

            break;

        }
    }

    public function __get($field)
    {
        return $this->$field;
    }

    private function setCachePath($val)
    {
        if (is_dir($val))
        {
            $this->cache_path = $val;
        }
        else
        {
            throw new Exception("Not a valid directory: ". $val);
        }
    }

    /**
     * return details for a plant by either its name and/oror numeric id
     * Uses arrays as parameters to emulate named parameters, only one is required
     * Ex:
     *   $plant = $carma->getPlant('id' => 25097);
     * @param mixed $input
     * @return array of matching Plant as a stdObject
     */
    public function getPlant($param)
    {
        $url = $this->buildUrl('getPlant', $param);
        return $this->callApi($url);
    }

    /**
     * Returns details for a plant by one or more params
     * Uses arrays as parameters to emulate named parameters, only one is required
     * Ex:
     *   $carma->getCompany(array('id' => 656, 'stock' => 'AEP, 'name' => 'AMERICAN ELEC PWR/BUCKEYE PWR'));
     *   $carma->getCompany(array('id' => 656'));
     *   $carma->getCompany(array('stock' => 'AEP));
     *
     * @param array
     * @return array of matching company as stdObject
     */
    public function getCompany($params)
    {
        // TODO: param checking
        $url = $this->buildUrl('getCompany', $params);
        return $this->callApi($url);
    }

    /**
     * Searches for plants based on one or more parameters.
     * Uses arrays as parameters to emulate named parameters, only one is required
     * Ex:
     *   $carma->searchPlants(array('name' => 'American'));
     *   $carma->searchPlants(array('operating_company' => '5012'));
     *   $carma->searchPlants(array('zip' => '22030'));
     *   $carma->searchPlants(array('name' => 'American', 'zip' => '22030'));
     *   $carma->searchPlants(array('zip'  => '22030', 'color' => 'red'));
     * @param array $params
     * @return array of matching plants as stdObjects
     */
    public function searchPlants($params)
    {
        // TODO: param checking
        $url = $this->buildUrl('searchPlants', $params);
        return $this->callApi($url);
    }

    /**
     * Searches for companies based on one or more parameters.
     * Uses arrays as parameters to emulate named parameters, only one is required
     * Ex:
     *   $carma->searchCompanies(array('name' => 'American'));
     *   $carma->searchCompanies(array('parent_company' => '5012'));
     *   $carma->searchCompanies(array('location' => 6, 'color' => red));
     * @param array $params
     * @return array of matching companies as stdObjects
     */
    public function searchCompanies($params)
    {
        // TODO: param checking
        $url = $this->buildUrl('searchCompanies', $params);
        return $this->callApi($url);
    }

    /**
     * Searches for locations based on one or more parameters.
     * Uses arrays as parameters to emulate named parameters, only one is required
     * Ex:
     *    $carma->searchLocations(array('name' => 'Virginia', 'region_type' => '3'));
     * @param array $params
     * @return array of matching locations as stdObjects
     */
    public function searchLocations($params)
    {
        // TODO: param checking
        $url = $this->buildUrl('searchLocations', $params);
        return $this->callApi($url);
    }

    private function buildUrl($api_method, $params)
    {
        $url = $this->carma_url
             . $api_method
             . '?' . http_build_query(array_merge($this->http_params, $params));
        return $url;
    }

    private function callApi($url)
    {
        // TODO: add caching
        $result = $this->fetcher->get($url);
        $data = $this->decoder->decode($result);
        return $data;
    }
}

class CarmaDecoderFactory {

    /**
     * Returns a CarmaDecoder class based on underlying system capabilities.
     */
    static public function create()
    {
        if (function_exists('json_decode'))
        {
            return new CarmaDecoderJSON();
        }
        else
        {
            return new CarmaDecoderXML();
        }
    }
}

interface CarmaDecoder {
    /**
     * Decodes the input into a native php object.
     *
     * @param unknown_type $string
     */
    public function decode($string);
}

class CarmaDecoderJSON implements CarmaDecoder
{
    public $http_params = array('format' => 'json');

    public function decode($json_string)
    {
        return json_decode($json_string);
    }
}

class CarmaDecoderXML implements CarmaDecoder
{
    public $http_params = array('format' => 'xml');

    public function decode($xml_string)
    {
        $xml = new SimpleXMLElement($xml_string);

        $result = array();
        foreach ($xml as $xml_node)
        {
            $result[] = $this->toObject($xml)->item;
        }

        // convert to an array of regular objects
        return $result;
    }

    public function toObject($xml_node)
    {
        $toreplace="/(^|;)*O:[0-9]+:\"[^\"]+\":/i";
        $serialized = serialize($xml_node);
        $munged = preg_replace($toreplace, "\\1"."O:" . strlen('stdClass').":\"" . 'stdClass' ."\":", $serialized);
        $obj = unserialize($munged);
        return $obj;
    }
}

class CarmaFetcherFactory {
    /**
     * Returns a CarmaFetch class based on underlying system capabilities.
     */
    static public function create()
    {
        if (in_array('http', stream_get_wrappers()))
        {
            return new CarmaFetcher_Streams;
        }
    }
}
interface CarmaFetcher {

    /**
     * Retrieves data from the url
     *
     * @param string $url
     */
    public function get($url);

}

class CarmaFetcher_Streams implements CarmaFetcher {

    public function get($url)
    {
        return file_get_contents($url);
    }
}