Update: 20-02-2010

Twitter Stream has now been updated. Support has been added back for parameter style calls to the function, twitter_stream(option, option, option) however you are strongly advised to change to the array/query string method which you can use by calling the wrapper function twitter_stream_args();. Some features like retweets & showing followers are not available through the old parameter method due to coding limitations & are only usable through the twitter_stream_args() function. You can find more on how to use the new function here.

I haven’t been able to test ReTweet support as much as I’d have liked so please report any bugs you find so I can fix them ASAP. Also those using WP-Super-Cache should update to 1.9 as soon as you can as I have fixed a huge problem which caused WP-Super-Cache to stop allowing Twitter Stream to update it cache.

Original Post

It’s been just over a year now since I released my first plugin which you may all know is The Attached Image, so I thought it was time I released another plugin. I hadn’t actually gone out on purpose to make this plugin, but a client’s website needed a simple Twitter feed plugin & while there are already WordPress plugins out there that do the job they insisted a custom one be built. So I set about making it & rather than have it sit in my WordPress functions folder doing nothing (other than working on the client’s site, of course) I thought I should release it as a plugin for anyone to use. :)

Althought the client requested the code be made I still retain the rights to use it as I wish. Just in case anyone was worrying about the useage rights. That means the plugin is under GNU (GPL) license as required by WordPress’s plugin repository.

Remember it is a very simple Twitter plugin, it is designed to do one thing and one thing only, show a user’s Twitter stream. Anyway here is some usage information.

What is Twitter Stream?

Twitter Stream is a very simple plugin originally created as a small function for a client’s website. Rather than have it sit doing nothing in my WordPress functions folder I thought I would extend it and make it into a plugin for everyone to use.

It’s functionality is very, very simple. It is designed to simply grab a set amount of status updates from the Twitter user account you request. If there are enough requests I may add some additional features, but for now it is designed to be very simple and run as quickly as possible while using the least amount of resources possible.

What Features Are There?

  1. Show the twitter timeline for any public username.
  2. Choose how many tweets to show.
  3. A Widget or template function is available.
  4. File caching to stop API overuse.
  5. Optional date shown in xx ago format, also links to permalink for the tweet. (Requested by Ron)
  6. Customizeable via CSS. (see the ‘Can I Style It?’ section below)
  7. Authentication for better API limiting & ability for protected users to show their tweets.
  8. @replies now link to the user profile of the user you are replying to.
  9. #tags now link to the Twitter search page for that hash tag.
  10. Link to user’s profile, customizable via CSS & via function parameter.
  11. Follower count can now be shown.
  12. Retweets can now be shown with normal tweets.

How Do I Install It?

You can download it from the WordPress repository here, and then install it as you would any old style WordPress plugin, which is as follows:

  1. Download the zip file and unzip it to somewhere, say your desktop.
  2. With any good SFTP client upload the extracted folder to your wp-content/plugins/ folder.
  3. Enable the plugin in the WordPress plugin page.

Of course you can also install it by using the WordPress auto installer.

How Do I Use It?

Well because it is so simple there wasn’t really a point in making a admin page for two options. So there is a widget available for all you widget fans (WordPress 2.8 or later is required though), or if you’re a good ol’ fashioned function user you can also call the plugin by using twitter_stream_args();. To pass options you can either use a query string or an array (preferred) like so:

twitter_stream_args(array('username' => 'twitteruser', 'password' => 'password', 'retweets' => FALSE));

or

twitter_stream_args('username=twitteruser&password=password&retweets=false');

You can find a list of all the available options here.

What Are The Connection Methods?

Twitter Stream features three different connection methods due to problems with certain server configurations. The preferable way to connect is CURL, however it may not be installed on your server. Twitter Stream will try to connect try via CURL by default, if CURL is not available it will try the next method which is fopen. fopen is generally always available, however some servers have URL access via fopen turned off for security purposes. If both CURL & fopen aren’t available it will try socket access. This method nearly always works, if Twitter Stream still can’t connect then your server is locked up tight & probably doesn’t allow external file access at all (highly unlikely). However feel free to contact me & I’ll try my best to help should this occur.

How Do You Get Round The API Limit?

Twitter has a built in API limit that stops a single IP from abusing the service. It is approximately 150 requests per hour from a single IP address, 20,000 if your IP is whitelisted by Twitter (you must make a request to twitter for whitelisting). If you exceed that too many times you may be blacklisted from the Twitter API, which isn’t good. To get round this Twitter Stream has a cache system that asks twitter for the users timeline once every 30 minutes & stores it locally. If you aren’t happy with 30 minutes you can change it. If you open the plugin file and find line 159 $thirtyago = time() - 1800; you can change 1800 to any amount time in seconds. Just remember that if you lower it too far & you get blacklisted due to too many requests, I am not responsible. Finally, lowering the time too far will cause the cache to be renewed far quicker, this can cause undue stress on the server.

What About Shared Servers & The API Limit?

This is a massive problem. If you are on a shared server there is a huge chance someone else may have put your servers IP, which you all share, over the API limit. I’ve added a new error message that will tell you if you have exceeded the API limit, if this is the case & you are on a shared server, there is a way around it. I have added user authenication into the plugin. This means if you give your Twitter username & password it will log in to Twitter when it grabs the tweets, this changes the API limit from the servers IP to your accounts API limit meaning no sharing. Please bare with me though as this is all theory & I have been unable to test it however with some basic testing I have performed the API requests left when authenticated are different to the API requests left when not authenticated meaning this should work.

Sometimes I Get An Error Message!

There is a built in error message that is shown if Twitter fails to provide a vaild XML file. Reasons for this could be that the Twitter API is down (which Twitter claim is highly unlikely), or the plugin failed to read the cache file. If this happens, and you know Twitter is available, try deleting the cache file which is named username.cache. It is located in the same folder as the plugin, that’s generally wp-content/plugins/twitter-stream/username.cache. If you continute to get the error please contact me & I’ll try and help out.

Sometimes The Date Is -xx Seconds Ago?

This is sometimes difficult to get your head around. Simply put it is caused by your servers clock being faster or slower than Twitters clock. To work out the time ago it takes the timestamp (number of seconds since Unix Epoc) and takes it away from the timestamp at which the tweet was posted. If your servers clock is slower than Twitters, for the first few seconds it ends up giving a negative value therfore seeming as if it was posted in the future. It could be something completely different involving Aliens, badgers and evil pidgeons, but that is the most sensible thing I’ve been able to come up with. If you have a better idea what it is let me know.

Can I Style It?

You can. I haven’t added any styles so I could keep the plugin on one file & keep it free of clutter. The available CSS classes are:

  1. .at-reply for @replys.
  2. .hash-tag for #tags.
  3. a.twitter-link for autolinked URL’s within the timeline.
  4. a:hover.twitter-link for autolinked URL’s within the timeline when they are hovered over.
  5. a.twitter-date for the date permalink.
  6. a:hover.twitter-date for the date permalink when it’s hovered over.
  7. .profile-link for the newly added link to user profile.
  8. .follower-count for the newly added follower count.

Can I Have A Options List?


Sure. The basic usage for in the template is this.

twitter_stream_args( [query-string/array] $args);

Here is the info for each parameter.

  • username should be a string and is the username of the Twitter timeline you want to return. Required.
  • count should be a string and is how many tweets to return. Default ’10′.
  • date bool or string. If set to TRUE it will show the time ago with a hyphen as a default separator. If it is a string of anything other than ‘TRUE’, ‘true’ or ’1′ it will use that as a separator.
  • password your twitter password as a string. Needed for retweet support. If you do not enter your password & enable retweet support it will just ignore it & show only normal tweets.
  • profile_link a string. Allows you to customize what the link to your Twitter profile (shown at the bottom of the tweets) says. ‘Visit My Profile’ by default. Use a space, like this ‘ ‘, to show nothing.
  • retweets bool, true or false. Shows retweets with normal tweets. If you haven’t entered your password this value will be ignored.
  • show_followers bool, true or false. Shows the number of followers.

Here is an example using all parameters.

twitter_stream_args(array( 'username' => 'twitteruser',
			      'count' => '10',
		              'date' => FALSE,
			      'password' => 'password',
			      'profile_link' => 'Visit My Profile',
			      'retweets' => FALSE,
			      'show_followers' => FALSE
		    ));

I Need A Translation!

You can download translations files for the plugin here. These are .po & .mo files in a zip for the languages available. For the translation to work you only need the .mo file placed in the same folder as the plugin.

I have provided the .po file for those who would like to amend or alter anything. Should you do that please send me a copy of the amended .po file so I can update the files here. If you would like to translate Twitter Stream into a language not available here you can download a blank .po file here. It is marked with Swedish codes but it is actually blank. Once you have filled that in send me a copy of the .po file & I will create the .mo file and offer it for download here. I will automatically credit you, but should you not want to be credited please tell me so in the email. You can email .po files to pablorobinson [at] gmail [dot] com.

A huge thank you to those who have translated so far & a big thank you to anyone who may help in the future.

I Have A Feature Request! / I’ve Found A Bug!

You can report all bugs via the comments which I read as soon as I can, or you can send me an email via the contact page. Either way I promise to try and get back to you as soon as possible.

Want To See A Working Demo?

Yep. If you want to see the Twitter Stream up & working, visit Medibolism and scroll down to the footer, it’s in the brown part on the right.

Where Do I Get It Again?

Once again you can download it from the WordPress plugin repository here, or you can install it via the WordPress auto installer in your blog admin.

I Love It, Can I Give You Some Love?

Wait… What?!! Oh you mean that sort of love. Sure. :P You can help out in one of three ways. You can donate to help cover server costs & the cost of the coffee that keeps me coding. You can do that by clicking the button below.


You can buy me a present from my Amazon Wish List which would be very much appreated, or you can simply spread the word about Twitter Stream & The Attached Image.

Well that’s about it, again this is designed to be a very, very simple plugin. As I’ve said if you find any bugs or have any requests let me know.

Note: Twitter bird artwork in header image created by lisa-marieart.com. Used with permission.