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>
        </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>
</sect1>