DM Blog

In April of last year (2010), I blogged about using Twitter’s geo-data when displaying tweets on my websites, and followed that up in May 2010 with my first code-oriented blog article, "PHP Code: Twitter CRON Job". Since then, Twitter has been busy enhancing their API and I’ve made a couple changes to that CRON job along the way to take advantage of these enhancements.

The biggest change to my CRON job is the use of Twitter’s Tweet Entities, so that’s what I’ll focus on in this article.

To get started, you can download the new script I’m using here: twitter-cron.php (The basic structure of the script has stayed the same as before, so in this article I’ll only focus on the incorporation of tweet entities, but if you want a more in-depth walk-through of what each part of the script is doing, I suggest reading my older article that I linked to above.)

Here’s what Twitter’s developer docs have to say about tweet entities:

Tweet text can potentially mention other users or lists, but also contain URLs, media, hashtags… Instead of parsing the text yourself to try to extract those entities, you can use the entities attribute that contains this parsed and structured data.

On my sites, I’m using the URL entities to display long URLs in a shorter, more visually appealing way; hashtag entities to make hashtags clickable links; user_mention entities to make usernames clickable links; and media entities to display any linked photos right on the page… (I’ll go more in-depth into each one of these below.)

Here’s the new linkify_text() function which contains the majority of the changes, and all of the tweet entities goodness:

private function linkify_text($raw_text, $tweet = NULL)
{
	// first set output to the value we received when calling this function
	$output = $raw_text;

	// create xhtml safe text (mostly to be safe of ampersands)
	$output = htmlentities(html_entity_decode($raw_text, ENT_NOQUOTES, 'UTF-8'), ENT_NOQUOTES, 'UTF-8');

	// parse urls
	if ($tweet == NULL)
	{
		// for regular strings, just create <a> tags for each url
		$pattern		= '/([A-Za-z]+:\/\/[A-Za-z0-9-_]+\.[A-Za-z0-9-_:%&\?\/.=]+)/i';
		$replacement	= '<a href="${1}" rel="external">${1}</a>';
		$output			= preg_replace($pattern, $replacement, $output);
	} else {
		// for tweets, let’s extract the urls from the entities object
		foreach ($tweet->entities->urls as $url)
		{
			$old_url		= $url->url;
			$expanded_url	= (empty($url->expanded_url))	? $url->url	: $url->expanded_url;
			$display_url	= (empty($url->display_url))	? $url->url	: $url->display_url;
			$replacement	= '<a href="'.$expanded_url.'" rel="external">'.$display_url.'</a>';
			$output			= str_replace($old_url, $replacement, $output);
		}

		// let’s extract the hashtags from the entities object
		foreach ($tweet->entities->hashtags as $hashtags)
		{
			$hashtag		= '#'.$hashtags->text;
			$replacement	= '<a href="https://twitter.com/search?q=%23'.$hashtags->text.'" rel="external">'.$hashtag.'</a>';
			$output			= str_ireplace($hashtag, $replacement, $output);
		}

		// let’s extract the usernames from the entities object
		foreach ($tweet->entities->user_mentions as $user_mentions)
		{
			$username		= '@'.$user_mentions->screen_name;
			$replacement	= '<a href="https://twitter.com/'.$user_mentions->screen_name.'" rel="external" title="'.$user_mentions->name.' on Twitter">'.$username.'</a>';
			$output			= str_ireplace($username, $replacement, $output);
		}

		// if we have media attached, let’s extract those from the entities as well
		if (isset($tweet->entities->media))
		{
			foreach ($tweet->entities->media as $media)
			{
				$old_url		= $media->url;
				$replacement	= '<a href="'.$media->expanded_url.'" rel="external" class="twitter-media" data-media="'.$media->media_url.'">'.$media->display_url.'</a>';
				$output			= str_replace($old_url, $replacement, $output);
			}
		}
	}

	return $output;
}

Using Tweet Entities to Display URLS

Twitter is now shortening all URLs using there own t.co domain, but they still give you access to the original (long) URI through the tweet entities, and they also give you a shorter "display URL" which is nicer to work with, (at least visually), within the context of tweets.

So, for example, if I include the link "https://DanielMenjivar.com/charts/#samples/calzada-del-cerro" in a tweet, it gets shortened to "https://t.co/gixlOwE" but I still have access to the original/long URI using tweet entities, in addition to a display URL of "DanielMenjivar.com/charts/#samples…" On my sites, I don’t use the t.co link at all and I just link to the original/long URL, but I use the shorter display URL as the link text.

Using Tweet Entities to Display HashTags

Instead of just displaying hashtags as plain text to visitors on my site, I convert all hashtags in my tweets to links (which link to Twitter’s search). So instead of displaying "#hashtags", I display "#hashtags".

Using Tweet Entities to Display Usernames

The user_mentions array contains a list of users mentioned in the tweet. Rather than displaying plain text @usernames, I’m converting them into links: @DanielMenjivar

Using Tweet Entities to Display Photos & Media

You can see from the code snippet above that I’m still displaying the media URL in the tweet text, but it links to the expanded URL for that photo/media. Also, I’m using a data-media attribute on the <a> tag so that I can bypass the link and display this photo right on the page (using JavaScript/Fancybox).

Hopefully this helps someone looking to get started with tweet entities. Let me know what questions you have using the comments section below.