WordPress Plugin: Twitter Stream

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

written by

WordPress wizard, coding ninja and all round cool guy. Loves Sci-Fi, geeky stuff, and of course Firefly. Currently a self confessed addict of Korean & Japanese Pop.



Author’s gravatar

Hi there,

Is there a way to implement the twitter feed in my own custom html? Say if I wanted to wrap all the hashtags in a div, or throw in a small icon next to each tweet, would that be possible?

Also, since I have my Twitter account and Instagram account synced, it would be really cool if I could show the images posted with tweets, instead of just a link to the image. Would that be possible?



Author’s gravatar

Hi Rasmus,

There are tags pre-wrapped around hashtags and each tweet is wrapped in a paragraph tag, so using a bit of CSS you should be able to do those things. Unfortunately without hacking the plugin you can’t alter the HTML at this point. It may be something I’d add in the future, but I’ve got so much work to do outside of my plugins that I can only maintain & help at the moment.

Unfortunately not, again it might be possible for me to add it in the future, but again work is preventing me from having time spare to add new features.


Author’s gravatar

Hi Paul,

Thank you for your reply! I would definitely love to see the ability to customize the HTML and also to display images from Twitter or Instagram. Hope you get some time in the future to implement that!

I can do some CSS styling, but for instance I’d like to display the date of the tweet as the first thing, before the actual tweet. For that, the best thing would be to alter the HTML.

Meanwhile, I have another question:

How do I use the “echo” parameter? As per your documentation, it “controls if the tweets should be echoed out to the page or returned as a SimpleXMLObject for manipulation via PHP”. Does this mean that if I set it to false, I should be able to interact with a SimpleXMLObject? What kind of manipulating would it be possible to do, and could you possibly point me in the right direction on how to do that?

Sorry for all the questions. I am obviously not a PHP wiz. I appreciate you taking the time!


Author’s gravatar


No problem. As much as I’m limited on time I try my best to reply to any comments or fix any problems as soon as I can. ;)

That is actually one way you can do it. Using the ‘echo’ parameter. If you set it to false then it will return a JSON object. It used to be a SimpleXMLObject, but Twitter recently changed their format to JSON only when they upgraded their API. I just haven’t had a chance to change the docs yet.

With the JSON object you’d have access to all the data I use in the plugin so you could make your own HTML template. If you use:

The variable $response will contain the raw data returned from Twitter. This is a object that contains all the Tweets. To do something with it you can dome something like:

Hopefully that makes a little sense. If you are wondering where the twitter_stream_time_ago() function comes from. Well it’s a function I use in the plugin and since it is a global function you should be able to call it too.

I know this can seem complicated, but if you can afford to spend the time it can be very rewarding to get something like this working. If you do it this way, even if I update the plugin this code is very unlikely to break.

If you have any trouble then please do let me know & if you need more help than feasible here in the comments drop me an email either via the contact form or via my portfolio site and I’ll help out however I can.

Author’s gravatar


Awesome! Thank you so much! I will give it a go as soon as I get some more time to look at it. I will let you know how it works out or ask, if I get stuck.

Thanks again! :)

Author’s gravatar

Not a problem. That’s probably the best way to customize the HTML, I hadn’t thought about it until you mentioned it, but it should allow you to change the HTML as you want and survive through any updates.

Please do just shout if you have any problems, or if you manage to get it working I’d love to hear from you. If everything goes well I’ll see if I can add a small tutorial to this post to help anyone else who wants to customize the HTML too. :)

Author’s gravatar

You may have to replace $tweet->id to $tweet-id_str on line 391 in the twitter-stream.php file. $tweet->id was returning some ridiculous number. Cool plugin! Thanks!

Author’s gravatar

Thank you a lot for this amazing wp-plugin! It’s just what I was looking for.

Author’s gravatar

Hi Paul,
First, thanks for the awesome plugin.
Second, is there a way to somehow wrap the plug-in’s widget into a scrollable box? What I am trying to do is to have a fixed height for the area the widget will display.. and if the tweets in the widget are longer than the fixed height there would be a scroll bar to thr right side allowing users to scroll downward to see the rest of the tweets.
I hope that makes sense.. let me know,

Author’s gravatar

Hi Steve,

The plugin automatically generates a division (div) element around the tweets with the class of twitter-stream. You can use that as a scrollable element by using CSS to set a height for that class & then set the overflow to auto, if that doesn’t work you can try setting overflow-y to scroll.

Author’s gravatar

Thank you so much.. worked great!

Author’s gravatar

Hi Paul,

when I try to connect to my twitter account using the “/wp-admin/options-general.php?page=twitterstreamauth&wptwit-page=redirect” I get an 504 gateway timeout after 60 seconds.
Any idea why?

Thanks a lot!

Best regards,

Author’s gravatar


A 504 is an unusual error to get in this case. It is most commonly an error returned when the server cannot contact the server-side language parser. It is most common on Nginx + PHP installs when PHP dies and cannot be contacted by Nginx. In this case it could be that either your server is, for some reason, having trouble completing the redirect request (which sends you to Twitter to authorize the plugin) or that you hit a time when Twitter’s servers were unavailable.

Do you still get this error now when you try? If so I would ask your hosting support if they can shed any light on the issue as it could be a problem or side-effect with/from the way PHP is setup.

Author’s gravatar

Hi and thanks for a very nice and simple Twitter Stream for WordPress! It works just fine for me displaying the tweets in my footer. Though there is some strange issue with the permalinks in the timestamps of the tweets. The links are broken and typically end with 4.5967329801276E+17 in stead of 459717020226191361 which is the correct id. Should I try to deauthorize the app and re-add it? Another question: All links to Twitter are in http-form, is it easy to change that to https?

Author’s gravatar


I apologise for taking such a long time to reply. The site got hit badly with spam & trying to clean it up has been a nightmare.

I’m not sure what is happening there, the links are grabbed straight from the result supplied by Twitter. Is this still occurring for you? I’m not seeing it on my install, but I’m happy to take a look if you are still seeing the problem.

Leave a Reply

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

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code class="" title="" data-url=""> <del datetime=""> <em> <i> <q cite=""> <strike> <strong> <pre class="" title="" data-url=""> <span class="" title="" data-url="">