PHP interface for the DecentUrl API

<?php

/*

    PHP interface for the DecentUrl service
        by Matthew D (project-2501.net)

    Based on the Python script by Ben Hoyt
    See http://decenturl.com/tools#api

    Example:


    <?php

        require_once("decenturl_interface.php");

        //  returns: "youtube/medieval-helpdesk-with-english"
        DecentUrl::Get('http://youtube.com/watch?v=pQHX-SjgQvQ');

        //  returns: "http://youtube.com/watch?v=pQHX-SjgQvQ"
        DecentUrl::Resolve('youtube/medieval-helpdesk-with-english');

        //  returns: array("DecentURL - Making ugly URLs decent", "making-ugly-urls-decent")
        DecentUrl::Title('http://decenturl.com/');

        //  returns: "brush.co.nz"
        DecentUrl::Domain('http://brush.co.nz');

        //  throws a DecentUrlException("resolve request failed:  notfound")
        DecentUrl::Resolve('baddy');
    ?>

*/

    class DecentUrlException extends Exception {}
    class DecentUrl
    {
        const BASE_URL = 'http://decenturl.com/api-';

        //  Create or get decent URL from given ugly one and return it
        public static function Get($url, $title="")
        {
            $response = self::Request("get", array("u" => $url, "t" => $title), 2);

            return $response[0];
        }

        //  Resolve decent URL and return ugly original
        public static function Resolve($decentUrl)
        {
            $response = self::Request("resolve", array("d" => $decentUrl), 2);

            return $response[0];
        }

        //  Return tuple of full <title> and decent title for given URL
        public static function Title($url, $maxLength = 1000)
        {
            return self::Request("title", array("u" => $url, "l" => $maxLength), 2);
        }

        //  Return URL's base domain
        public static function Domain($url, $maxLength = 1000)
        {
            $response = self::Request("domain", array("u" => $url, "l" => $maxLength), 1);

            return $response[0];
        }

        //  Call generic DecentUul API function, throw DecentUrlException if not ok
        private static function Request($type, $parameters, $expectedResponseSize = false)
        {
            //  Take a key value pair, and join them together, making sure to
            //  urlencode the value
            foreach($parameters as $key => $value)
            {
                $parameters[$key] = sprintf("%s=%s", $key, urlencode($value));
            }

            $queryString = implode("&", array_values($parameters));

            $url = sprintf("%s%s?%s", self::BASE_URL, $type, $queryString);

            $contents = file_get_contents($url);

            $response = json_decode($contents);

            if($response == null)
            {
                throw new DecentUrlException("Response was not valid JSON");
            }

            if($response[0] != "ok")
            {
                throw new DecentUrlException("{$type} request failed:  {$response[0]}");
            }

            //  Remove the first element (which we proved was 'ok' above)
            $trimedResponse = array_slice($response, 1);

            //  If requested, we check to see that the response is the correct
            //  size.
            if(($expectedResponseSize !== false) && (count($trimedResponse) != $expectedResponseSize))
            {
                throw new DecentUrlException("{$type} request failed:  expected {$expectedResponseSize} fields, got " . count($trimedResponse));
            }

            return $trimedResponse;
        }
    }

?>