Services_Digg

Services_Digg is a PEAR package created by the developers at Digg that allows developers to quickly consume and interface with the Digg API. The PEAR package officially supports the PHP return type, unofficially supports the XML response type using SimpleXML, but does not support the JSON return type. It also includes the class Services_Digg_Proxy, which allows developers to quickly set up JSON proxies for use from AJAX/JavaScript requests.

Installing Services_Digg

You can easily install the Services_Digg package using the PEAR command line utility under Windows, UNIX, and OSX. Please note that the below instructions are only temporary until the package is formally accepted as an official PEAR package. For change history, updates and other information please visit the package homepage.

$ pear install Services_Digg

Services_Digg

At this time the Services_Digg package supports all of the Digg API endpoints. The package is broken up into the major areas of the API: Comment, Comments, Errors, Stories, Story, Topics, User and Users. The default return type is serialized PHP and, to facilitate this interaction, the package defines and extends the classes returned from the API which are: DiggAPIStory, DiggAPIError, DiggAPIUser, DiggAPIComment, DiggAPIActivityPeriod, DiggAPIActivity, DiggAPIContainer, DiggAPIDigg, DiggAPIErrors, DiggAPIEvents, DiggAPIStories, DiggAPITopic, DiggAPITopics, and DiggAPIUsers.

Whenever possible, the package extends the behavior of these classes to facilitate subsequent API requests and usability of the responses. For instance, all of the result container classes (e.g. DiggAPIErrors, DiggAPIStories, etc.), support object iteration.

Services_Digg_Stories

Fetching stories

The example below shows how to send a request to fetch 10 stories from the API. The example also shows how you can easily iterate through the results using PHP5's object iteration. Almost all of the package's methods take a $params argument that is an array of API arguments that are then passed on to the API request.

<?php

require_once 'Services/Digg.php';
try {
    $api = Services_Digg::factory('Stories');
    $stories = $api->getAll(array('count' => 10));
    foreach ($stories as $story) {
        echo $story->title . '<br />' . "n";
    }
} catch (PEAR_Exception $error) {
    echo $error->getMessage() . '<br />' . "n";
}

?>

Fetching comments from stories

The following example shows how you can make an inital request to the API and then make subsequent requests for more data using the objects returned by the initial API request. Normally these functions are named after their endpoints, but there are exceptions and you should either view the phpt tests or package code for more details. This example brings together a few of the features of the package: how to define $params, how to check responses, how to iterate, and the magic __toString() function to output comments.

<?php

require_once 'Services/Digg.php';

try {
    $api = Services_Digg::factory('Stories');

    $params = array('count' => 3,
                    'sort' => 'submit_date-asc');

    $stories = $api->popular($params);
    foreach ($stories as $story) {
        echo '<h2>' . $story->title . '</h2>';
        $comments = $story->comments();
        echo '<ul>';
        foreach ($comments as $comment) {
            echo '<li>' . $comment . '</li>'; 
        }
        echo '</ul>';
    }
} catch (PEAR_Exception $error) {
    echo $error->getMessage() . '<br />' . "n";
}

?>

Services_Digg_Users

Fetching a User's comments

The API lets you look up users by their username, fetch a user's comments, their diggs, and other activity. The following example is how you would fetch a user's information and then print out their comments within a specific time period. 

<?php

require_once 'Services/Digg.php';

try {
    $api = Services_Digg::factory('Users');
    $user = $api->getUserByName('joestump');
    $params = array('min_date' => 1173981000,
                    'max_date' => 1173981600);

    echo '<ul>';
    foreach ($user->comments($params) as $comment) {
        echo '<li>' . $comment . '</li>'; 
    }
    echo '</ul>';
} catch (PEAR_Exception $error) {
    echo $error->getMessage() . '<br />' . "n";
}

?>

Fetching a User's diggs

In the example below we fetch a user's diggs from a specific time period, fetch each story they dugg from the API, and then format the story for general browsing. When testing out this script try using the following URI http://www.example.com/users-diggs.php?user=joestump&min_date=2007-04-04+10:00:00&max_date=2007-04-04+10:59:00.

<?php

require_once 'Services/Digg.php';

try {
    $api = Services_Digg::factory('Users');
    $user = $api->getUserByName($_GET['user']);

    $params = array('min_date' => strtotime($_GET['min_date']),
                    'max_date' => strtotime($_GET['max_date']));

    $diggs = $user->diggs($params);

    echo '<ul>';
    foreach ($user->diggs($params) as $digg) {
        $story = Services_Digg::factory('Stories')->getStoryById($digg->story);
        echo '<li><a href="' . $story->href . '">' . $story->title . '</li>'; 
    }
    echo '</ul>';
} catch (PEAR_Exception $error) {
    echo $error->getMessage() . '<br />' . "n";
}

?>

DiggAPIError

If an API request fails for some reason the API returns the PHP class DiggAPIError. The PEAR package defines this as extending from PEAR_Error (Note: I just noticed that this is deprecated so future versions will be switching to throwing a PEAR_Exception), which means that you can check responses from package calls as you would most other PEAR packages. The defined DiggAPIError doesn't currently support callbacks, etc. because it's instantiated through __wakeup() rather than __construct().

Defining Response Classes

The PEAR package takes the liberty of defining all of the response classes returned by the Digg API. The default classes defined by the package add functionality to make interacting with the responses and the API easier and less verbose. That being said, some developers might wish to define their own response classes rather than use the ones defined by the package. If you wish to define your own response classes merely define them before including Services/Digg.php or making any requests to the API via the PEAR package.

Services_Digg_Proxy

The class Services_Digg_Proxy allows you to quickly set up a proxy on your own website to proxy requests to the Digg API from your own JavaScript. If you plan on making requests to the Digg API from JavaScript on your own website you must use a proxy.

Example proxy code

The example PHP code below should be placed into a file on your web server. In our example we've called it my-proxy.php. You will then send requests to this PHP script from your JavaScript/AJAX applications rather than directly to the Digg API, which isn't possible due to "same domain" restriction on AJAX requests. Services_Digg_Proxy accepts both GET and POST requests.

<?php

require_once 'Services/Digg/Proxy.php';
Services_Digg::$appKey = 'http://www.example.com/my-proxy.php';
$proxy = new Services_Digg_Proxy();
$proxy->proxy();

?>

Example jQuery code

The example JavaScript below calls the PHP script created in the above example. When you send requests from your JavaScript/AJAX applications you will use your proxy script, my-proxy.php, and not call the Digg API directly. The only required argument is endPoint. All other arguments passed to the proxy are passed onto the Digg API request.

<html>
<head>
<script type="text/javascript" src="jquery-latest.pack.js"></script>
<script type="text/javascript">
$(document).ready(function() {
    var uri = '/my-proxy.php';
    var params = {
        endPoint : '/stories/popular',
        type : 'json',
        min_promote_date : 1173942000,
        max_promote_date: 1174028399,
        count : 50
    };
    $.getJSON(uri, params, function(json) {
        if (json.stories.length > 0) {
            for (i in json.stories) {
                $('#stories').append('<li><a href="' + json.stories[i].href + '">' + json.stories[i].title + '</a></li>');
            }

            $('#stories').show('slow');
        }
    });
});
</script>
</head>
<body>
<ul id="stories" style="display: none;"></ul>
</body>
</html>

 Create your own business wiki!Support CommunityPublic, Platinum wiki Privacy Policy RSS