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.


Author’s gravatar

If this plugin is used with a multi-site configuration, it only has one cache for all the websites.

So you have to disable the cache if you use different twitter accounts on the different websites.

Is it possible to change this?

Author’s gravatar author

Hi Carsten,

I’m not 100% but I think that is caused by the fact Twitter now allows you to omit your username should you be the authorized user. In such a case Twitter Stream uses the name authuser.cache for the cache file.

I can only suggest providing a username as a parameter even if you are the authorized user, in that case Twitter Stream should create a unique cache file for each user.

If you are providing a username & you are still having the problem, please drop as much information as you can via the contact for & I’d love to look into it more for you.

Author’s gravatar

Hi Paul,

Thank you for your plugin, it works great on ww.depatissier.nl.
However, I would like to know if it is possible to exclude replies from the twitter stream?
I hope so!

Author’s gravatar author

Hi Michelle,

unfortunately it isn’t at the moment. I can add it in though as Twitter do allow it in their API. There will be one problem though due to a problem on Twitter’s end.

Basically because Twitter exclude the replies after grabbing the tweets, if you ask for 5 tweets and 3 are replies, you’ll only get back 2. Is that okay? Let me know & I’m happy to add it into the plugin for you.

Author’s gravatar

Hi Paul,

Thank you for your quick response and your willingness to add this option to the plugin! I have to discuss this with my collegues but I don’t think it’s a good option to have the change of an empty twitter stream 🙁 Too bad Twitter doesn’t exclude before grabbing the tweets.

Thank you once more!

Author’s gravatar author

Hi Michelle,

Yep, sadly it’s the way their API works. It’s always bothered me that they don’t filter before hand. 🙁

Author’s gravatar

Paul, GREAT plugin! Works so perfectly. I had coded my own twitter stream I was using on wordpress, but ran into problems with the API limit being reached, and still my links weren’t working out the way I wanted them to…

Came across your plugin and it’s PERFECT. Super-customizable via CSS, the caching is a brilliant idea so you don’t get an error displayed when the API limit is reached, and all-around great plugin. Great work.

I’m using it now on http://www.joelpack.com and love it. I’ll definitely be using your plugin for all my wordpress twitter feeds in the future. thanks again! 🙂

Author’s gravatar author

Hi Ryan,

Not a problem. It’s always nice to hear all the hard work of writing it has paid off by it actually helping people it the real world. 🙂

Thanks again.

Author’s gravatar

How would it be possible to add this to a page in wordpress. I want to put it under my tweet box in my update page.

Author’s gravatar author

Hi Dominick,

You would be able to do that by making a page template & using the PHP template call mentioned in the instructions above. Check out the WordPress Codex for info on how to make a page template.

Author’s gravatar

Hi Paul,

I have entered the keys, but when I click on the “Sign in with Twitter” button I get a http 500 internal server error. I have been trying to fix this now for 2 hours!

Do you have any ideas?


Author’s gravatar author

Hi Rob,

I’m not sure. 500 errors are hard to track as they generally just mean the server encountered an error, but isn’t sure what the error was. It covers everything from over use of memory, to a PHP syntax error (depending on server config).

The sign in with Twitter button normally just sends you to Twitter to sign in. When you get the 500 error is the address in the address bar your website or Twitter’s?

Author’s gravatar

Hi Paul,

The address is:


And thanks for the quick response!


Author’s gravatar author

Well, that would suggest it’s your side that has the 500 error. I can only think there is a problem with the script that redirects you to Twitter. Unfortunately I’m not the author of that code, it is a oAuth framework that is commonly used to connect to Twitter.

Do you have access to your PHP error logs for your server? Normally although the server gives a 500 error, the log normally gives a better description of what is wrong.

If you can could you send me an email with the error in? The text written in the error log sometimes has information you generally wouldn’t want to be available to the whole internet.

Author’s gravatar

Hi Paul, I came across this after seeing you’re twitter switcher and together they’re just what I need, how ever I was wondering if it was possible to display 4/5 users tweets? if i can mod it to achieve this, I’ve found the perfect plugin!

Author’s gravatar author

Hi Sam,

Sadly no, that would be difficult to modify the plugin to do. In fact it would probably be easier to start from scratch.

Sorry. 🙁

Author’s gravatar

No worries Paul, thanks for letting me know! If I get anywhere, I’ll be sure to let you know!

Author’s gravatar author

Again sorry I wasn’t able to help.

Thanks, will be a big help if I try to add it as a feature in the future.

Author’s gravatar

When I click on “Sign in with Twitter”, it flashes really quickly “could not connect to Twitter. Refresh the page or try again later. Code:401” and doesn’t progress to the next step to set-up.

I’ve uninstalled everything and started from scratch on three different occasions and keep getting the same thing.

My Twitter account is private and I want to publish private tweets on a password protected website. I’ve read this is possible with this plugin. Is this true?

Thanks for the help.

Author’s gravatar author

Hi Owen,

You should be able to use Twitter Stream to display private tweets. The 401 problem is quite a common problem and it normally comes down to a few different problems.

The first is that your server has been blacklisted by Twitter. It’s highly unlikely but some hosts like Bluehost (at least the last time I used them) have a few servers that are blacklisted by Twitter & cannot connect to their API.

The second is that there was a problem when creating your application on the Twitter development website. This is the most common problem & is normally fixed by deleting your keys in the plugin, and deleting the application you created at Twitter. Then remaking it making sure that you fill in the Callback URL as it will not work without it.

Also you may need to go into the application you create and click the button that says ‘Create My Access Token’ so that Twitter Stream can authorize you correctly. This is a fairly new feature on Twitter’s end & I need to add the extra instruction into my plugins walkthrough.

Hopefully that helps you in some way. Let me know if you continue to encounter the problem & I’ll look into it further for you.

Author’s gravatar

Thanks Paul!

I think we may have the “highly unlikely” situation. I’ve tried a few more times and still am not having any different results.

I noticed the “create my access token” authorization before posting the first time too.

I’m actually with Bluehost and will have to ring them tomorrow and see if the server my site is on.

Thanks again!

Author’s gravatar author

The only thing I’m having trouble with is that normally, if you are logging in via oAuth, having a blacklisted server doesn’t matter since when logged in via oAuth your API requests are counted against your account (and you get 350 instead of 150). Unless of course Twitter won’t allow your server to authenticate because your server is blacklisted.

If you can’t get Twitter Stream to work I normally recommend SeaOfClouds Javascript Twitter script instead, it gets around a lot of banning & oAuth problems. As much as I’d like you to use Twitter Stream, I’d rather you have something that works.

Author’s gravatar

Hi Paul,
I don’t know if this has been covered already in the comments, but I’m trying to add my Twitter avatar to display before the tweets.
I’ve experimented by putting this just before


and then this just before


But I think this will not be a cached result? I think instead I need to reference the ‘profile_image_url’ from the cached xml… but I’m stuck (even though your code is very well documented!). I’d appreciate any help, even just a nudge in the right direction! Thank you!!

Author’s gravatar

how do I fix this error?

Tweet failed. Twitter returned HTTP 401. Check your OAuth settings and re-save this post to try again.

It appears in the Tweet This box after I publish a new post.


Author’s gravatar author

Hi Kendra,

I’m not sure what you mean? My plugin doesn’t allow submission of tweets to Twitter, Twitter Stream just allows you to show your tweets in your sidebar or somewhere else on your WordPress blog.

Author’s gravatar

The widget at my website shows only 2 tweets. The setting is 6. The cache file has just 2 tweets too.

What’s the solution for this?

Author’s gravatar

Hi Paul, sorry for my english. I have a problem with your pligin, when i click “Sign in w twitter” (options-general.php?page=twitterstreamauth&wptwit-page=redirect), i recieve only HTTP 500 error at any version of plugin. Can you help me with this situation? I use phpfpm+nginx my for web server, maybe i need to setup some aditional packages? Thanks in advance.

Author’s gravatar author


A 500 is a difficult error to track down as it is literally the server saying there was a problem, but (in most cases) it can’t tell you what the problem was or what that cause was. When you get the 500 is the URL in the browser your website or Twitter’s? If it was Twitter it may just be a temporary problem. Let me know if the problem persists & I’ll try to find the problem for you.

Author’s gravatar

Paul, thanks for quick response. I get this error on my site, not twitter’s. On this url – mysite/options-general.php?page=twitterstreamauth&wptwit-page=redirect

Author’s gravatar author


I apologise for the delay in responding. We’ve had some pretty bad weather here & we had some damage due to flooding, not only that I’ve had to continue with client work so things haven’t exactly been great.

I’m sad to say I’m not sure what could be causing the error. As I said the 500 error is the servers way of saying that something is wrong, but it isn’t exactly sure what. You could check your PHP error logs (if you have access to them). Also check you have PHP 5 installed as it is required for the plugin to work.

Author’s gravatar

Hello Paul!

Thanks for help, error log help me to solve this situation 🙂
I hope weather better now and you are ok.
Thanks so much for your work.

Author’s gravatar author

Ahh, good news & thank you.

Any chance you could share what the problem was as it may help others who are having the same problem. 🙂

Author’s gravatar

Hi, I notice that long tweets are cut off with …
Is that the data that Twitter returns? Or is the script cutting of the tweets?

Author’s gravatar author

Hi Sander,

The plugin uses the text straight from the data returned from Twitter. It passes it through a few find and replaces to auto link URLs & add links to hashtags & @replies, but doesn’t shorten the tweet in anyway. I can only think it’s something Twitter do on their end, although I’m not sure why.

Author’s gravatar


is there a possibility of putting a gap between the tweets?


Author’s gravatar

Hi Paul,

Thanks for producing such a handy plugin. I’m trying to get it to hide @replies as the options currently only let me hide retweets. In order to achieve this I’ve edited twitter-stream.php and in the [lang]foreach($twitxml->status as $tweet) [/lang] just before [lang]$o .= “”.$tweet->text;[/lang] I’ve added the following:
[lang]if (substr($tweet->text,0,1)==”@”){
Please forgive the inelegance… it’s my first attempt at php! Anyway, the problem now is that instead of 3 tweets at the bottom of the page I just get blank entries e.g. at the time of writing I can only see one tweet on my website instead of the 3 last non-RT and non-@someone.

Finally, tweets containing & symbols seem to display as & Could that be something to do with the line [lang/$content = str_replace(‘&’, ‘&’, $content);[/lang] in function twitter_stream_convert_to_xml($content) ?

Any help or insight would be a great relief… thanks!

Author’s gravatar

Hmm hadn’t spotted I was supposed to insert spaces after and before the code tags, sorry about that. Hopefully my post is still legible.

Author’s gravatar


I’ve removed my above fix for hiding @replies for now awaiting your advice.

You might also be interested to know that by removing the & conversion that your inline comment refers to as “Some sort of strange fix for unterminated entities in XML. Possibly related to PHP bug #36795.” I am now seeing the & symbol from tweets represented correctly in my twitter-stream. With your fix in place the twitter-stream was incorrectly displaying the html code representation of the character, making the tweet look strange.

Advice and comments on both of these issues much appreciated.


Author’s gravatar author

Hi Marc,

Sorry for the delay in replying I’ve been a little sick over the last two weeks and am still trying to catch up on work, so unfortunately replying to comments has been put on the back burner a little.

Removing @replies is a difficult subject that has been discussed a few times. Removing them using PHP will leave you with a small problem. You will ask for say 7 tweets, 2 might be @replies, PHP will remove them & you’ll only be able to display 5. Twitter do have a new option to remove @replies, but according to their documentation it has the same problem. The @replies are removed after they are retrieved meaning you will get back less than you originally asked for. This becomes a huge problem if you ask for 5 tweets and the last 5 tweets happened to be @replies. Does that make sense?

I’m not sure what is happening with the & symbols showing as &. It could be that you are using a version of PHP that no longer has that problem. I’ll see if I can alter the line of code tomorrow to only convert the & to & if it is appropriate instead of assuming it is wrong.

Thanks for the notes.

Author’s gravatar

Yes, that makes sense thanks. I’d only read the latest page of comments but having gone through the history I can see that this feature request has come up more than once!

My (uncle’s) site is currently only displaying 2 tweets instead of 3. When looking at Thierrylt’s twitter feed I can see that tweet 3 was a third party RTing @Thierrylt. My assumption is that this is therefore getting supressed with the plugin’s existing retweets=FALSE functionality in a similar manner to the loss of @replies that you just warned me about (instead of showing tweet 4).

If a complete solution to the above problems is not possible with the current Twitter API how about a partial solution where you give us the option to set both the max number of tweets to fetch in addition to the minimum number of tweets to display? That way we could safely filter RTs and @replies whilst having the option to display them if there is nothing else recent.

Sorry you’ve not been well and totally understand that you’ve got a day job to attend to – good luck!

Author’s gravatar

Was there ever a fix found for the &amp issue? I am having the & sign being displayed wrong… any help?

Author’s gravatar

So I added a line of code to the twitter-stream.php file

So far it looks like it does change the &amp to &…

Author’s gravatar

It seems that, from time to time, I get a timeout on twitter. It sometimes echoes “Your Twitter stream could not be collected. Normally this is caused by no XML feed being returned. Why this happens is still unclear.” but most of the time the site is not loading at all.

Everything works fine if I disable the script. I understand this is due to what you described in the description about XML, but can we do something about it saying that if we don’t get a response within 5-10 seconds, stop trying and show the rest of the content instead along with the error message?

Setting time out in the .php files doesn’t seem to fix this either. I’m not very good at php, but it really seems that the timeout function isn’t working at all.

Apart from this issue, the plugin is awesome and I’d like to do all I can to keep using it. Thanks in advance!

Author’s gravatar author

Hi Patrik,

Sadly no. If that error is returned it means Twitter didn’t return anything at all, and due to the way the logic in the plugin works the cache has already been destroyed. Because Twitter returned bupkis and the cache is empty we can’t return anything at all. The connection is made via a Twitter oAuth connection class and is set to timeout after 30 seconds. You can open the file (twitteroauth.php) and change the variables that determine the timeout to see if that helps, but normally Twitter should respond within 30 seconds.

If that doesn’t do anything I’m not sure what the problem is. If you disable the plugin does the issue go away?

Author’s gravatar

I’m getting an error when I display the Tweets on our page.


I’m also unable to nuke the cache. I get the error ‘Cache Deletion Failed!’

Any solution?

Author’s gravatar author


Did this resolve itself? Normally being unable to delete the cache is caused by PHP not having permission to remove the file. The script tried to give itself permissions, but sometimes it doesn’t have permission to give itself permission… If that makes sense.

Author’s gravatar

Is there a way to delete tha cache manually?

Author’s gravatar

Hello Paul.

Great plugin. We are using it to create a microblog/livestream via a protected Twitter account. One of the things we would like to do is show the date/time the tweet was created, as opposed to using the twitter standard “ago” format. In the XML I can see that this data is retrieved on the user_timeline GET, however I’m not savvy enough with PHP to hack it into the plugin. Can you help?

Author’s gravatar author

Hi Jamey,

You could try this. The only problem is that you’d need to hack the Twitter Stream plugin directly. If you don’t mind copying down the hack & redoing it if the plugin gets updated at some point, then it should work. I would add it as an option, but I don’t have access to my original code at the moment.

Anyway in the meantime here is how to change it.

First find line 387 in twitter-stream.php near the end of the line it should say ".twitter_stream_time_ago($tweet->created_at).". Change that to ".date('j F, Y', $tweet->created_at).". You can replace the ‘j F, Y’ with whatever letters you wish from the PHP date manual to get the format of date you need.

Hope that helps & I’ll try to get that option in soon, I can’t promise anything until after Christmas though unfortunately as it’s very busy at the moment.

Author’s gravatar

Thanks Paul. That didn’t seem to work, but got me close enough I came up with this:

Comment out line 379:
// $tweet->created_at = strtotime($tweet->created_at);

Change line 387 to this:
$o .= date(‘M. d, y H:i’, strtotime($tweet->created_at));

As you suggest, set the date format however preferred per the PHP manual. *Note: I removed the href on the date since I’m pulling from a protected twitter stream.

Sharing in case it helps you with the feature, or anyone else who may want to do the same hackery. 🙂

Author’s gravatar

Thanks Jamie for the date hack-exactly what i was after.

Author’s gravatar author

Thanks Jamey.

Honestly not sure why the code I shared didn’t work, but that is definitely a brilliant alternative to the way I suggested. Thanks for sharing it. 🙂

Author’s gravatar

any way to show your twitter icon next to your recent tweets? I don’t see how to do that. I changed the icon to show the one i wanted to but no go.

Author’s gravatar author


Do you mean your avatar? If so I’m sad to say the plugin doesn’t support that, but you could grab the URL to your Twitter avatar from Twitter and then place it next to your tweets & use CSS to style it however you need.

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