PHP Twitter User Timeline & Search Plugin

• Created: 10/02/2013
• By: Democode.net
• http://codecanyon.net/user/cawebstore
• Email: support@democode.net
• Demo: http://www.democode.net

Thank you for purchasing my script. If you have any questions that are beyond the scope of this help file, please feel free to email via Codecanyon here. Thank you so much!

Intro

This PHP script enables you to add a Twitter user timeline and/or Twitter search results on your site. The script is easy to install, use and it's modifiable. You can add the script to your site by copying and pasting the PHP or jQuery code that is bundled in this software package, but before we begin and go over these steps, let's first look into what this script requires.

Requirements

• Register an account on the Twitter Developers website and create an app (more information can be found here)
• Make sure that your PHP version has the cURL and JSON extensions loaded (more information can be found here)

Register an account on the Twitter Developers website and create an app

Since we will be using the Twitter API to retrieve user timeline and search data, it's necessary to have an account on the Twitter Developers website and to have an app created.

Step 1 Go to: https://dev.twitter.com/

Step 2 Sign in or create an account

Step 3 Go to: https://dev.twitter.com/apps

Step 4 Create a new app

Step 5 Enter a name for the app

Step 6 Enter a description for the app

Step 7 Enter a URL for the app

Step 8 (optional) Enter an icon for the app

Step 9 Choose Read only for the access type because this is all that this plugin requires

Step 10 Leave the callback URL empty since this app shows tweets and search results. Therefore, it's not necessary for us to request sign in credentials etc.

Step 11 After entering all necessary information, click on "Create your Twitter application".

Step 12 (very important) Then view your newly created app and copy and the following credentials into a text editor and keep this information handy for when we edit our configuration file in the Installation section of this instructional manual.

• Consumer key
• Consumer secret
• Access token
• Access token secret

Installation

Upload files to server or web hosting account
Ok so now that we are ready to install the 'PHP Twitter User Timeline & Search Plugin script' on our web hosting account or server, we can decide on where to install the files. For example, if we were to install the script in the root section of our site, we would upload the "twitter_api_pkg" folder as well as all files and folders found within it, to the root of our site. Remember that the "twitter_api_pkg" can be found in the "php-twitter-user timeline-and-search-plugin" folder.

Make the 'caches' folder writable
Twitter often sets limits on API requests and for this reason, it's always good to cache API requests on very active websites. Of course before we can cache any data, we must make sure that the cache folder is writable. To do this, locate the 'caches' folder which is located in the "twitter_api_pkg" folder and make sure that the permissions are set to 777.

Configure your script
Since no two sites are alike, we must configure the 'PHP Twitter User Timeline & Search Plugin script' to work with our site. To begin, open the 'twitter_config.php' in a text editor and prepare to edit the lines of code in this file. The 'twitter_config.php' file can be found in the "twitter_api_pkg" folder. Below is an explanation of what each line of code does and how you can edit them.

Line: define('TWITTER_API_PKG_DIR','/');
Replace "/" with the path of the directory in which the 'twitter_api_pkg' folder is installed. If installed in the root directory, leave as is.
Account & APP Setup of this manual.

Line: define('TWITTER_CONSUMER_KEY', '*Consumer key');
Replace "*Consumer key" with the Consumer key that you copied from the Twitter website (this was explained in the Twitter Developers (API)
Account & APP Setup of this manual.

Line: define('TWITTER_CONSUMER_SECRET', '*Consumer secret');
Replace "*Consumer secret" with the *Consumer secret that you copied from the Twitter website (this was explained in the Twitter Developers (API)
Account & APP Setup of this manual.

Line: define('TWITTER_ACCESS_TOKEN', '*Access token');
Replace "*Access token" with the Access token that you copied from the Twitter website (this was explained in the Twitter Developers (API)
Account & APP Setup of this manual.

Line: define('TWITTER_ACCESS_TOKEN_SECRET', '*Access token secret');
Replace "*Access token secret" with the Access token secret that you copied from the Twitter website (this was explained in the Twitter Developers (API)
Account & APP Setup of this manual.

Line: define('TWITTER_CACHE_FOLDER', $_SERVER['DOCUMENT_ROOT'] . 'twitter_api_pkg/caches/twitter-');
This is the directory in which user timeline activity is cached. Replace $_SERVER['DOCUMENT_ROOT'] . 'twitter_api_pkg/caches/twitter-' with the correct path. If you have this plugin installed in the root directory, the path may already be correct. If you'd prefer not to cache user timeline Tweets, you can turn off caching by modifying the following line:

define('TWITTER_CACHE_TWEETS', true);
to
define('TWITTER_CACHE_TWEETS', false);

Line: define('TWITTER_CACHE_TIME', 5);
the 5 represents 5 minutes. You can change this number by modifying it - keep in mind that the script only accepts cache time in minutes. Of course if you have TWITTER_CACHE_TWEETS set to false, this field will be ignored.

Line: define('TWITTER_USER_TIMELINE_COUNT', 5);
Replace the number 5 with the number of tweets that you'd like to display or leave as is. Please keep in mind that 200 is the maximum number of tweets that can be displayed (Twitter set the limit to 200).

Line: define('TWITTER_USER_TIMELINE_HYPERLINK_URLS', true);
Do you want URLs in your timeline to be automatically tranformed into clickable links? If yes, leave the value as is. If not, change the true to false. Keep in mind that links which have been "cut off" due to the link being at the end of a summarized tweet (due to the Tweet being too long), will not by hyperlinked (prevents broken links).

Line: define('TWITTER_USER_TIMELINE_HYPERLINK_HASHTAGS', true);
When set to true, hashtags are hyperlinked. When set to false, hashtags are shown in plain text. Hyperlinks help people find tweets on Twitter which are related to the mentioned hashtag.

Line: define('TWITTER_USER_TIMELINE_HYPERLINK_USER_MENTIONS', true);
When set to true, Twitter screen names which are mentioned in Tweets, are automatically hyperlinked. If set to false, Twitter screen names are shown in plain text.

Line: define('TWITTER_CACHE_SEARCH_FOLDER', $_SERVER['DOCUMENT_ROOT'] . 'twitter_api_pkg/caches/twitter-');
This is the directory in which Twitter search results are cached. Replace $_SERVER['DOCUMENT_ROOT'] . 'twitter_api_pkg/caches/twitter-' with the correct path. If you have this plugin installed in the root directory, the path may already be correct. If you'd prefer not to cache Twitter search results, you can turn off caching by modifying the following line:

define('TWITTER_CACHE_SEARCH', true);
to
define('TWITTER_CACHE_SEARCH', false);

Line: define('TWITTER_CACHE_SEARCH_TIME', 5);
the 5 represents 5 minutes. You can change this number by modifying it - keep in mind that the script only accepts cache time in minutes. Of course if you have TWITTER_CACHE_SEARCH set to false, this field will be ignored.

Line: define('TWITTER_SEARCH_COUNT', 15);
Twitter has the default set at 15 and the maximum number of results that can be displayed is 100. If you set this value lower than 15, our script will automatically remove the excess number of results.

Line: define('TWITTER_SEARCH_HYPERLINK_URLS', true);
Do you want URLs in your search feed to be automatically tranformed into clickable links? If yes, leave the value as is. If not, change the true to false. Keep in mind that links which have been "cut off" due to the link being at the end of a summarized tweet (due to the Tweet being too long), will not by hyperlinked (prevents broken links).

Line: define('TWITTER_SEARCH_HYPERLINK_HASHTAGS', true);
When set to true, hashtags are hyperlinked. When set to false, hashtags are shown in plain text. Hyperlinks help people find tweets on Twitter which are related to the mentioned hashtag.

Line: define('TWITTER_SEARCH_HYPERLINK_USER_MENTIONS', true);
When set to true, Twitter screen names which are mentioned in Tweets, are automatically hyperlinked. If set to false, Twitter screen names are shown in plain text.

Line: define('TWITTER_SEARCH_RESULTS_TYPE', 'mixed');
How would you like the search results to be sorted? By default, the results are 'mixed' which means that a mix of recent and popular tweets are displayed. If you'd like to change the sort order, you can enter 'recent' or 'popular'.

Important!
After you've made changes to your 'twitter_config.php', it's advised (as a safety precaution) that you set the permissions of the file to read only.

Now we are ready for action!
Now that are script is ready for use, we can implement it into our existing scripts. For an explanation of how it all works, please proceed to the Usage section.

Usage

In the "php-twitter-user timeline-and-search-plugin" folder you will find 6 example files:

index.php

In this file there are 3 examples on how to use this script, but before we cover the examples, let's look at which files we need to include for the script to function properly. Below are the PHP codes that you need to add to the top of the file that you wish to embed tweets into:

<?php
require_once "twitter_api_pkg/twitter_config.php";
require_once "twitter_api_pkg/classes/twitterapirequest.php";
require_once "twitter_api_pkg/functions/twitter_user_timeline.php";
require_once "twitter_api_pkg/functions/twitter_search.php";
?>

Note that you may need to modify the path of the files depending on where you are installing.

Note that you only need to add line require_once "twitter_api_pkg/functions/twitter_user_timeline.php"; on pages that you will add Twitter user timeline results to.

Also note that you only need to add line require_once "twitter_api_pkg/functions/twitter_search.php"; on pages that you will add Twitter search forms or search results to.

Add this line into the head section (you may need to modify the path depending on where 'twitter_api_pkg' is installed):

<link rel="stylesheet" type="text/css" href="twitter_api_pkg/twitter.css">

Add the two lines below in your head section if you are adding a search form a Google map being shown:

<script src="https://maps.googleapis.com/maps/api/js?sensor=false&libraries=places"></script>
<script src="twitter_api_pkg/javascript/location_map_finder.js"></script>

(1) Add the line below on a page where you'd like to show a Twitter search form:

<?php echo twitter_generate_search_form('index.php',true,true,true,true,$_GET); ?>

There are 5 variables that you can change on this function. Below is a list of each value explained.

Index.php is the file that we are send that form variables to. This can be any page. See this section for information on which lines of code you need to add to the page that you are send the variables to.

true do you want to show a languages select menu? If yes, then leave as true if no, then change to false.

true do you want to show a results type select menu? If yes, then leave as true if no, then change to false.

true do you want to show coordinates inputs? If yes, then leave as true if no, then change to false.

true do you want to show a Google map? If yes, then leave as true if no, then change to false.

(1.1) Paste the code below into the page that you'd like to send form variables to and show search results.

<?php echo twitter_search_php($_GET);?>

(2) Paste the code below into the page that you'd like to display user timeline results on:

<?php echo twitter_user_timeline_php('google');?>

Change 'google' to the screen name of the Twitter user that you'd like to display results for.

(3) Paste the code below into the page that you'd like to display Twitter search results on:

<?php echo twitter_search_php('New York','en','recent','40.757332,-73.955556,10mi'); ?>

There are 4 variables that you can change here:

New York change this to your search query and remember that you can use search operators as well. For more info see this section.

en is the language. Leave empty for any language or change en to the language code of your choice. Remember that you can choose from these language codes.

recent is the results type (sort order). You can leave this empty. If left empty, the function will use the value you entered in the twitter_config.php file. If you wish to enter a value here, you may choose between recent, mixed or popular.

40.757332,-73.955556,10mi is the geocode. If left empty, the function will not filter tweets by distance. If a value is entered, the results will be filtered by coordinates. Note that Twitter seems to only return results filtered by distance when the results type "recent" is selected. Remember to enter values in this format for geocode:

"latitude,longitude,radius" radius units must be specified as either "mi" (miles) or "km" (kilometers).

jquery_example.php

The above file contains jQuery example code. Note that the jQuery code embed options have a slight advantage over the PHP code embed options because results can be auto refreshed and pageload times might be faster when the Twitter API is slow to respond because your page doesn't wait on the Twitter API to respond.

To start, add these PHP lines of code to the top of your page:

<?php
require_once "twitter_api_pkg/twitter_config.php";
require_once "twitter_api_pkg/functions/twitter_user_timeline.php";
require_once "twitter_api_pkg/functions/twitter_search.php";
?>

Note that you may need to modify the path of the files depending on where you are installing.

Note that you only need to add line require_once "twitter_api_pkg/functions/twitter_user_timeline.php"; on pages that you will add Twitter user timeline results to.

Also note that you only need to add line require_once "twitter_api_pkg/functions/twitter_search.php"; on pages that you will add Twitter search forms or search results to.

Add this line into the head section (you may need to modify the path depending on where 'twitter_api_pkg' is installed):

<link rel="stylesheet" type="text/css" href="twitter_api_pkg/twitter.css">

Add this line into the head section if you don't already have the jQuery library added to your page (you may need to modify the path depending on where 'twitter_api_pkg' is installed):

<script src="twitter_api_pkg/javascript/jquery-1.10.2.min.js"></script>

Add this line into the head section if you plan on showing a user timeline on the page:

<?php echo twitter_user_timeline_jquery('envato',0);?>

Change the following variables based on your needs.

envato can be changed to the Twitter screen name that you'd like to show timeline results for.

0 can be changed to the number of seconds that you'd like to auto refresh results in. Note that this field only accepts seconds so if you'd like to enter 2 minutes enter 120 here.

Add this line into the head section if you plan on showing a search results on the page:

<?php echo twitter_search_jquery('traffic',0,'en','recent','40.757332,-73.955556,10mi');?>

traffic change this to your search query and remember that you can use search operators as well. For more info see this section.

en is the language. Leave empty for any language or change en to the language code of your choice. Remember that you can choose from these language codes.

recent is the results type (sort order). You can leave this empty. If left empty, the function will use the value you entered in the twitter_config.php file. If you wish to enter a value here, you may choose between recent, mixed or popular.

40.757332,-73.955556,10mi is the geocode. If left empty, the function will not filter tweets by distance. If a value is entered, the results will be filtered by coordinates. Note that Twitter seems to only return results filtered by distance when the results type "recent" is selected. Remember to enter values in this format for geocode:

"latitude,longitude,radius" radius units must be specified as either "mi" (miles) or "km" (kilometers).

Add the below line of code to the body section of your page (where you'd like to show user timeline results):

<div id="timeline_tweets_jquery"></div>

Add the below line of code to the body section of your page (where you'd like to show search results):

<div id="twitter_search_results_jquery"></div>

twitter_api_pkg/twitter.css

The CSS file can easily be edited to blend with your site's design. The CSS file is in the twitter_api_pkg folder. Below is an explanation of each link of code:

div.tweet {
clear:both;border-top:thin solid #ddd;
}

The lines above changes the style of the rows of Tweets.

The CSS file can easily be edited to blend with your site's design. The CSS file is in the twitter_api_pkg folder. Below is an explanation of each link of code:

.tweet_pic {
float:left;padding:20px;
}

The lines above changes the way the image of Twitter users is displayed.

.tweet_name {
width:60%;float:left;padding:15px;
}

The lines above changes the way the Twitter text (tweets, screen names etc.) is displayed and positioned.

#twitter_search_results{
clear:both;width:100%;margin:10px;color:#333333;
}

The lines above changes the look of the div with contains the search results. Here you can change the width and positioning so that it blends with your site.

#twitter_search_results a {
color:#0385b4;
}

The color of the links in search results.

#timeline_tweets{
clear:both;width:100%;margin:10px;color:#333333;
}

The lines above changes the look of the div with contains the user timeline results. Here you can change the width and positioning so that it blends with your site.

#timeline_tweets a {
color:#0385b4;
}

The color of the links in Twitter user timeline results.

span.highlight
{
font-weight: 700;
}
span.highlight_ul
{
font-weight: 700;
text-decoration:underline;
}

The lines above changes the way keywords on search results pages emphasized.

#location{
margin:10px 0;
padding:10px 0 10px 5px;
background-color:#d0e7ff;
}

The lines above change the box that coordinates fields are in on the search form.

#map_canvas{
width: 683px;
height: 300px;
}

How large do you want the Google map to be?

#map_holder{
padding-top: 25px;
}

Top padding for the Google map.

#panel{
width: 683px;
padding:10px 0;
} #target{
width: 683px;
}

Google search box styling.

#map_help{
text-align:left;
}

Help text that is displayed above the Google search box and map.

#help{
display:none;
color:#333333;
font-size:14px;
margin-top:10px;
}#help td{
padding-right:10px;
}a.help_link{
color:#0385b4;
}

Search operator help link and box styling.

Twitter Search Operators

Twitter Language Codes