WordPress Plugin: Twitter Stream

/ WordPress Plugins / by Paul Robinson / 445 Comments
This post was published back on December 30, 2009 and may be outdated. Please use caution when following older tutorials or using older code. After reading be sure to check for newer procedures or updates to code.

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 – 04/03/2013

If you have updated the plugin to version 2.5 and are having trouble, please make sure to delete the cache. Either manually or using the button on the options page.

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:

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.

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.

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

445 Comments

Author’s gravatar author

Thank you Jon it’s always nice to hear that the hard work that goes into creating a WordPress plugin is appreciated.

Right at this moment in time Twitter do not provide a method to remove/hide @replies from the timeline. I could do it manually, but the problem becomes even worse. The only way to do it would be to make 2 requests to Twitter instead of 1.

I’ll try and figure something out. 😉 ETA will probably be within the next few days.

Reply
Author’s gravatar author

Just another little message for Jon. I am currently trying to add both your request & a request I had to add the option for retweets to be displayed.

I am currently adding the retweet option, but the ability to hide/remove @replies has so far eluded me. I am not going to say it’s impossible, because it isn’t, but getting it to work in a practical mannor is lost on me.

Basically the problem is that you have to ask Twitter for a certain amount of tweets, let’s say 20. Now we take those tweets and remove the @replies, let’s say there were 8 of them (that isn’t the hard bit). Here is the problem, we now only have 12 tweets when the user asked for 20. This problem could become recursive should I attempt to correct it.

The only solution I have come up with is to request 200 tweets all the time, remove @replies & then count out the amount requested. The problem with that is that getting & parsing 200 tweets takes too long.

If any coders are reading this & can think of a better solution, please let me know. Sorry Jon. I will keep trying, but so far I’m not having much luck.

Reply
Author’s gravatar

I fixed up the “Your Twitter stream could not be collected. Normally this is caused by no XML feed being returned. Why this happens is still unclear.” message by changing the protocol of the twitter url to be http instead of https.

Reply
Author’s gravatar author

If you had to change https to http it means your server does not have support for secure http.

Please do not use your password as it will be sent in plain text by the server & could be very easily be intercepted.

Reply
Author’s gravatar

Has there been a recent change on your plugin or the Twitter side of things that changed the tweet listing to reverse chronological?

Reply
Author’s gravatar author

Well I haven’t changed anything recently, but you are correct. My twitter timeline is also in reverse chronological order.

I have absolutely no idea why though as my test server is in the correct order running the same version of the plugin. If you need to fix it right now here is how to do it while I try & find out what is going on.

Use the WP plugin editor (or a text editor of choice) and find the lines:

change krsort($combtweets) to ksort($combtweets).

That would probably be the fix I would use, but I need to find out why if I apply this fix to my test server it goes from chronological to reverse chronological while this server seems to go the opposite way… Very bizzare.

I’m open to suggestions if anyone has any on the problem.

Author’s gravatar author

Just to let you know I’ve now figured out what was causing the problem & it’s fixed in the update which you should be able to get now. 🙂

Author’s gravatar

Paul,
Thanks for finding and fixing the issue so quickly. (And for the mention in the changelog!)

Author’s gravatar author

No problem. It was a very strange bug so if you hadn’t brought it to my attention I probably would never have known. So thank you. 🙂

Author’s gravatar

First off all; thanks for making this great plugin!

I do however have run into a small problem

“Rate limit exceeded. Clients may not make more than 150 requests per hour.

Warning: krsort() expects parameter 1 to be array, null given in /mnt/web5/33/74/52018474/htdocs/dsa/wp-content/plugins/twitter-stream/twitter-stream.php on line 178

Warning: Invalid argument supplied for foreach() in /mnt/web5/33/74/52018474/htdocs/dsa/wp-content/plugins/twitter-stream/twitter-stream.php on line 179”

i have no idea what i did wrong? i just installed it…
i tried my personal twitter account and it seemed to work!

please help!

Reply
Author’s gravatar author

Hi Richard,

That error is exactly what it say’s. Your server has exceeded it’s allowed API requests per hour (that’s 150 for non-whitelisted IP’s).

Unfortunately that is a problem with Twitter only allowing that many requests per hour. I assume you are on a shared server so everyone on that servers Twitter requests are using the same 150 limit (since you are all on the same server and therefore have the same IP).

If you are happy to you can enter your password, this will allow Twitter to identify you & use your personal API requests, again that’s 150 per hour but only you will be using them, not the entire server. Refer to the post above for info on using your password.

Hope that helps.

Author’s gravatar

Hi Paul,

i can not recall that i am on a shared server… although i do run multiple twitter accounts on the same computer… but for this website it’s my first time using the twitter stream plugin so it’s not being used on any other machine or anything..

Thanks for the quick response… hope it will work later on today!

Author’s gravatar author

Hi again Richard,

I’ve checked the website you have used when you commented & you are hosted on a server along with about 34,000 other websites (I used a reverse IP checker to find out).

This means that all those other websites are using your 150 twitter API requests. The only way around this is to log in using your password so that Twitter identifies you as a user instead of just a IP address. It will then use your 150 API requests instead of the servers.

I hope that made what I meant a little easier to understand.

Author’s gravatar

Hey Paul,

thanks again for responding so quick
As you probably noticed i’m still a little new to this thing, so excuse me and thanks again for putting up with my unknowing!

I will try and hope it works!

thanks for all the effort!

Will respond if i figured it out 🙂

thanks again!

– Richard

Author’s gravatar author

No worries, we all start somewhere. 😉

I won’t be around for the rest of tonight (GMT+1 time) so it’ll probably be tomorrow morning before I respond.

Author’s gravatar

Hey Paul!

I tried filling it in all over again and it worked!!!!!
Thanks so much! This plug in is perfect!!!

– Richard

Author’s gravatar

I’ve saw lot of blog now that using this plugin so that it is easier for the visitor to follow the blog in twitter if he’she liked it.

Reply
Author’s gravatar

I get this error once in a while when the plugin can’t connect to Twitter (not the plugin’s fault… appears when Twitter service is down):

Warning: krsort() expects parameter 1 to be array, null given in /home/fruity/public_html/wp-content/plugins/twitter-stream/twitter-stream.php on line 178

Warning: Invalid argument supplied for foreach() in /home/fruity/public_html/wp-content/plugins/twitter-stream/twitter-stream.php on line 179

The problem is, I wish the plugin would convert that to a nicer, user-friendly error message. The current error messages take up space and throw off the alignment on my site.

Reply
Author’s gravatar author

Hey there,

Sorry about that. It really should convert to a nice error & shouldn’t give that message, so there is obviously a bug there. I’ll give it a check over for you and update the plugin to sort it out. 😉

Author’s gravatar author

I’ve updated the plugin to try & stop the ugly error messages. I can’t really test it though since Twitter send out a special error in their stream if that happens & I can’t get Twitter to send one on command, unfortunately.

If you can give it a try & let me know what happens the next time it happens, it would be most appreciated.

Author’s gravatar

Hi, following up on the previous issue… I’m still getting the same error messages after the update.

Reply
Author’s gravatar author

Sorry about the problems. I’m not exactly sure how to fix it. I’ve followed Twitters error checking guide which explains how to deal with errors sent back by Twitter.

I can only think of one more thing to try, I’ll update it now & hopefully it will work.

Author’s gravatar author

Ok, I’ve added one last idea I had to try & catch the errors. If this doesn’t work I’ll have to try to find a way to simulate an error so I can test it as I’m working blind at the moment.

Sorry for all the problems, hopefully that will fix it. 😉

Author’s gravatar

Hi,

I have submitted a comment here but it doesn’t appear. I think it goes to the spam folder. Please reconsider my comment.

Reply
Author’s gravatar

Your codes are really fantastic. Can I also use it for my blog. I really want to have a Twitter stream on it to have more followers and visitors.

Reply
Author’s gravatar

Hi! I just wanted to report that your fix (RE: nicer error message handling) WORKED! This now appears when Twitter is down:
Your Twitter stream could not be collected. Normally this is caused by no XML feed being returned. Why this happens is still unclear.
Ooop! Twitter seems to be down. Please either delete the cache file using FTP or wait until it auto clears.

THANK YOU for the fix! 🙂

Reply
Author’s gravatar author

Both those errors shouldn’t show at the same time so a little tweak needs to be done there, but at least the fix works. 🙂

Thank you for letting me know. 🙂

Author’s gravatar

By the way, you probably already know this, but I thought I should tell just in case you didn’t know… re-tweets still don’t show up. For example, I set up my sidebar to show only 1 tweet. The re-tweet wasn’t fetched and displayed.

The cache file only contained these few lines:
a:1:{i:0;s:75:”

“;}

Reply
Author’s gravatar author

The array didn’t show. Try putting it in

tags (without the spaces of course).

I’m not having any trouble with ReTweets as you can see in my sidebar (yes the pinching Suzi Perry’s bum tweet, lol). If you can provide the array I’ll definitely have a look at if for you though, just it case there is a problem. 🙂

I know there is a problem where it will show one less than you tell it too. I haven’t been able to track down the cause of that bug. I am still working on it though. 😉

Author’s gravatar

Hi Paul,

Can I still use this even I already have facebook on my site? It is just like this.

Reply
Author’s gravatar author

Errrm… Facebook?! This plugin is for putting Twitter on your WordPress blog.

Author’s gravatar

Hello!

still can’t get retweets, have entered password to twitter account and marked “show retweets” but still nothing from the retweets, they show up fine in my twitter account page

Reply
Author’s gravatar author

I’m not sure what is causing that. I can see retweets okay. There should be a retweet in the sidebar when the cache updates. I’ve also checked with a few friends sites & they show them okay too.

If you can give any more information that might help I’ll see if I can find any bugs. Just without the ability to replicate a problem it’s exceptionally hard to find the problem & fix it. 🙁

Author’s gravatar

Ok my twitter account is ‘kthinnovation’ and the twitter widget on the page innovationspaviljongen.com shows my tweets, but not the retweets that show up in the account.

What information can I send you to help find problem?

Author’s gravatar author

I realized after I’d wrote that, that there isn’t really much else you could tell me to help. 😆

Are you using the sidebar widget? My sidebar is using the template call (which you can see retweets are working on), so if you are I’ll check for bugs in the widget code later today as I don’t have access to my test copy at the moment.

Author’s gravatar author

I apologize Donnie, I’ve just found a bug that only effected retweets being shown when using the widget. Since I don’t use widgets I never noticed it.

I’ve fixed it and have uploaded it to the WordPress SVN so it should be available soon.

Author’s gravatar

Hi Paul,

I have just tried your plugin on a fresh install of WP 3.0 and it is coming up with an error:

Warning: array_slice() expects parameter 1 to be array, boolean given in /home/blah/wp-content/plugins/twitter-stream/twitter-stream.php on line 295

I have tried with password and no password, same error, plus 2 different twitter accounts.

It looks like a symptom of a bigger problem as it is failing due to the $content passed to twitter_stream_compile_tweets() is empty.

The server is running php 5.2.8 and it has libxml if that helps?

Any ideas?
Cheers
Rob

Reply
Author’s gravatar author

Hi Rob.

I’m not sure what is going on there. I’m currently running WP 3.0 (you can see in my source code) and my Tweets are showing okay.

According to the error $content is a boolean which would look empty unless you use var_dump() to debug it. The only reason $content would be a boolean would be if Twitter sent back an error & even then the error checking should catch it.

I’ve been having problems getting the error checking working properly since Twitter doesn’t error very often & it’s hard to replicate a Twitter error, lol.

Is there any other information you can give such as are you using a widget, or the template function? Also do you have SimpleXML installed on the server?

Author’s gravatar

Hi Paul,

I’m using the plugin as a widget in a side bar – a second side bar if that makes a difference? I am pretty sure SimpleXML is installed on the server. I’m not in the office at the moment, but will be back there tomorrow. I’ll have a deeper look to see what the problem is – most probably something setup wrong on my server or something.
Will keep you posted.
Cheers
Rob

Author’s gravatar

can’t get it running…

Could not authenticate you

Ooop! Twitter seems to be down. Please either delete the cache file using FTP or wait until it auto clears.

It work previously…

Please advice..

Reply
Author’s gravatar author

It happens sometimes. Twitter have been having fairly large problems with the API as of late & have been running at a reduced rate.

My best advice is to delete the cache as the error message says and then refresh the page in your browser using a Ctrl+F5 .

Author’s gravatar

Hi,

I don’t have “Twitter stream” listed in my setting menu. So I can’t configure it…

I’m using WP 3.0. I tried to delete the plugin folder and reupload it, but nothing…

Help ? 😉

Reply
Author’s gravatar author

Ahhh. Sorry in my panic to sort things out (thanks to Twitter & their oAuth problems) I forgot to remove that part from the instructions.

You have to set twitter stream up the old way, either with the widget (the easy way) or with the function call in your template (the hard but customizable way).

I’ll sort the instructions out now so other people don’t get confused.

Again sorry.

Author’s gravatar

Yep I figured it out after my comment. Thanks 😉

Author’s gravatar

I’m confused about styling. I’m using Twitter Stream in a standard template (not as a widget). The tweets show up, but I need to adjust their appearance. In a different plugin I was using, each tweet was a ul list item, so I was able to edit the CSS very easily. Is this possible with Twitter Stream? If not, how do I edit the appearance of the stream (beyond what is listed above)?

Reply
Author’s gravatar author

Well just like the other plugin has a outer ul with lis inside Twitter Stream uses a div with the class of twitter-stream and paragraph tags inside.

So something like:

The other CSS classes are written in the post above for things like @replies & hashtags.

I hope that helps.

Author’s gravatar

Perfect! Thanks for the quick reply!

Author’s gravatar

Any further word on the oAuth issue or a means I can keep informed of the situation?
BTW thanks for a wonderful plugin!

Reply
Author’s gravatar author

Unfortunately not. Trying to get an answer from Twitter is like getting blood from a stone. 🙁

I’m considering changing the oAuth system into the more complex version where you register for your own Twitter app & get your own consumer keys to use with the plugin. ETA for that will probably be a week or two though.

Oh, you can keep up to date either by keep checking this page for comments, or sign up to be updated via email just below the comments form below.

Author’s gravatar author

Adding the more complicated version of oAuth was easier than I have expected.

If you update to the latest version (should be on the repo shortly) you can follow the instructions on the admin page (settings->twitter stream) to get up and running with oAuth. 🙂

Author’s gravatar

I get the following error when I activate it:

Fatal error: Cannot redeclare class OAuthException in /home5/theforem/public_html/wp-content/plugins/twitter-stream/twitteroauth/OAuth.php on line 8

Reply
Author’s gravatar author

Not too sure about that one. It would suggest that that the TwitterOAuth class is already defined to the page.

Are you using the plugin twice on the same page? I’m sure that would be possible due to needing to use the external TwitterOAuth class to connect to Twitter.

Author’s gravatar

Just using it one time. Have two different accounts for two different sites. Until the plugin was fixed I had disabled it, and then I updated it and tried to activate it.

Author’s gravatar author

Hmm. I’m not really sure what is going on. I’m running the recent update. So are a few other websites I work with & I’ve yet to encounter the error.

Is there any more information you can provide as to what is happening. The only way I know of that you can receive that error is by a class being defined twice. Does any file in your theme or attached to the theme try to use the TwitterOAuth class or the oAuth class?

Author’s gravatar

Nothing else on the site is using oAuth class. Your plugin is the only one. I have not installed anything else related to twitter. I am using wordpress 3.0.1 and on bluehost.com which is a shared server.

Reply
Author’s gravatar author

I can’t confirm this, but apparently it may be because your PHP install on bluehost uses the PECL oAuth extention.

The only fix I have read requires editing the oAuth.php file. Which can be found in the twitteroauth folder inside the Twitter Stream plugin folder (found at /wp-content/plugins/twitter-stream). Here is the fix if you want to try it:

to this

I haven’t been able to replicate the problem to try the fix, but from poking around a little I was able to find that.

Please let me know if it works & I’ll keep on trying to find a more user friendly way to fix the problem so you don’t need to edit the file.

Sorry for the problems.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

I'll keep your WordPress site up-to-date and working to its best.

Find out more