repo_zf1/documentation/manual/en/module_specs/Zend_Service_ShortUrl.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.service.short-url">
    <title>Zend_Service_ShortUrl</title>

    <sect2 id="zend.service.short-url.intro">
        <title>Overview</title>

        <para>
            URL shorteners have exploded in popularity in the last several years, in large part due
            to the social nature of the web and the desire to share links.
            <classname>Zend_Service_ShortUrl</classname> provides an API for accessing a number of
            different URL shortener services, with the ability to both create short URLs as well as
            retrieve the original URL.
        </para>

        <para>
            Adapters provided include:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <classname>Zend_Service_ShortUrl_JdemCz</classname>, which accesses the <ulink
                        url="http://jdem.cz/">jdem.cz</ulink> service.
                </para>
            </listitem>

            <listitem>
                <para>
                    <classname>Zend_Service_ShortUrl_TinyUrlCom</classname>, which accesses the <ulink
                        url="http://tinyurl.com">tinyurl.com</ulink> service.
                </para>
            </listitem>

            <listitem>
                <para>
                    <classname>Zend_Service_ShortUrl_MetamarkNet</classname>, which accesses the <ulink
                        url="http://metamark.net/">metamark.net</ulink> service.
                </para>
            </listitem>

            <listitem>
                <para>
                    <classname>Zend_Service_ShortUrl_IsGd</classname>, which accesses the <ulink
                        url="http://is.gd">is.gd</ulink> service.
                </para>
            </listitem>

            <listitem>
                <para>
                    <classname>Zend_Service_ShortUrl_BitLy</classname>, which accesses the <ulink
                        url="http://bitly.com">bit.ly</ulink> service.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.service.short-url.quick-start">
        <title>Quick Start</title>

        <para>
            Using one of the URL shortener services is straightforward. Each URL shortener follows a
            simple interface that defines two methods: <methodname>shorten()</methodname> and
            <methodname>unshorten()</methodname>. Instantiate the class, and call the appropriate
            method.
        </para>

        <programlisting language="php"><![CDATA[
$tinyurl = new Zend_Service_ShortUrl_TinyUrlCom();

// Shorten a URL:
$short = $tinyurl->shorten('http://framework.zend.com/'); // http://tinyurl.com/rxtuq

// Inflate or unshorten a short URL:
$long  = $tinyurl->unshorten('http://tinyurl.com/rxtuq'); // http://framework.zend.com/
]]></programlisting>
    </sect2>

    <sect2 id="zend.service.short-url.methods">
        <title>Available Methods</title>

        <variablelist>
            <varlistentry id="zend.service.short-url.methods.shorten">
                <term>
                    <methodsynopsis>
                        <methodname>shorten</methodname>
                        <methodparam>
                            <funcparams>$url</funcparams>
                        </methodparam>
                    </methodsynopsis>
                </term>

                <listitem>
                    <para>
                        Takes the given <varname>$url</varname> and passes it to the service in
                        order to obtain a shortened URL.
                    </para>

                    <para>
                        If the provided <varname>$url</varname> is invalid, an exception will be
                        raised.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry id="zend.service.short-url.methods.unshorten">
                <term>
                    <methodsynopsis>
                        <methodname>unshorten</methodname>
                        <methodparam>
                            <funcparams>$shortenedUrl</funcparams>
                        </methodparam>
                    </methodsynopsis>
                </term>

                <listitem>
                    <para>
                        Takes the provided <varname>$shortenedUrl</varname> and passes it to the
                        service in order to obtain the original URL.
                    </para>

                    <para>
                        If the provided <varname>$shortenedUrl</varname> is invalid, an exception
                        will be raised.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry id="zend.service.short-url.methods.set-http-client">
                <term>
                    <methodsynopsis>
                        <methodname>setHttpClient</methodname>
                        <methodparam>
                            <funcparams>Zend_Http_Client $httpClient</funcparams>
                        </methodparam>
                    </methodsynopsis>
                </term>

                <listitem>
                    <para>
                        Use this method to set the HTTP client used for communicating with the
                        service.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry id="zend.service.short-url.methods.get-http-client">
                <term>
                    <methodsynopsis>
                        <methodname>getHttpClient</methodname>
                        <methodparam>
                            <funcparams></funcparams>
                        </methodparam>
                    </methodsynopsis>
                </term>

                <listitem>
                    <para>
                        Use this method to access the HTTP client attached to the service. By
                        default, this will lazy-load an instance of
                        <classname>Zend_Http_Client</classname> if no client is yet attached.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </sect2>

    <sect2 id="zend.service.short-url.bitly">
        <title>Additional Bit.ly Methods</title>

        <para>
            The bitly API require that authentication credentials be supplied as query arguments.
            To get started, you'll need a free bitly user account and apiKey. Signup at:
            <ulink url="http://http://bitly.com/a/sign_up">http://bitly.com/a/sign_up</ulink>
        </para>

        <para>
            bitly currently also supports the OAuth 2 draft specification. You could provide a
            generated OAuth access token to <classname>Zend_Service_ShortUrl_BitLy</classname>
            using <methodname>setOAuthAccessToken</methodname> or as constructor argument.
        </para>

        <programlisting language="php"><![CDATA[
$bitly = new Zend_Service_ShortUrl_BitLy('username','apiKey');

// Shorten a URL:
$short = $bitly->shorten('http://framework.zend.com/'); // http://bit.ly/15Oe0

// Inflate or unshorten a short URL:
$long  = $bitly->unshorten('http://bit.ly/15Oe0'); // http://framework.zend.com/
]]></programlisting>

        <variablelist>
            <varlistentry id="zend.service.short-url.bitly.setApiLogin">
                <term>
                    <methodsynopsis>
                        <methodname>setApiLogin</methodname>
                        <methodparam>
                            <funcparams>$login, $apiKey</funcparams>
                        </methodparam>
                    </methodsynopsis>
                </term>

                <listitem>
                    <para>
                        Takes the required <varname>$login</varname> username and <varname>$apiKey</varname>
                        and passes it to the service.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry id="zend.service.short-url.bitly.setOAuthAccessToken">
                <term>
                    <methodsynopsis>
                        <methodname>setOAuthAccessToken</methodname>
                        <methodparam>
                            <funcparams>$accessToken</funcparams>
                        </methodparam>
                    </methodsynopsis>
                </term>

                <listitem>
                    <para>
                        Use the OAuth <varname>$accessToken</varname> for authentication
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </sect2>
</sect1>