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.

Example #1 Get all posts

  1. $delicious = new Zend_Service_Delicious('username', 'password');
  2. $posts = $delicious->getAllPosts();
  3.  
  4. foreach ($posts as $post) {
  5.     echo "--\n";
  6.     echo "Title: {$post->getTitle()}\n";
  7.     echo "Url: {$post->getUrl()}\n";
  8. }

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.

  1. /**
  2. * Get posts matching the arguments. If no date or url is given,
  3. * most recent date will be used.
  4. *
  5. * @param string $tag Optional filtering by tag
  6. * @param Zend_Date $dt Optional filtering by date
  7. * @param string $url Optional filtering by url
  8. * @return Zend_Service_Delicious_PostList
  9. */
  10. public function getPosts($tag = null, $dt = null, $url = null);
  11.  
  12. /**
  13. * Get recent posts
  14. *
  15. * @param string $tag   Optional filtering by tag
  16. * @param string $count Maximal number of posts to be returned
  17. *                      (default 15)
  18. * @return Zend_Service_Delicious_PostList
  19. */
  20. public function getRecentPosts($tag = null, $count = 15);
  21.  
  22. /**
  23. * Get all posts
  24. *
  25. * @param string $tag Optional filtering by tag
  26. * @return Zend_Service_Delicious_PostList
  27. */
  28. 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.

Example #2 Accessing post lists

  1. $delicious = new Zend_Service_Delicious('username', 'password');
  2. $posts = $delicious->getAllPosts();
  3.  
  4. // count posts
  5. echo count($posts);
  6.  
  7. // iterate over posts
  8. foreach ($posts as $post) {
  9.     echo "--\n";
  10.     echo "Title: {$post->getTitle()}\n";
  11.     echo "Url: {$post->getUrl()}\n";
  12. }
  13.  
  14. // get post using array access
  15. 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.

Example #3 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.

  1. $delicious = new Zend_Service_Delicious('username', 'password');
  2. $posts = $delicious->getAllPosts();
  3.  
  4. // Print posts having "php" and "zend" tags
  5. foreach ($posts->withTags(array('php', 'zend')) as $post) {
  6.     echo "Title: {$post->getTitle()}\n";
  7.     echo "Url: {$post->getUrl()}\n";
  8. }

Example #4 Filtering a Post List by URL

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

  1. $delicious = new Zend_Service_Delicious('username', 'password');
  2. $posts = $delicious->getAllPosts();
  3.  
  4. // Print posts having "help" in the URL
  5. foreach ($posts->withUrl('/help/') as $post) {
  6.     echo "Title: {$post->getTitle()}\n";
  7.     echo "Url: {$post->getUrl()}\n";
  8. }

Editing posts

Example #5 Post editing

  1. $delicious = new Zend_Service_Delicious('username', 'password');
  2. $posts = $delicious->getPosts();
  3.  
  4. // set title
  5. $posts[0]->setTitle('New title');
  6. // save changes
  7. $posts[0]->save();

Example #6 Method call chaining

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

  1. $delicious = new Zend_Service_Delicious('username', 'password');
  2. $posts = $delicious->getPosts();
  3.  
  4. $posts[0]->setTitle('New title')
  5.          ->setNotes('New notes')
  6.          ->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.

Example #7 Deleting posts

  1. $delicious = new Zend_Service_Delicious('username', 'password');
  2.  
  3. // by specifying URL
  4. $delicious->deletePost('http://framework.zend.com');
  5.  
  6. // or by calling the method upon a post object
  7. $posts = $delicious->getPosts();
  8. $posts[0]->delete();
  9.  
  10. // another way of using deletePost()
  11. $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.

Example #8 Adding a post

  1. $delicious = new Zend_Service_Delicious('username', 'password');
  2.  
  3. // create a new post and save it (with method call chaining)
  4. $delicious->createNewPost('Zend Framework', 'http://framework.zend.com')
  5.           ->setNotes('Zend Framework Homepage')
  6.           ->save();
  7.  
  8. // create a new post and save it  (without method call chaining)
  9. $newPost = $delicious->createNewPost('Zend Framework',
  10.                                      'http://framework.zend.com');
  11. $newPost->setNotes('Zend Framework Homepage');
  12. $newPost->save();

Tags

Example #9 Tags

  1. $delicious = new Zend_Service_Delicious('username', 'password');
  2.  
  3. // get all tags
  4. print_r($delicious->getTags());
  5.  
  6. // rename tag ZF to zendFramework
  7. $delicious->renameTag('ZF', 'zendFramework');

Bundles

Example #10 Bundles

  1. $delicious = new Zend_Service_Delicious('username', 'password');
  2.  
  3. // get all bundles
  4. print_r($delicious->getBundles());
  5.  
  6. // delete bundle someBundle
  7. $delicious->deleteBundle('someBundle');
  8.  
  9. // add bundle
  10. $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

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

Example #11 Retrieving public data

  1. // username and password are not required
  2. $delicious = new Zend_Service_Delicious();
  3.  
  4. // get fans of user someUser
  5. print_r($delicious->getUserFans('someUser'));
  6.  
  7. // get network of user someUser
  8. print_r($delicious->getUserNetwork('someUser'));
  9.  
  10. // get tags of user someUser
  11. 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.

Example #12 Changing the HTTP client of Zend_Rest_Client

  1. $myHttpClient = new My_Http_Client();
  2. 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.

Example #13 Configuring your HTTP client to keep connections alive

  1. Zend_Rest_Client::getHttpClient()->setConfig(array(
  2.         'keepalive' => true
  3. ));

Note: 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).

blog comments powered by Disqus