Introduction

If you surf the Web with any degree of intensity, chances are you already know what del.icio.us is: a free online service that allows you to bookmark interesting Web sites and share them with other users. The service also allows users to "tag" bookmarks with keywords, and view the most popular bookmarks at any given time.

One cool feature of del.icio.us is the ability to access your bookmark list through a REST-based API, and integrate this list into your own XML-aware application. In most cases, this involves writing application-level code to communicate with the del.icio.us REST API, send requests, and parse responses. However, if your application is a PHP application, you can reduce some of the work in this process if you use Services_Delicious, a package from the PHP Extension and Application Repository (PEAR).

The Services_Delicious package provides an API to communicate with the del.icio.us REST API, create and transmit requests, and parse and decode XML responses. As such, it provides a robust, easy-to-use widget to view, add, edit or delete del.icio.us bookmarks from within any PHP application. This tip provides a brief overview of the package, with code illustrations of how you can accomplish these basic tasks.

Back to top

Installation

The Services_Delicious package is maintained by Stephan Schmidt and Tatsuya Tsuruoka, and released to the PHP community under a PHP license. The easiest way to install it is with the automated PEAR installer, which should have been included by default with your PHP build. To install it, simply issue the following command at your shell prompt:

shell> pear install Services_Delicious

The PEAR installer will now connect to the PEAR package server, download the package, and install it to the appropriate location on your system. This tip uses Services_Delicious V0.5.0.

To install the package by hand, visit its home page, download the source code archive, and manually uncompress the files to the desired location. Note that this manual installation process presupposes some knowledge of PEAR's package organization structure.

Services_Delicious depends on two other PEAR packages: the HTTP_Request package and the XML_Serializer package. With the PEAR automated installer, you can install these package as described previously; alternatively, you'll find links to the package files from the Resources of this tip. It's worth noting that in my development, I found that the HTTP_Request package sometimes failed to function correctly on Windows® and so the examples in this tutorial assume a *NIX development environment.

Services_Delicious also requires that you install OpenSSL and the OpenSSL extension of PHP in your PHP development environment. In *NIX environments, it may be necessary to recompile PHP with support for this extension. Find links to the OpenSSL Web site and further information on activating PHP's OpenSSL extension from the Resources.

Finally, the examples in this tip assume that you already have an account with del.icio.us, possibly with a few bookmarks added to it. In case you don't, you should sign up with the service—it's free—and seed your account with some entries. You'll find a link to the service's sign-up page in the Resources section of this tip.

Back to top

Retrieving bookmarks

Before you dive into Services_Delicious, a few words about the del.icio.us API are in order. As with all REST-based services, the API works over HTTP, using HTTP Basic authentication to verify a user's credentials before granting access. It includes methods to add and delete bookmarks, retrieve a user's bookmark list, and retrieve (or rename) a user's tags.

To see the API in action, try accessing the URL https://api.del.icio.us/v1/posts/recent in your favourite Web browser. This REST method returns a list of the user's most recent posts. You will be asked to sign in with your del.icio.us user credentials; once done, you should see the raw XML response to this method, which contains a list of recent bookmarks. It will look something like Listing 1:

                                
<?xml version='1.0' standalone='yes'?>
<posts tag="" user="someuser">
  <post href="http://www.kernel.org/" description="The Linux Kernel Archives" 
   hash="7dae6d24e3f8c6c3c3aa1b05ce5bfe94" tag="linux kernel opensource" 
   time="2007-12-04T09:03:25Z" />
  <post href="http://www.everythingphpmysql.com/" description="How to 
   do Everything with PHP & MySQL - Vikram Vaswani" 
   hash="8c9c6572c70cb3de3fa93b87269a8d79" 
   tag="book development php mysql web beginner" time="2007-12-04T09:02:47Z" />
  <post href="http://www.mysql-tcr.com/" description="MySQL: The Complete 
   Reference - Vikram Vaswani" hash="c8d99b00cfb9a1af9d59bbc6c46848cd" 
   tag="mysql php book" time="2007-12-04T09:02:21Z" />
  ...
</posts>
        

Figure 1 shows this output in Mozilla Firefox:

Listing 2 demonstrates how to replicate this action with Services_Delicious, in the context of a PHP application:

                                
<?php
// include class file
include_once 'Services/Delicious.php';

// initialize object
$sdObj = new Services_Delicious('someuser', 'somepass');

// get recent posts from del.icio.us
print_r($sdObj->getRecentPosts());
?>
        

Remember to replace the dummy user name and password in this listing, and all subsequent ones, with actual values.

Listing 2 uses the Services_Delicious package of PHP to connect to the del.icio.us Web service and retrieve a list of recent posts. To begin, it reads the Services_Delicious class file and initializes an object instance of the Services_Delicious class. The user's del.icio.us user name and password are passed to the object constructor and used to perform HTTP authentication. Then, the object's getRecentPosts() method retrieves the user's most recently-submitted bookmarks, and the XML response is then parsed and converted into a nested series of PHP arrays.

Listing 3 demonstrates what the array returned by getRecentPosts() looks like:

                                
Array
(
    [0] => Array
        (
            [href] => http://www.kernel.org/
            [description] => The Linux Kernel Archives
            [hash] => 7dae6d24e3f8c6c3c3aa1b05ce5bfe94
            [tag] => Array
                (
                    [0] => linux
                    [1] => kernel
                    [2] => opensource
                )

            [time] => 2007-12-04T09:03:25Z
        )

    [1] => Array
        (
            [href] => http://www.everythingphpmysql.com/
            ...
        )
)
        

The foreach() loop in PHP makes it easy to reformat this array for HTML display. Listing 4 illustrates the process:

                                
<html>
  <head></head>
  <body>
    <h2>My Bookmarks</h2>
    <?php
    // include class file
    include_once 'Services/Delicious.php';
    
    // initialize object
    $sdObj = new Services_Delicious('someuser', 'somepass');
    
    // get recent posts from del.icio.us
    // print as bulleted list
    $posts = $sdObj->getRecentPosts();
    echo "<ul>\n";
    foreach ($posts as $p) {
      echo "  <li>\n";
      echo "    <a href=\"" . $p['href'] . "\">" . $p['description'] . "</a><br />\n";
      echo "    <span style=\"color:red\">" . implode(' ', $p['tag']) . "</span>\n";
      echo "  </li>\n";
    }
    echo "</ul>\n";
    ?>
  </body>
</html>
        

Listing 4 iterates over the array returned by getRecentPosts(), printing each element as a bulleted list item, with the corresponding tags listed below each item. Figure 2 shows what this output might look like:

Back to top

Working with tags

The getTags() method returns a list of all tags used in a del.icio.us account, together with a count of how often each one is used. Listing 5 illustrates this method:

                                
<html>
  <head></head>
  <body>
    <h2>My Tags</h2>
    <?php
    // include class file
    include_once 'Services/Delicious.php';
    
    // initialize object
    $sdObj = new Services_Delicious('someuser', 'somepass');
    
    // get tags from del.icio.us
    // print as table
    $tags = $sdObj->getTags();
    echo "<table border=\"1\">\n";
    foreach ($tags as $tag => $count) {
      echo "  <tr>\n";
      echo "    <td>$tag</td>\n";
      echo "    <td>$count</td>\n";
      echo "  </tr>\n";
    }
    echo "</table>\n";
    ?>
  </body>
</html>
        

And Figure 3 illustrates what the output might look like:

One you have a list of tags, use the getPosts() method to return all bookmarks that match one or more of these tags, by passing it an array of tag names as first argument. Listing 6 illustrates, returning only those bookmarks tagged with the keyword book:

                                
<html>
  <head></head>
  <body>
    <h2>My Bookmarks</h2>
    <?php
    // include class file
    include_once 'Services/Delicious.php';
    
    // initialize object
    $sdObj = new Services_Delicious('someuser', 'somepass');
    
    // get recent posts from del.icio.us
    // tagged with 'book'
    // print as bulleted list
    $posts = $sdObj->getPosts(array('book'));
    echo "<ul>\n";
    foreach ($posts as $p) {
      echo "  <li>\n";
      echo "    <a href=\"" . $p['href'] . "\">" . $p['description'] . "</a><br />\n";
      echo "    <span style=\"color:red\">" . implode(' ', $p['tag']) . "</span>\n";
      echo "  </li>\n";
    }
    echo "</ul>\n";
    ?>
  </body>
</html>
        

Incidentally, you can also pass getRecentPosts() a similar array of tag names as first argument.

Back to top

Adding and deleting bookmarks

Services_Delicious also lets you add and delete bookmarks to your del.icio.us account from within your PHP application, through its addPost() and deletePost() methods. To illustrate, consider Listing 7, which adds a new bookmark:

                                
<?php
// include class file
include_once 'Services/Delicious.php';

// initialize object
$sdObj = new Services_Delicious('someuser', 'somepass');

// add a bookmark to del.icio.us
$ret = $sdObj->addPost('http://www.google.com/', 'My fav search engine', 
  null, 'search web cool', null, null);
if ($ret === true) {
  echo 'Bookmark added.';
} else {
  echo 'Bookmark could not be added.';
}
?>
        

The addPost() method accepts six parameters, of which only the first two are mandatory. The parameters are, in order of appearance:

• The URL
• A description of the URL link
• An extended description of the URL link
• Tags for the link
• The date and time at which the URL was submitted
• Whether or not the item is private

The return value of addPost() is Boolean, making it easy to check whether the item was successfully posted or not, and display an appropriate message to the user.

Want to remove a bookmark which has fallen out of favour? Listing 8 illustrates the necessary code:

                                
<?php
// include class file
include_once 'Services/Delicious.php';

// initialize object
$sdObj = new Services_Delicious('someuser', 'somepass');

// remove a bookmark from del.icio.us
$ret = $sdObj->deletePost('http://www.google.com/');
if ($ret === true) {
  echo 'Bookmark removed.';
} else {
  echo 'Bookmark could not be removed.';
}
?>
        

Removing a bookmark is even easier than adding one: simply provide deletePost() with the URL and bzzzt...it's gone!

Back to top

A simple application

Now that you understand what Services_Delicious can do, how about tying it all up with a practical example? Listing 9 demonstrates a PHP-based del.icio.us bookmark manager, which uses the methods described in previous sections to let users view and add bookmarks interactively:

                                
<html>
  <head></head>
  <body>
    <h2>My Bookmarks</h2>
    <?php
    // include class file
    include_once 'Services/Delicious.php';

    // use form submission
    // to add new bookmark
    if (isset($_POST['submit'])) {
      $url = trim($_POST['url']);
      $desc = trim($_POST['desc']);
      $tags = trim($_POST['tags']);
      $sdObj = new Services_Delicious('someuser', 'somepass');
      $ret = $sdObj->addPost($url, $desc, null, $tags, null, null);
      if ($ret === true) {
        echo 'Bookmark saved!';
      } else {
        echo 'Bookmark not saved!';
      }
      unset($sdObj);
    }

    // get recent posts from del.icio.us
    // print as bulleted list
    $sdObj = new Services_Delicious('someuser', 'somepass');
    $posts = $sdObj->getRecentPosts();
    echo "<ul>\n";
    foreach ($posts as $p) {
      echo "<li>\n";
      echo "<a href=\"" . $p['href'] . "\">" . $p['description'] . "</a><br />\n";
      echo "<span style=\"color:red\">" . implode(' ', $p['tag']) . "</span>\n";
      echo "</li>\n";
    }
    echo "</ul>\n";
    ?>

    <h2>Add New Bookmark</h2>
    <form method="post" action="<?php echo $_SERVER['PHP_SELF']; ?>">
      URL *: <br /> <input type="text" name="url" size="30" /> <br />
      Description *: <br /> <input type="text" name="desc" size="30" /> <br />
      Tags: <br /> <input type="text" name="tags" size="30" /> <br />
      <input type="submit" name="submit" value="Save" />
    </form>
  </body>
</html>
        

Listing 9 makes use of two methods you've seen already:

• The getRecentPosts() method, which lists recently-added bookmarks
• The addPost() method, which accepts data from a form submission and updates the bookmark list accordingly

Figure 4 illustrates the main page of the application:

And Figure 5 shows the updated main page, after adding a new bookmark:

As these examples illustrate, the Services_Delicious package provides a neat PHP wrapper around the del.icio.us REST API. It's very useful if you try to mash up your del.icio.us data with data from other Web services, or simply build a customized interface to the del.icio.us service. Play with it, and see what you think!

Resources

Learn

• Building Web Services the REST Way (Roger L. Costello, XFront): Understand how REST works in this tutorial that briefly introduces REST and then describes how to build Web services in the REST style.
  
  
• Enable REST with Web services, Part 1: REST and Web services in WSDL 2.0 (Eran Chinthaka, developerWorks, May 2007): Learn to use REST to enable Web services.
  
  
• Sign up for a free del.icio.us account (needed for the examples in this tutorial): Access and share your delicious bookmarks easily. Also browse, find, and get recommendations of new sites from the delicious community.
  
  
• The del.icio.us documentation: Peruse the del.icio.us help for an excellent overview of the del.icio.us REST API.
  
  
• PHP's OpenSSL extension: In the PHP manual, read about generating and verifying signatures and how to seal and open .
  
  
• More PEAR packages related to PHP and XML development: Find other PEAR packages related to PHP and XML development.
  
  
• XML area on developerWorks: Get the resources you need to advance your skills in the XML arena.
  
  
• IBM XML certification: Find out how you can become an IBM-Certified Developer in XML and related technologies.
  
  
• XML technical library: See the developerWorks XML library for a wide range of technical articles and tips, tutorials, standards, and IBM Redbooks. For a complete list of XML tips to date, check out the tips summary page.
  
  
• developerWorks technical events and webcasts: Stay current with technology in these sessions.
  
  
• The technology bookstore: Browse for books on these and other technical topics.
  
  

Get products and technologies

• The Services_Delicious package: Download a client for the REST-based Web service of del.icio.us to easily add, categorize, and share your collection of sites.
  
  
• The XML_Serializer package: Download this class and generate any XML document without DOM.
  
  
• The HTTP_Request package: Download this tool for GET/POST/HEAD/TRACE/PUT/DELETE, basic authentication, proxy, proxy authentication, SSL, and file uploads.
  
  
• The OpenSSL package: Download this toolkit that implements the Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS v1) protocols and includes a general purpose cryptography library.
  
  
• IBM trial software: Build your next development project with trial software available for download directly from developerWorks.
  
  

Discuss

• XML zone discussion forums: Participate in any of several XML-related discussions.
  
  
• developerWorks XML zone: Share your thoughts: After you read this article, post your comments and thoughts in this forum. The XML zone editors moderate the forum and welcome your input.
  
  
• developerWorks blogs: Check out these blogs and get involved in the developerWorks community.
  
  

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Installation
• Retrieving bookmarks
• Working with tags
• Adding and deleting bookmarks
• A simple application
• Resources
• About the author
• Comments

Next steps from IBM

With the no-charge DB2 Express-C, Zend Core PHP, and Java you can develope advanced Web 2.0 applications quickly that matter.

---

• Try: Download a free trial version of DB2 Express-C, which includes Zend Core PHP and pureXML technology that is ideally suited for managing both XML and relational data and powering a new breed of SOA and Web 2.0 solutions.
• Article: This IBM Redbook shows how to port PHP apps from MySQL to DB2, and includes code samples for creating Zend Core PHP applications.
• Tutorial: In this Mastering Facebook app development tutorial series, you will use Java and PHP in parallel to build a Facebook interface for an online stock trading J2EE application using the Spring framework.
• Buy: DB2 9 for Linux, UNIX and Windows

My developerWorks community

Dig deeper into XML on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers