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?
- Connect to Twitter securely using oAuth. (required)
- Show the twitter timeline for any public username.
- Choose how many tweets to show.
- A Widget or template function is available.
- File caching to stop API overuse.
- Optional date shown in xx ago format, also links to permalink for the tweet. (Requested by Ron)
- Customizeable via CSS. (see the ‘Can I Style It?’ section below)
- Authentication for better API limiting & ability for protected users to show their tweets.
- @replies now link to the user profile of the user you are replying to.
- #tags now link to the Twitter search page for that hash tag.
- Link to user’s profile, customizable via CSS & via function parameter.
- Follower count can now be shown.
- 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:
- Download the zip file and unzip it to somewhere, say your desktop.
- With any good SFTP client upload the extracted folder to your
wp-content/plugins/
folder. - 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:
1 |
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:
.at-reply
for @replys..hash-tag
for #tags.a.twitter-link
for autolinked URL’s within the timeline.a:hover.twitter-link
for autolinked URL’s within the timeline when they are hovered over.a.twitter-date
for the date permalink.a:hover.twitter-date
for the date permalink when it’s hovered over..profile-link
for the newly added link to user profile..follower-count
for the newly added follower count.
Can I Have A Options List?
Sure. The basic usage for in the template is this.
1 |
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.
1 2 3 4 5 6 7 8 9 |
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
- Serbo-Croatian Translation – Thanks to Borisa Djuraskovic (WebHostingHub)
- German Translation – Thanks to Stefan Moeller
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
Paul Robinson
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.
Paul Robinson
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.
Gareth Pelly
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.
Paul Robinson
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.
Bryon Powell
Has there been a recent change on your plugin or the Twitter side of things that changed the tweet listing to reverse chronological?
Paul Robinson
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)
toksort($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.
Paul Robinson
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. 🙂
Bryon Powell
Paul,
Thanks for finding and fixing the issue so quickly. (And for the mention in the changelog!)
Paul Robinson
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. 🙂
Richard
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!
Paul Robinson
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.
Richard
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!
Paul Robinson
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.
Richard
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
Paul Robinson
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.
Richard
Hey Paul!
I tried filling it in all over again and it worked!!!!!
Thanks so much! This plug in is perfect!!!
– Richard
Paul Robinson
No problem, glad it worked for you. 🙂
Man and Van Richmond
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.
Massa P
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.
Paul Robinson
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. 😉
Paul Robinson
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.
Massa P
Thank you so much for the quick response! 🙂
Paul Robinson
Not a problem, I just hope it works okay. 😉
Massa P
Hi, following up on the previous issue… I’m still getting the same error messages after the update.
Paul Robinson
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.
Paul Robinson
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. 😉
Chicago Limousine Service
Hi,
I have submitted a comment here but it doesn’t appear. I think it goes to the spam folder. Please reconsider my comment.
Website design
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.
Massa P
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! 🙂
Paul Robinson
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. 🙂
Massa P
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:”
“;}
Paul Robinson
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. 😉
Limoges Boxes
Hi Paul,
Can I still use this even I already have facebook on my site? It is just like this.
Paul Robinson
Errrm… Facebook?! This plugin is for putting Twitter on your WordPress blog.
Donnie SC Lygonis
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
Paul Robinson
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. 🙁
Donnie SC Lygonis
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?
Paul Robinson
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.
Paul Robinson
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.
Rob Searles
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
Paul Robinson
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?
Rob Searles
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
QS
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..
Paul Robinson
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 .
titi
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 ? 😉
Paul Robinson
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.
titi
Yep I figured it out after my comment. Thanks 😉
jason
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)?
Paul Robinson
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.
Jason
Perfect! Thanks for the quick reply!
Paul Robinson
No worries. 😉
Neelesh
Any further word on the oAuth issue or a means I can keep informed of the situation?
BTW thanks for a wonderful plugin!
Paul Robinson
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.
Paul Robinson
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. 🙂
Richard Foreman
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
Paul Robinson
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.
Richard Foreman
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.
Paul Robinson
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?
Richard Foreman
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.
Paul Robinson
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.