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.

Latest Info – 31/10/2011

Added the ability to return tweets into a variable so they can be manipulated via PHP before being output. This option was requested by advanced users & any users who do not want to use it should not notice any difference after upgrading.

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

Due to Twitter not having a solution for open source applications using oAuth yet, you must follow some slightly more complicated instructions to sign in via oAuth. Comprehensive instructions are provided in the plugin but here is a rough overview.

First you need to register a Twitter App, save the consumer keys you are provided with, then sign in with Twitter. As I said more detailed instructions are provided as you set up the plugin, including tips for what to enter when registering you app.

Finally you can show your tweets using a widget. The widget is a WP 2.8 & up compatible widget. If you are using a WP version lower than 2.8 you should really upgrade for security reasons if nothing else.

If you are a good ‘ol fashioned function user then you can call Twitter stream using:

twitter_stream($arg);

Providing either a keyed array or an argument list. All the parameters available are listed here.

How Do You Get Round The API Limit?

Now that oAuth has been implemented API requests will be counted against your personal account rather than your servers IP address meaning that shared servers should no longer cause a problem. However to reduce the possibility of overusing the API even further caching is still in use.

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. You can do that using the brand new ‘delete cache’ button which is shown on the bottom of the authorization page. Just click ‘Twitter Stream’ under the settings menu to find it.

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.

Sometimes oAuth Misses The Deny/Accept Page When I Press ‘Sign in with Twitter’?

This happens if you have already authorized Twitter Stream to be used with your Twitter account. Until you press the sign in button the plugin can’t tell if you have already given authorization or not. This generally happens if you have more than one blog using Twitter Stream with the same Twitter account. It’s perfectly normal though.

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( [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. No longer required. If omitted will show the user who authorized Twitter Stream’s timeline.
• 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.
• 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.
• show_followers bool, true or false. Shows the number of followers.
• cache_time Set the length of time tweets are cached for.
• echo Controls if the tweets should be echoed out to the page or returned as a SimpleXMLObject for manipulation via PHP. Defaults to TRUE, meaning echo tweets to page.

Here is an example using all parameters.

twitter_stream(array( 'username' => 'twitteruser',
			      'count' => '10',
		              'date' => FALSE,
			      'profile_link' => 'Visit My Profile',
			      'retweets' => FALSE,
			      'show_followers' => FALSE,
			      'cache_time' => 30,
			      'echo' => TRUE
		    ));

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.

• Swedish Translation – Thanks to Albert Johansson
• Belarusian Translation – Thanks to FatCow
• French Translation – Thanks to Tolingo.com
• Dutch Translation – Thanks to Rene
• Alternative Dutch Translation – Thanks to Sander Van Vliet
• Spanish Translation – Thanks to inMotion Hosting

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. Once you’ve done the translation send it to me at admin [at] return-true [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.

I Want To See A Working Demo?

Okay. Well the Twitter timeline here on Return True (on the right) is created using Twitter Stream. You can also see it on Medibolism & on Lisa Marie Art’s website.

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. 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 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.