Hummingbird

Hummingbird is a “show my latest tweets on my blog” widget written in PHP. The name is based on the idea of a bird (something that makes tweeting noises) with a very short attention span (just your latest, most recent tweets). It's small, lightweight, and pretty.

Many of the existing widgets that do what Hummingbird does have one problem or another. The progenitors of the genus — the widgets available from Twitter itself — are heavily reliant on Twitter’s own bandwidth, so that if Twitter's site is slow, yours will be too. Twitter's Flash widget, in particular, has only three possible color schemes, making it difficult to integrate visually with some sites. And very few of the available widgets have an option to strip out tweets that point back to your blog.

Features

Can automatically skip “blog backlink” tweets: If you use software that automatically creates a tweet with a link back to your blog every time you post a new blog entry (such as WordPress’ “Twitter Tools” plugin), you probably don’t need those tweets to show up in your Hummingbird feed. (“Gee, thanks for linking me to what I’m already looking at!”) Hummingbird can be configured to automatically skip those tweets in its output.
Can automatically skip @replies: If you don’t want visitors to your blog to see the one-sided conversations of @replies, you can set Hummingbird to strip out just the tweets that start with @someone, leaving the items you posted as original tweets. Tweets like “@john_doe123 I totally agree” will silently vanish; @user references inside the tweet, like “RT @jane_roe42 insert deep thoughts here”, will still show up.
Easy styling with CSS: Hummingbird emits well-formed, W3C-compliant XHTML with unique IDs that make it easy to style its look and feel using standard CSS. With just a few simple CSS rules (see below), you can make Hummingbird look just like the rest of your blog.
Makes @username references, #hashtags, and hyperlinks clickable: Even if you’re stripping out @replies, you might have references to other Twitter users inside your tweets. (Hummingbird only strips tweets with @replies if they’re the first thing in the tweet.) All @username references, #hashtags, and anything beginning with "http://" or "www." will automatically be made into a clickable link.
Doesn’t require WordPress: There are an awful lot of WordPress plugins out there that show your latest tweets on a WordPress blog. Hummingbird will work with blogs that aren’t powered by WordPress; as long as you can include a PHP file, you can run Hummingbird. (Of course if you are using WordPress, Hummingbird will still work just fine with it.)
Automatic background caching: Hummingbird will automatically cache its record of your tweets on your web server’s hard drive, and update the cache only when it gets old enough to be stale. Updates are performed in the background, so no visitor ever has to wait while the tweet information is updated. If your web host has a cron facility, you can use it to freshen the cache, so the tweets are always up-to-date.
Respects Twitter API’s rate limits: By default, Hummingbird should only perform 12 requests per hour to Twitter’s REST services, well below the 100-requests-per-hour limit that Twitter adheres to. If it does detect that it’s exceeded the rate limit, it will simply return data out of its cache until a new hour starts and it can get updated information.

Requirements

To run Hummingbird, you will need PHP5, with the SimpleXML extension built in. (It’s included by default in the standard PHP distribution.) Also, your PHP needs to include the command-line interface (CLI). Typing “php -v” at a command prompt will tell you if you have the CLI or CGI version; see the PHP site’s documentation for details on how to build or acquite the CLI version if you don’t already have it.

Hummingbird is particularly designed to work with WordPress, but it should be able to work with any blog software that uses PHP.

The installation instructions assume you have a general concept of things like file permissions and crontabs. If that part is confusing, there's a whole Web full of basic Unix tutorials out there; I don’t have the time to write yet another one.

Documentation

You’re reading it. Hummingbird is a small, lightweight package, and doesn’t really need a whole lot of docs. It’s also worth looking at the descriptions of the 7 configuration settings inside the hummingbird.php source file itself.

Download

Version 0.67 is a bug-fix release, which fixes some problems in auto-hyperlinking and hashtag recognition.

Version 0.67
Unix: hummingbird-0.67.tar.gz
Windows: hummingbird-0.67.zip

Archival copies of previous versions are available, but only for historical purposes. Older versions should not be deployed for actual use.

Version 0.66
Unix: hummingbird-0.66.tar.gz
Windows: hummingbird-0.66.zip

Version 0.65
Unix: hummingbird-0.65.tar.gz
Windows: hummingbird-0.65.zip

Version 0.61
Unix: hummingbird-0.61.tar.gz
Windows: hummingbird-0.61.zip

Version 0.60
Unix: hummingbird-0.60.tar.gz
Windows: hummingbird-0.60.zip

Installation

Note for pre-existing users: To upgrade from a previous version of Hummingbird, just follow steps 1-3 of the following installation instructions. Steps 4-6 are things you’ve already done, and don’t need to be repeated.

Download Hummingbird using the links above. Unpack, unzip, or untar the files into any directory you like — the archive will create a new “hummingbird-0.66” directory with the two PHP files in it.
Open hummingbird.php in your favorite editor, and change the $twitter_username value at the beginning of the file. If you wish, you can also edit the other 6 configuration variables there. The hummingbird-cache.php file does not require any configuration; it will get its config variables from hummingbird.php automatically.
Upload both files to your web host. If you’re using WordPress, you should place them in the wp-content/themes/yourtheme directory, where “yourtheme”, obviously, should be replaced by the name of the theme you’re actually using. If you’re using some other blog software, place the files wherever seems most convenient and logical.
Create an empty file in that same directory called hummingbird.xml. Make sure that file is writable by the web server user (such as user apache, www or httpd). Making the file world-writable (Unix file mode 0666, or rw-rw-rw-) is a good way to do this.
Find the place in your blog layout, theme, or other HTML where you want the tweets to show up, and insert a call to Hummingbird there. For themes that have a sidebar.php, that’s a popular place. Just add the line:

<?php include('hummingbird.php') ?>

and your latest tweets will appear at that point in your HTML.
If your web host has a cron or other job-scheduling feature, it’s good to set it up to freshen the cache file every 5 minutes. Normal Web hits on your blog will also trigger Hummingbird’s cache-update feature, but that will only update after displaying the cache’s contents. Setting up cron updates will ensure that the tweets presented on your blog are up-to-date. More data is available in the v0.60 release announcement.

Assuming your web server has a standard Unix cron facility, you can add the following line to your crontab file:

*/5 * * * * php /full/path/to/hummingbird.php

You will need to know the full path to the hummingbird.php file, starting from the server’s root directory. If you need help finding this, please consult your web host's support.

Finally, you’ll probably want to edit your blog’s CSS file(s) to make the Hummingbird output fit your blog’s look and feel.

CSS Styling

Hummingbird creates the following page elements:

A div called #hummingbird_div, which contains the entirety of Hummingbird's output.
An h2 called #hummingbird_title.
An optional p tag called #hummingbird_error, if Hummingbird encounters any errors during its execution.
The main ul, called #hummingbird_list.
- The ul naturally contains a collection of li elements, which have no class or ID.
- Each li includes at least one a, at the end, which links back to the tweet itself. This link has the class .hb_tweet_link.
- Additionally, any @username in any of your tweets will be turned into a hyperlink with the class .hb_atuser_link.
- Plus, any #hashtags will become links. You'll hopefully be unsurprised to learn that all #hashtags will have the class .hb_hashtag_link.
- Any other URL in your tweet will become a hyperlink with the class .hb_other_link.
Finally, there's a p element called #hummingbird_link_para, containing an a element called #hummingbird_twitter_link.

As a suggestion, the following CSS will set your tweets up to use the Twitter logo/icon as a list bullet. To make it work, you'll need to copy the Twitter icon image into the same directory as your CSS file, and add the following code at the end of the file. (If you’re using WordPress, you should upload the image to your theme’s directory, and add the code to the bottom of the style.css file.)

#hummingbird_list {
	margin: 0;
	padding: 0;
}
#hummingbird_list li {
	margin: 0;
	padding: 0 0 0.75em 20px;
	list-style: none;
	background: #fff url('icon_twitter.png') no-repeat 0 2px;
}
#hummingbird_link_para {
	text-align: right;
}

If you want to force all your individual-tweet backlinks to be on their own line, you can add this rule as well:

#hummingbird_list li a.hb_tweet_link {
	display: block;
}

If you want to add a bit of space before each backlink, the rule: margin-top: 0.5em; seems to work pretty nicely.

Feedback

If you have ideas or suggestions, or want to report bugs, or want to contact me in other ways, you can reach me at kai@mactane.org. I welcome bug reports, feature requests, and particularly tips on using Hummingbird with non-WordPress blog platforms — although I certainly hope Hummingbird works well with others, I personally am using WordPress, and so I don’t have an easy way of testing with other blog packages.

License

Hummingbird, by Kagan D. MacTane, is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License.

Version History

Hummingbird's version history is still short and sweet:

Number	Released	Notes
0.5	2009-05-27	Initial release. (And there was much rejoicing?)
0.51	2009-07-15	Added automatic linking of hashtags.
0.60	2009-08-20	Major rewrite to handle slow responses by Twitter. Code split into two files; distribution now in archive format instead of single-PHP-file.
0.61	2009-12-13	Bug-fix release: Hummingbird now handles empty XML cache files gracefully.
0.65	2010-09-19	Can now use multiple copies of Hummingbird with different Twitter accounts on the same machine. Hashtag links now go to Twitter's search function instead of hashtag.org.
0.66	2010-11-28	Improved error reporting on missing/unwritable file problems; better handling of different server configurations. Many thanks to Tom Clift of papercut.com for code patches!
0.67	2011-01-15	Fixed a couple of bugs in hashtag recognition and URL auto-hyperlinking.