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

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

    <sect2 id="zend.service.delicious.introduction">
        <title>Introduction</title>

        <para>
            <classname>Zend_Service_Delicious</classname> is simple <acronym>API</acronym> for using
            <ulink url="http://del.icio.us">del.icio.us</ulink> <acronym>XML</acronym> and
            <acronym>JSON</acronym> web services. This component gives you read-write access to
            posts at del.icio.us if you provide credentials. It also allows read-only access to
            public data of all users.
        </para>

        <example id="zend.service.delicious.introduction.getAllPosts">
            <title>Get all posts</title>

            <programlisting language="php"><![CDATA[
$delicious = new Zend_Service_Delicious('username', 'password');
$posts = $delicious->getAllPosts();

foreach ($posts as $post) {
    echo "--\n";
    echo "Title: {$post->getTitle()}\n";
    echo "Url: {$post->getUrl()}\n";
}
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.service.delicious.retrieving_posts">
        <title>Retrieving posts</title>

        <para>
            <classname>Zend_Service_Delicious</classname> provides three methods for retrieving
            posts: <methodname>getPosts()</methodname>, <methodname>getRecentPosts()</methodname>
            and <methodname>getAllPosts()</methodname>. All of these methods return an instance of
            <classname>Zend_Service_Delicious_PostList</classname>, which holds all retrieved posts.
        </para>

        <programlisting language="php"><![CDATA[
/**
 * Get posts matching the arguments. If no date or url is given,
 * most recent date will be used.
 *
 * @param string $tag Optional filtering by tag
 * @param Zend_Date $dt Optional filtering by date
 * @param string $url Optional filtering by url
 * @return Zend_Service_Delicious_PostList
 */
public function getPosts($tag = null, $dt = null, $url = null);

/**
 * Get recent posts
 *
 * @param string $tag   Optional filtering by tag
 * @param string $count Maximal number of posts to be returned
 *                      (default 15)
 * @return Zend_Service_Delicious_PostList
 */
public function getRecentPosts($tag = null, $count = 15);

/**
 * Get all posts
 *
 * @param string $tag Optional filtering by tag
 * @return Zend_Service_Delicious_PostList
 */
public function getAllPosts($tag = null);
]]></programlisting>
    </sect2>

    <sect2 id="zend.service.delicious.postlist">
        <title>Zend_Service_Delicious_PostList</title>

        <para>
            Instances of this class are returned by the <methodname>getPosts()</methodname>,
            <methodname>getAllPosts()</methodname>, <methodname>getRecentPosts()</methodname>, and
            <methodname>getUserPosts()</methodname> methods of
            <classname>Zend_Service_Delicious</classname>.
        </para>

        <para>
            For easier data access this class implements the <code>Countable</code>,
            <code>Iterator</code>, and <code>ArrayAccess</code> interfaces.
        </para>

        <example id="zend.service.delicious.postlist.accessing_post_lists">
            <title>Accessing post lists</title>

            <programlisting language="php"><![CDATA[
$delicious = new Zend_Service_Delicious('username', 'password');
$posts = $delicious->getAllPosts();

// count posts
echo count($posts);

// iterate over posts
foreach ($posts as $post) {
    echo "--\n";
    echo "Title: {$post->getTitle()}\n";
    echo "Url: {$post->getUrl()}\n";
}

// get post using array access
echo $posts[0]->getTitle();
]]></programlisting>
        </example>

        <note>
            <para>
                The <methodname>ArrayAccess::offsetSet()</methodname> and
                <methodname>ArrayAccess::offsetUnset()</methodname> methods throw exceptions in this
                implementation. Thus, code like <code>unset($posts[0]);</code> and
                <code>$posts[0] = 'A';</code> will throw exceptions because these properties are
                read-only.
            </para>
        </note>

        <para>
            Post list objects have two built-in filtering capabilities. Post lists may be filtered
            by tags and by <acronym>URL</acronym>.
        </para>

        <example id="zend.service.delicious.postlist.example.withTags">
            <title>Filtering a Post List with Specific Tags</title>

            <para>
                Posts may be filtered by specific tags using <methodname>withTags()</methodname>. As
                a convenience, <methodname>withTag()</methodname> is also provided for when only a
                single tag needs to be specified.
            </para>

            <programlisting language="php"><![CDATA[
$delicious = new Zend_Service_Delicious('username', 'password');
$posts = $delicious->getAllPosts();

// Print posts having "php" and "zend" tags
foreach ($posts->withTags(array('php', 'zend')) as $post) {
    echo "Title: {$post->getTitle()}\n";
    echo "Url: {$post->getUrl()}\n";
}
]]></programlisting>
        </example>

        <example id="zend.service.delicious.postlist.example.byUrl">
            <title>Filtering a Post List by URL</title>

            <para>
                Posts may be filtered by <acronym>URL</acronym> matching a specified regular
                expression using the <methodname>withUrl()</methodname> method:
            </para>

            <programlisting language="php"><![CDATA[
$delicious = new Zend_Service_Delicious('username', 'password');
$posts = $delicious->getAllPosts();

// Print posts having "help" in the URL
foreach ($posts->withUrl('/help/') as $post) {
    echo "Title: {$post->getTitle()}\n";
    echo "Url: {$post->getUrl()}\n";
}
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.service.delicious.editing_posts">
        <title>Editing posts</title>

        <example id="zend.service.delicious.editing_posts.post_editing">
            <title>Post editing</title>

            <programlisting language="php"><![CDATA[
$delicious = new Zend_Service_Delicious('username', 'password');
$posts = $delicious->getPosts();

// set title
$posts[0]->setTitle('New title');
// save changes
$posts[0]->save();
]]></programlisting>
        </example>

        <example id="zend.service.delicious.editing_posts.method_call_chaining">
            <title>Method call chaining</title>

            <para>
               Every setter method returns the post object so that you can chain method calls using
               a fluent interface.
            </para>

            <programlisting language="php"><![CDATA[
$delicious = new Zend_Service_Delicious('username', 'password');
$posts = $delicious->getPosts();

$posts[0]->setTitle('New title')
         ->setNotes('New notes')
         ->save();
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.service.delicious.deleting_posts">
        <title>Deleting posts</title>

        <para>
            There are two ways to delete a post, by specifying the post <acronym>URL</acronym> or by
            calling the <methodname>delete()</methodname> method upon a post object.
        </para>

        <example id="zend.service.delicious.deleting_posts.deleting_posts">
            <title>Deleting posts</title>

            <programlisting language="php"><![CDATA[
$delicious = new Zend_Service_Delicious('username', 'password');

// by specifying URL
$delicious->deletePost('http://framework.zend.com');

// or by calling the method upon a post object
$posts = $delicious->getPosts();
$posts[0]->delete();

// another way of using deletePost()
$delicious->deletePost($posts[0]->getUrl());
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.service.delicious.adding_posts">
        <title>Adding new posts</title>

        <para>
            To add a post you first need to call the <methodname>createNewPost()</methodname>
            method, which returns a <classname>Zend_Service_Delicious_Post</classname> object. When
            you edit the post, you need to save it to the del.icio.us database by calling the
            <methodname>save()</methodname> method.
        </para>

        <example id="zend.service.delicious.adding_posts.adding_a_post">
            <title>Adding a post</title>

            <programlisting language="php"><![CDATA[
$delicious = new Zend_Service_Delicious('username', 'password');

// create a new post and save it (with method call chaining)
$delicious->createNewPost('Zend Framework', 'http://framework.zend.com')
          ->setNotes('Zend Framework Homepage')
          ->save();

// create a new post and save it  (without method call chaining)
$newPost = $delicious->createNewPost('Zend Framework',
                                     'http://framework.zend.com');
$newPost->setNotes('Zend Framework Homepage');
$newPost->save();
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.service.delicious.tags">
        <title>Tags</title>

        <example id="zend.service.delicious.tags.tags">
            <title>Tags</title>

            <programlisting language="php"><![CDATA[
$delicious = new Zend_Service_Delicious('username', 'password');

// get all tags
print_r($delicious->getTags());

// rename tag ZF to zendFramework
$delicious->renameTag('ZF', 'zendFramework');
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.service.delicious.bundles">
        <title>Bundles</title>

        <example id="zend.service.delicious.bundles.example">
            <title>Bundles</title>

            <programlisting language="php"><![CDATA[
$delicious = new Zend_Service_Delicious('username', 'password');

// get all bundles
print_r($delicious->getBundles());

// delete bundle someBundle
$delicious->deleteBundle('someBundle');

// add bundle
$delicious->addBundle('newBundle', array('tag1', 'tag2'));
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.service.delicious.public_data">
        <title>Public data</title>

        <para>
            The del.icio.us web <acronym>API</acronym> allows access to the public data of all
            users.
        </para>

        <table id="zend.service.delicious.public_data.functions_for_retrieving_public_data">
            <title>Methods for retrieving public data</title>

            <tgroup cols="3">
                <thead>
                    <row>
                        <entry>Name</entry>
                        <entry>Description</entry>
                        <entry>Return type</entry>
                    </row>
                </thead>

                <tbody>
                    <row>
                        <entry><methodname>getUserFans()</methodname></entry>
                        <entry>Retrieves fans of a user</entry>
                        <entry>Array</entry>
                    </row>

                    <row>
                        <entry><methodname>getUserNetwork()</methodname></entry>
                        <entry>Retrieves network of a user</entry>
                        <entry>Array</entry>
                    </row>

                    <row>
                        <entry><methodname>getUserPosts()</methodname></entry>
                        <entry>Retrieves posts of a user</entry>
                        <entry>Zend_Service_Delicious_PostList</entry>
                    </row>

                    <row>
                        <entry><methodname>getUserTags()</methodname></entry>
                        <entry>Retrieves tags of a user</entry>
                        <entry>Array</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <note>
            <para>
                When using only these methods, a username and password combination is not required
                when constructing a new <classname>Zend_Service_Delicious</classname> object.
            </para>
        </note>

        <example id="zend.service.delicious.public_data.retrieving_public_data">
            <title>Retrieving public data</title>

            <programlisting language="php"><![CDATA[
// username and password are not required
$delicious = new Zend_Service_Delicious();

// get fans of user someUser
print_r($delicious->getUserFans('someUser'));

// get network of user someUser
print_r($delicious->getUserNetwork('someUser'));

// get tags of user someUser
print_r($delicious->getUserTags('someUser'));
]]></programlisting>
        </example>

        <sect3 id="zend.service.delicious.public_data.posts">
            <title>Public posts</title>

            <para>
                When retrieving public posts with the <methodname>getUserPosts()</methodname>
                method, a <classname>Zend_Service_Delicious_PostList</classname> object is returned,
                and it contains <classname>Zend_Service_Delicious_SimplePost</classname> objects,
                which contain basic information about the posts, including <acronym>URL</acronym>,
                title, notes, and tags.
            </para>

            <table id="zend.service.delicious.public_data.posts.SimplePost_methods">
                <title>Methods of the Zend_Service_Delicious_SimplePost class</title>

                <tgroup cols="3">
                    <thead>
                        <row>
                            <entry>Name</entry>
                            <entry>Description</entry>
                            <entry>Return type</entry>
                        </row>
                    </thead>

                    <tbody>
                        <row>
                            <entry><methodname>getNotes()</methodname></entry>
                            <entry>Returns notes of a post</entry>
                            <entry>String</entry>
                        </row>

                        <row>
                            <entry><methodname>getTags()</methodname></entry>
                            <entry>Returns tags of a post</entry>
                            <entry>Array</entry>
                        </row>

                        <row>
                            <entry><methodname>getTitle()</methodname></entry>
                            <entry>Returns title of a post</entry>
                            <entry>String</entry>
                        </row>

                        <row>
                            <entry><methodname>getUrl()</methodname></entry>
                            <entry>Returns <acronym>URL</acronym> of a post</entry>
                            <entry>String</entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
        </sect3>
    </sect2>

    <sect2 id="zend.service.delicious.httpclient">
        <title>HTTP client</title>

        <para>
            <classname>Zend_Service_Delicious</classname> uses
            <classname>Zend_Rest_Client</classname> for making <acronym>HTTP</acronym> requests to
            the del.icio.us web service. To change which <acronym>HTTP</acronym> client
            <classname>Zend_Service_Delicious</classname> uses, you need to change the
            <acronym>HTTP</acronym> client of <classname>Zend_Rest_Client</classname>.
        </para>

        <example id="zend.service.delicious.httpclient.changing">
            <title>Changing the HTTP client of Zend_Rest_Client</title>

            <programlisting language="php"><![CDATA[
$myHttpClient = new My_Http_Client();
Zend_Rest_Client::setHttpClient($myHttpClient);
]]></programlisting>
        </example>

        <para>
            When you are making more than one request with
            <classname>Zend_Service_Delicious</classname> to speed your requests, it's better to
            configure your <acronym>HTTP</acronym> client to keep connections alive.
        </para>

        <example id="zend.service.delicious.httpclient.keepalive">
            <title>Configuring your HTTP client to keep connections alive</title>

            <programlisting language="php"><![CDATA[
Zend_Rest_Client::getHttpClient()->setConfig(array(
        'keepalive' => true
));
]]></programlisting>
        </example>

        <note>
            <para>
                When a <classname>Zend_Service_Delicious</classname> object is constructed, the
                <acronym>SSL</acronym> transport of <classname>Zend_Rest_Client</classname> is set
                to <code>'ssl'</code> rather than the default of <code>'ssl2'</code>. This is
                because del.icio.us has some problems with <code>'ssl2'</code>, such as requests
                taking a long time to complete (around 2 seconds).
            </para>
        </note>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->