repo_zf1Php7/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 API for using
            <ulink url="http://del.icio.us">del.icio.us</ulink>
            XML and JSON 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: <code>getPosts()</code>,
            <code>getRecentPosts()</code> and <code>getAllPosts()</code>. 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 <code>getPosts()</code>, <code>getAllPosts()</code>,
            <code>getRecentPosts()</code>, and <code>getUserPosts()</code> 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 <code>ArrayAccess::offsetSet()</code> and <code>ArrayAccess::offsetUnset()</code> 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 URL.
        </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 <code>withTags()</code>. As a convenience,
                <code>withTag()</code> 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 URL matching a specified regular expression using the <code>withUrl()</code>
                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 URL or by calling the <code>delete()</code>
            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 <code>createNewPost()</code> 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 <code>save()</code> 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 API 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><code>getUserFans()</code></entry>
                        <entry>Retrieves fans of a user</entry>
                        <entry>Array</entry>
                    </row>
                    <row>
                        <entry><code>getUserNetwork()</code></entry>
                        <entry>Retrieves network of a user</entry>
                        <entry>Array</entry>
                    </row>
                    <row>
                        <entry><code>getUserPosts()</code></entry>
                        <entry>Retrieves posts of a user</entry>
                        <entry>Zend_Service_Delicious_PostList</entry>
                    </row>
                    <row>
                        <entry><code>getUserTags()</code></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 <code>getUserPosts()</code> 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 URL, 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><code>getNotes()</code></entry>
                            <entry>Returns notes of a post</entry>
                            <entry>String</entry>
                        </row>
                        <row>
                            <entry><code>getTags()</code></entry>
                            <entry>Returns tags of a post</entry>
                            <entry>Array</entry>
                        </row>
                        <row>
                            <entry><code>getTitle()</code></entry>
                            <entry>Returns title of a post</entry>
                            <entry>String</entry>
                        </row>
                        <row>
                            <entry><code>getUrl()</code></entry>
                            <entry>Returns URL 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 HTTP requests
            to the del.icio.us web service. To change which HTTP client <classname>Zend_Service_Delicious</classname>
            uses, you need to change the HTTP 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 HTTP 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 SSL 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:
-->