ZendService\Delicious

Introduction

ZendService\Delicious\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 ZendService\Delicious\Delicious('username', 'password');
$posts = $delicious->getAllPosts();

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

Retrieving posts

ZendService\Delicious\Delicious provides three methods for retrieving posts: getPosts(), getRecentPosts() and getAllPosts(). All of these methods return an instance of ZendService\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 DateTime $dt Optional filtering by date
 * @param string $url Optional filtering by url
 * @return ZendService\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 ZendService\Delicious\PostList
 */
public function getRecentPosts($tag = null, $count = 15);

/**
 * Get all posts
 *
 * @param string $tag Optional filtering by tag
 * @return ZendService\Delicious\PostList
 */
public function getAllPosts($tag = null);

ZendService\Delicious\PostList

Instances of this class are returned by the getPosts(), getAllPosts(), getRecentPosts(), and getUserPosts() methods of ZendService\Delicious\Delicious.

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

Accessing post lists

$delicious = new ZendService\Delicious\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();

Note

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 ZendService\Delicious\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 ZendService\Delicious\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 ZendService\Delicious\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 ZendService\Delicious\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 ZendService\Delicious\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 ZendService\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 ZendService\Delicious\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 ZendService\Delicious\Delicious('username', 'password');

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

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

Bundles

Bundles

$delicious = new ZendService\Delicious\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	ZendServiceDeliciousPostList
getUserTags()	Retrieves tags of a user	Array

Note

When using only these methods, a username and password combination is not required when constructing a new ZendService\Delicious\Delicious object.

Retrieving public data

// username and password are not required
$delicious = new ZendService\Delicious\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 ZendService\Delicious\PostList object is returned, and it contains ZendService\Delicious\SimplePost objects, which contain basic information about the posts, including URL, title, notes, and tags.

Methods of the ZendServiceDeliciousSimplePost 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

ZendService\Delicious\Delicious uses Zend\Rest\Client for making HTTP requests to the del.icio.us web service. To change which HTTP client ZendService\Delicious\Delicious uses, you need to change the HTTP client of Zend\Rest\Client.

Changing the HTTP client of ZendRestClient

$myHttpClient = new My_Http_Client();
Zend\Rest\Client::setHttpClient($myHttpClient);

When you are making more than one request with ZendService\Delicious\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
));

Note

When a ZendService\Delicious\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).