Using the Dribbble API with PHP
Get your Dribbble shots out into the wild using the API plus open source PHP project.
The GitHub Project
It might have taken a while, but two weeks ago I finally got into GitHub. For those not familiar, GitHub is a site focused on the version control system Git, and allows. It’s not the only place that you can get hosted Git repositories from (e.g. Beanstalk), but it does have a much more open-source friendly environment. It’s no coincidence that their tagline is “Social Coding”.
As part of my orientation to GitHub, I wanted to contribute something to an existing project. As it turned out, Martin Bean’s Dribbble PHP wrapper was a brilliant candidate. Martin had already done a substantial amount of work in getting the raw JSON data into a workable format. I decided to help out and add in support for comments, rebounds, and some updated examples. This tutorial is the finishing touch.
Dribble API in PHP
Dribbble has a nicely documented API. Unfortunately for some, it only documents the API’s output, which means that you’d have to do some work on your own to get it to working on a project. On the bright side, finding a library for your language is not hard. In this tutorial, we’ll walk through a couple examples using the Dribbble PHP project hosted on GitHub.
As part of my GitHub update, I included formatted example pages that cover most of the regular API activity. This includes displaying rebounds, comments, and a number of the preset feeds given by Dribbble. If you download the source files and look at the examples, getting started should be straightforward. For the average person, displaying their account’s last five shots is perfectly fine.
General Installation
Note: All of these instructions are based on the version available as of November 1, 2010. If you’re reading this in the future, things may look different. That’s technology for you.
To start off, make sure that you’ve downloaded the most recent version from the project page. Once you’ve unzipped the project folder you’ll see a couple folders. The first is “examples/” and has a few sample pages that you can play with and see how things work. The second is “src” and contains all the files you need to integrate it into your own project.
Assuming you leave these files in the “src/” folder, you’ll load the class using the following code at the top of your page. This code must be present in order for any of the examples below to work.
<?php
require_once('src/dribbble.php');
$dribbble = new Dribbble();
?>
This will create a new dribbble object stored in $dribbble. Everything below branches from this.
Example 1: List by User
This is probably what 90% of you are interested in. A Dribbble feed makes an excellent addition to any portfolio/personal site. The following code will pull in the latest 3 shots made by the specified account.
<ul class="dribbble-shots">
<?php
$player = $dribbble->player->find('zachdunn');
$shots = $player->shots(array('per_page' => 3));
foreach ($shots->shots as $shot) {
echo sprintf('<li><a href="%s"><img src="%s" alt="%s" /></a></li>', $shot->url, $shot->image_url, $shot->title);
} ?>
</ul>
Shots can be called in two sizes: teaser and full. The example above uses the full 400×300 default, but if you wanted to display teasers instead, you can replace the $shot->image_url with $shot->image_teaser_url.
For those unfamiliar with PHP’s sprintf() function, here’s a quick primer: The “%s” acts as a placeholder for the arguments provided after the first comma. In the example above, the $shot->url result will be placed into the href attribute, etc. You don’t have to use this method, but I find it to be much neater than a series of PHP blocks for one-liners.
Example 2: Popular Shots
Here’s how you could use the API to get the three latest shots from Dribbble’s popular section:
<ul class="shots">
<?php
//If we're using the same dribbble object, this will overwrite previous calls
$popular_shots = $dribbble->shot->popular(array('page' => 1, 'per_page' => 3));
foreach ($popular_shots->shots as $shot) { ?>
<li>
<h2><a href="<?php echo $shot->url;?>"><?php echo $shot->title; ?></a></h2>
<a href="<?php echo $shot->url;?>"><img src="<?php echo $shot->image_url; ?>" alt="<?php echo $shot->title; ?>"/></a>
<p>from <a href="<?php echo $shot->player->url; ?>"><?php echo $shot->player->name; ?></a>
</li>
<?php } ?>
</ul>
Notice that you’re also able to display information about each shot’s author as well as link to their respective profiles.
Example 3: Comments on a Shot
This last one would be useful if you wanted to make a Dribbble-powered testimonial system. The loop below will display comments for the shot specified by ID.
# find a shot
$shot = $dribbble->shot->find(62170);
# Get first 5 comments on first page
$comments = $shot->comments(array('page' => 1, 'per_page' => 5));
<ul class="shots">
<li>
<h2><a href="<?php echo $shot->url;?>"><?php echo $shot->title; ?></a></h2>
<a href="<?php echo $shot->url;?>"><img src="<?php echo $shot->image_url; ?>" alt="<?php echo $shot->title; ?>"/></a>
<p>from <a href="<?php echo $shot->player->url; ?>"><?php echo $shot->player->name; ?></a>
</li>
</ul>
<?php if ($comments) : ?>
<ul class="comments">
<?php foreach ($comments as $comment) { ?>
<li>
<p><span class="author"><a href="<?php echo $comment->player->url; ?>"><?php echo $comment->player->name; ?></a> says:</span> <?php echo $comment->body; ?></p>
</li>
<?php } ?>
</ul>
<?php else : ?>
<p>No comments on this shot yet</p>
<?php endif; ?>
If you have any confusion with these (or other) examples, I recommend you take a look at the demo pages packaged with the source code. I tried to make sure that they were as clear-cut as possible, and should make it easy to figure out most issues.
Fork It Yourself
Since the project is open source, if anyone is motivated enough to contribute, that would be wonderful. Even though the current version covers all of the basics, there are plenty of features that could be improved upon and integrated from scratch. Even a couple hours can add miles (or kilometers) of polish. If you make a branch that’s got some exciting stuff in it, post up a link in the comments! We’d love to see it.
…and before you ask, I don’t have any dribbble invites. Sorry to disappoint!
