# Zend_Service_Delicious

## Introduction

`Zend_Service_Delicious` is simple API for using del.icio.us 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.

### Get all posts

    $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";
    }

## Retrieving posts

`Zend_Service_Delicious` provides three methods for retrieving posts: `getPosts()`, `getRecentPosts()` and `getAllPosts()`. All of these methods return an instance of `Zend_Service_Delicious_PostList`, which holds all retrieved posts.

    /**
     * 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);

## Zend_Service_Delicious_PostList

Instances of this class are returned by the `getPosts()`, `getAllPosts()`, `getRecentPosts()`, and `getUserPosts()` methods of `Zend_Service_Delicious`.

For easier data access this class implements the `Countable`, `Iterator`, and `ArrayAccess` interfaces.

### Accessing post lists

    $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();

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

Post list objects have two built-in filtering capabilities. Post lists may be filtered by tags and by URL.

### Filtering a Post List with Specific Tags

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

    $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";
    }

### Filtering a Post List by URL

Posts may be filtered by URL matching a specified regular expression using the `withUrl()` method:

    $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";
    }

## Editing posts

### Post editing

    $delicious = new Zend_Service_Delicious('username', 'password');
    $posts = $delicious->getPosts();

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

### Method call chaining

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

    $delicious = new Zend_Service_Delicious('username', 'password');
    $posts = $delicious->getPosts();

    $posts[0]->setTitle('New title')
             ->setNotes('New notes')
             ->save();

## Deleting posts

There are two ways to delete a post, by specifying the post URL or by calling the `delete()` method upon a post object.

### Deleting posts

    $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());

## Adding new posts

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

### Adding a post

    $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();

## Tags

### Tags

    $delicious = new Zend_Service_Delicious('username', 'password');

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

    // rename tag ZF to zendFramework
    $delicious->renameTag('ZF', 'zendFramework');

## Bundles

### Bundles

    $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'));

## Public data

The del.icio.us web API allows access to the public data of all users.

### Methods for retrieving public data

Name | Description | Return type
--- | --- | ---
`getUserFans()` | Retrieves fans of a user | Array
`getUserNetwork()` | Retrieves network of a user | Array
`getUserPosts()` | Retrieves posts of a user | Zend_Service_Delicious_PostList
`getUserTags()` | Retrieves tags of a user | Array

When using only these methods, a username and password combination is not required when constructing a new `Zend_Service_Delicious` object.

### Retrieving public data

    // 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'));

### Public posts

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

#### Methods of the Zend_Service_Delicious_SimplePost class

Name | Description | Return type
--- | --- | ---
`getNotes()` | Returns notes of a post | String
`getTags()` | Returns tags of a post | Array
`getTitle()` | Returns title of a post | String
`getUrl()` | Returns URL of a post | String

## HTTP client

`Zend_Service_Delicious` uses `Zend_Rest_Client` for making HTTP requests to the del.icio.us web service. To change which HTTP client `Zend_Service_Delicious` uses, you need to change the HTTP client of `Zend_Rest_Client`.

### Changing the HTTP client of Zend_Rest_Client

    $myHttpClient = new My_Http_Client();
    Zend_Rest_Client::setHttpClient($myHttpClient);

When you are making more than one request with `Zend_Service_Delicious` to speed your requests, it's better to configure your HTTP client to keep connections alive.

### Configuring your HTTP client to keep connections alive

    Zend_Rest_Client::getHttpClient()->setConfig(array(
            'keepalive' => true
    ));

When a `Zend_Service_Delicious` object is constructed, the SSL transport of `Zend_Rest_Client` is set to `'ssl'` rather than the default of `'ssl2'`. This is because del.icio.us has some problems with `'ssl2'`, such as requests taking a long time to complete (around 2 seconds).