Create a Twitter Feed With Hash Tag And Cache Support

Written by Kevin Liew on 20 Feb 2012
59,585 Views • Tutorials


Due to popular demand, this tutorial is actually a revisit from my previous Twitter tutorial - Create a dead simple Twitter feed with jQuery. A lot of readers requested to be able to parse hashtag. So, I've decided to make a new version that able to do both plus some enhancements.

The foundation of this script will be the same, but with some modification to accept both hashtag and normal user feed. It will be smart enough to switch but with one tiny caveat which I will mention later on. You can see the preview or download it to play with the code.

UPDATE: We have written an updated version of Twitter API tutorial based on Twitter Newest API 1.1. - Easiest Way to Retrieve Twitter Timeline and Hashtags


  • Able to parse User Timeline and hashtag (multiple hashtags by using OR operator to separate hashtags)
  • Cache result to avoid rate limits restriction from Twitter.
  • Decided to not using Cronjob to renew the cache, it uses date comparison with PHP.
  • Using links/hashtag/alias script to parse the tweet.


HTML is basically the same as the old one, nothing fancy.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "">
<html xmlns="" xml:lang="en">
    <meta http-equiv="Content-Type" content="text/html;charset=UTF-8" />
    <script data-src="" type="text/javascript"></script>
    <script data-src="twitter.js"></script>
    <div id="jstwitter">


CSS, nothing special, just simply style it up to make it presentable. However, this is a list of class that you can use to style it up:

  • .twtr-hashtag: #abc
  • .twtr-hyperlink: hyperlink
  • .twtr-atreply: #abc
  • .text: tweet
  • .user: username
  • .time: relative time (10 minutes ago)
body {

#jstwitter {
	width: 300px;
	font-family: georgia;
	font-size: 12px;
	color: #333333;
	padding: 10px 10px 0 10px;
	margin:0 auto;
	border:5px solid #eaeaea;
	box-shadow:0 0 5px rgba(0, 0, 0, 0.3);

#jstwitter h1 {

#jstwitter .tweet {
	margin: 0 auto 15px auto;
	padding: 0 0 15px 0;
	border-bottom: 1px dotted #ccc;

#jstwitter .tweet a {
	text-decoration: none;
	color: #03a8e5;

#jstwitter .tweet a:hover {
	text-decoration: underline;

#jstwitter .tweet .text {

#jstwitter .tweet .time, #jstwitter .tweet .user {
	font-style: italic;
	color: #666666;

#jstwitter .tweet:last-child {


Okay, the core. This jQuery script added a few if-else statements to toggle between hashtag and user timeline. I put inline comment in every crucial code for better understanding of what it does.

The way it works:

  1. Firstly, you can set either hashtag or username. If you filled in hashtag, username will be ignore. If you want username, you need to leave hashtag empty.
  2. You can set other setting such as number of tweet, cache expiry date, append to element.
  3. In loadTweet function, it constructs different request and pass it to PHP script, and then PHP script will format the request with the right Twitter API and grab the content. The PHP script is responsible to handle the cache as well. Depend on how long you set in the cacheExpiry, it will renew the cache accordingly.
  4. Finally, the Javascript will parse the returned JSON based on the type of API. (hashtag and user timeline's JSON is a bit different in structure)

Some tips and tricks

Multiple Hashtags: You can separate the hastags with OR operator. eg: '%23jquery OR %23css'

Multiple Users: You can use 'from:account' and separate with OR operator. eg: 'from:quenesswebblog OR from:favbulous'

	// Set twitter hash/user, number of tweets & id/class to append tweets
	// You need to clear tweet-date.txt before toggle between hash and user
	// for multiple hashtags, you can separate the hashtag with OR, eg:
	// hash: '%23jquery OR %23css'
	hash: '%23jquery', //leave this blank if you want to show user's tweet
	user: 'quenesswebblog', //username
	numTweets: 5, //number of tweets
	cacheExpiry: 2, //get the new cache in 2 hours
	appendTo: '#jstwitter',
	// core function of jqtweet
	loadTweets: function() {
		var request;
		// different JSON request {hash|user}
		if (JQTWEET.hash) {
			request = {
				q: JQTWEET.hash,
				expiry: JQTWEET.cacheExpiry,				
				api: ''
		} else {
			request = {
				screen_name: JQTWEET.user,
				include_rts: true,
				count: JQTWEET.numTweets,
				include_entities: true,
				expiry: JQTWEET.cacheExpiry, 
				api: ''

			url: 'tweets-grab.php',
			type: 'GET',
			dataType: 'json',
			data: request,
			success: function(data, textStatus, xhr) {

				var text, name, html = '<div class="tweet"><span class="text">TWEET_TEXT</span><span class="time"><a href="URL" target="_blank">AGO</a></span> by <span class="user">USER</span></div>';
				try {
					//Twitter Search API has different JSON Structure
					if (JQTWEET.hash) data = data['results'];
					// append tweets into page
					for (var i = 0; i < data.length && i < JQTWEET.numTweets; i++) {
						name = (JQTWEET.hash) ? data[i].from_user : data[i].user.screen_name;
						    html.replace('TWEET_TEXT', JQTWEET.ify.clean(data[i].text) )
						        .replace(/USER/g, name)
						        .replace('AGO', JQTWEET.timeAgo(data[i].created_at) )
						        .replace('URL', '' + data[i].from_user + '/status/' + data[i].id_str )
				} catch (e) {
					alert('No data returned, you might want to clear tweets-date.txt.');


      * relative time calculator FROM TWITTER
      * @param {string} twitter date string returned from Twitter API
      * @return {string} relative time like "2 minutes ago"
    timeAgo: function(dateString) {
		var rightNow = new Date();
		var then = new Date(dateString);
		if ($.browser.msie) {
			// IE can't parse these crazy Ruby dates
			then = Date.parse(dateString.replace(/( \+)/, ' UTC$1'));

		var diff = rightNow - then;

		var second = 1000,
		minute = second * 60,
		hour = minute * 60,
		day = hour * 24,
		week = day * 7;

		if (isNaN(diff) || diff < 0) {
			return ""; // return blank string if unknown

		if (diff < second * 2) {
			// within 2 seconds
			return "right now";

		if (diff < minute) {
			return Math.floor(diff / second) + " seconds ago";

		if (diff < minute * 2) {
			return "about 1 minute ago";

		if (diff < hour) {
			return Math.floor(diff / minute) + " minutes ago";

		if (diff < hour * 2) {
			return "about 1 hour ago";

		if (diff < day) {
			return  Math.floor(diff / hour) + " hours ago";

		if (diff > day && diff < day * 2) {
			return "yesterday";

		if (diff < day * 365) {
			return Math.floor(diff / day) + " days ago";

		else {
			return "over a year ago";
	}, // timeAgo()
      * The Twitalinkahashifyer!
      * Eg:
      * ify.clean('your tweet text');
    ify:  {
      link: function(tweet) {
        return tweet.replace(/\b(((https*\:\/\/)|www\.)[^\"\']+?)(([!?,.\)]+)?(\s|$))/g, function(link, m1, m2, m3, m4) {
          var http = m2.match(/w/) ? 'http://' : '';
          return '<a class="twtr-hyperlink" target="_blank" href="' + http + m1 + '">' + ((m1.length > 25) ? m1.substr(0, 24) + '...' : m1) + '</a>' + m4;

      at: function(tweet) {
        return tweet.replace(/\B[@@]([a-zA-Z0-9_]{1,20})/g, function(m, username) {
          return '<a target="_blank" class="twtr-atreply" href="' + username + '">@' + username + '</a>';

      list: function(tweet) {
        return tweet.replace(/\B[@@]([a-zA-Z0-9_]{1,20}\/\w+)/g, function(m, userlist) {
          return '<a target="_blank" class="twtr-atreply" href="' + userlist + '">@' + userlist + '</a>';

      hash: function(tweet) {
        return tweet.replace(/(^|\s+)#(\w+)/gi, function(m, before, hash) {
          return before + '<a target="_blank" class="twtr-hashtag" href="' + hash + '">#' + hash + '</a>';

      clean: function(tweet) {
        return this.hash(;
    } // ify


$(document).ready(function () {
	// start jqtweet!


Right, the final part of this tutorial - the PHP. It:

  • Checks for Cache Expiry interval
  • Constructs the API call
  • Retrieves JSON data from Twitter
  • Saves both JSON data and date

We need two text files:

  • tweets-cache.txt: contains latest data in JSON format
  • tweets-date.txt: contains the date of last retrieval

In the introduction, I mentioned about a small caveat of this script - Whenever you switch between hashtag and username, you need to clear the tweets-date.txt.


$cache = 'tweets-cache.txt';
$date = 'tweets-date.txt';

$currentTime = time(); // Current time

// Get cache time
$datefile = fopen($date, 'r');
$cacheDate = fgets($datefile);

//check if cache has expired
if (floor(abs(($currentTime-$cacheDate) / 3600)) <= $_GET['expiry'] && $cacheDate) {

	$cachefile = fopen($cache, 'r');
	$data = fgets($cachefile);

} else { //renew the cache

	//toggle between API
	if ($_GET['q']) 
		$data = file_get_contents($_GET['api'] . '?q=' . urlencode($_GET['q']));   
	} else if ($_GET['screen_name']) 
		$data = file_get_contents($_GET['api'] . '?screen_name=' . $_GET['screen_name'] . '&count=' . $_GET['count'] . '&include_rts=' . $_GET['include_rts'] . '&include_entities=' . $_GET['include_entities']);   
	// update cache file
	$cachefile = fopen($cache, 'wb');  

	// update date file
	$datefile = fopen($date, 'wb');  
	fwrite($datefile, utf8_encode(time()));  

header('Content-type: application/json');
echo $data;


So, that's how you do it, support both hashtag and username, easy to style and uses cache to overcome Twitter rate limits. You just have to remember, whenever you switch between hashtag and username, remember to clear the content of tweets-date.txt.

That's it, hope you will find this useful and any questions, just drop me a comment and I will try my very best to answer it quickly. Stay tuned with queness! For more cool and updated javascript inspiration, tutorials, plugins, you can follow us on twitter or like us on facebook.

Demo 1Demo 2Download
Join the discussion

Comments will be moderated and rel="nofollow" will be added to all links. You can wrap your coding with [code][/code] to make use of built-in syntax highlighter.

Hassan Raza 8 years ago
Awesome. Interesting tutorial.
Rebecca 8 years ago
Hi Kevin, Wonderful script, thanks very much for sharing! Works great when using the hash, but I'm having a small problem when just using the user. I did update the JS file, set hash to '' and user:mytwitterusername and my twitterusername.json. I also cleared the tweets-date.txt file. Can't understand why I'm getting blank results.

In testing, I did try to directly open in my Firefox browser: and it comes up with an error:

{"error":"Could not authenticate you.","request":"/1/statuses/mytwitterusername.json/"}

I suspect twitter wants to authenticate? Maybe there's a step I'm missing?

Really apprecaite your help, thank you! Rebecca
Rebecca 8 years ago
Well, I managed to figure this out. I needed an OAuth token, and with the help of this site: I was able to add the extra values I needed for the twitter.js file.

request = {
screen_name: JQTWEET.user,
include_rts: true,
count: JQTWEET.numTweets,
include_entities: true,
expiry: JQTWEET.cacheExpiry,
oauth_nonce: 20058557,
oauth_consumer_key: 'enter-value',
oauth_signature_method: 'enter-value',
oauth_version: '1.0',
oauth_token: 'enter-value',
oauth_signature: 'enter-value',
api: '
Otreva 8 years ago
Let me start by saying thanks Kevin for the awesome script!

I had the same problem as some others where the script wouldn't work as is on one server but it did another. The reason is that allow_url_fopen was set to off for me. By changing this to "allow_url_fopen = on" in php.ini solved my issue. For those on Plesk you can follow this but change steps 3-5 to change "allow_url_fopen = Off" to "allow_url_fopen = On".

Kevin, I am having one issue though with multiple users, if I want to use 3 users, what should the exact syntax be on line 5-6?

I have tried to no avail:

hash: '',
user: 'quenesswebblog OR twitter OR otreva',


hash: '',
user: 'from:quenesswebblog OR from:favbulous',

dragonpearl 8 years ago
Great tutorial! Quick question that I am struggling with. Am I able to pull only the tweets for a specific user and filter for a specific hash used by that user and not include any replies? If so, any guidance would be greatly appreciated.
Michael 8 years ago
Seriously stellar tutorial! Thank you!
izinux 8 years ago
I have tried many different things but I have had no luck on getting any data in cache. I have deleted the tweets-date.txt many many many times however nothing seems to be saving.

hash: '%23RealShitPeopleSay',
user: '',
numTweets: 5,
cacheExpiry: 1,
appendTo: '#jstwitter'

I left the rest of the script stalk except for design.

Error - "No data returned, you might want to clear tweets-date.txt"

I would appreciate any help possible. Thank you !!!

PS. When I used the old cache data from the download it displays but its the dummy data you had.
Niels 8 years ago
Hi there,

Thanks for sharing the information, but i got a question regarding this plugin. Is it possible to show the usertweeds and a certain hashtag? So both will be showed in the menu?

Thank you very much.
Kevin Liew Admin 8 years ago
Not so sure, but you can try using this:

'%23jquery OR 'from:quenesswebblog'
Niels 8 years ago
It doesn't seem to work. :)
Shari 8 years ago
Hi there,

Thanks for the great post.

I have one question: I'm trying to implement three different twitter feeds on one page. One twitter feed works like a charm. However, when I add another one, the first one stops working and the second one starts showing its tweets. I can't get them both to work at the same time. Is there a way to show three different feeds on one page?

Thanks in advance!

Qawiem 8 years ago
hi, I wonder why I couldn't see your tutorial :(
Andy 8 years ago
Love this script!

One thing i've noticed though:
what is "$_GET['hours']" in tweets-grab.php?
shouldn't it be "$_GET['cacheExpiry']" ?
Kevin Liew Admin 8 years ago
You're right, I don't know where did that coming from :p
I have updated the script, thanks!
Andy 8 years ago
Sorry, i meant "$_GET['expiry']"
Michael 8 years ago
Thank you for the outstanding, simple script!

I had an issue where my local environment displayed everything perfectly, but my staging server (Hostgator shared hosting) was displaying an empty DIV. I racked my brain then finally broke down and called them. They said their mod_security was preventing tweets-grab.php from running. The moment they allowed it to run it worked so get in touch with your hosting provider if you experience a similar issue!
Celio 8 years ago
Hi Kevin, I want to thank you for this wonderful script. I'm testing it locally (wamp) for a wordpress site that I'm creating and it's working fine, except for one thing. I'm getting blank results each time the cache expires, but if I refresh the page I get the results as expected. Thanks