Developer Guide

This guide includes information that is intended for those who would like to modify the Tweetledee files or develop other projects with the data provided by the Tweetledee files. If this is not your goal and you are trying to figure out how to use the files as released in the GitHub repository to generate RSS feed or JSON data, please see the Usage Examples section.

Contents

• Debugging
• Access to Twitter Data from the Command Line
• Piping Twitter Data to Other Applications
• Cross Origin Resource Sharing of your Twitter Data
• Customization of the RSS Feed Format

Debugging Tweetledee

Tweetledee provides a flag in every data file that permits you to turn on PHP debugging for a more verbose report of issues that arise with your use of the files. This debugging feature is off by default. To turn on debugging, switch the $TLD_DEBUGflag to 1.

The default setting is 0

$TLD_DEBUG = 0;

Switch it to:

$TLD_DEBUG = 1;

Save the file and run it again. Please include any error messages in bug reports that you submit as a new issue on the GitHub repository.

Access to Twitter Data from the Command Line

You can access Twitter JSON and RSS feed data with standard command line syntax and display your results in a terminal or pipe the data through the standard out stream to any other application (see below for more information about this). Instead of running the Tweetledee code with a URL, you run the script directly through the PHP interpreter. The Tweetledee files automatically detect whether you are accessing the data by URL or from a terminal window.

All of the mandatory and optional parameter names remain the same with the CLI approach; however, you use standard CLI syntax to define them. For single character options, use a short switch format ( -c). For multiple character options, use a long switch format ( --user).

Here are a few examples. Navigate to the tweetledee directory and then try the following commands:

Command line access to user timeline JSON (your own timeline)

php userjson.php

Command line access to user timeline JSON, different user

php userjson.php --user=csimpkins

Command line access to user timeline JSON, different user + exclude retweets

php userjson.php --user=csimpkins --xrt=1

Command line access to user timeline JSON, different user + exclude retweets + 5 tweets

php userjson.php --user=csimpkins --xrt=1 -c 5

You get the idea. You can use this approach with any of the data files. The complete list of available options are in the Usage Examples section of the documentation.

Piping Twitter Data to Other Applications

When you access the Tweetledee files from the command line, the data are transmitted through the standard out stream. This makes it possible to pipe your results to any application that accepts data through the standard in stream. As a trivial, relatively useless example to demonstrate this, here is how you would perform a word count on your user list (called "coollist") JSON data with the *nix wc application:

Example of Piping Data from Tweetledee to Another Application

php listsjson.php --list=coollist | wc -w

This provides a relatively easy to implement Twitter data source for other applications.

Cross Origin Resource Sharing of your Twitter Data

If you host your Tweetledee files on the domain mydata.com, access to the data from your other domain, myapp.com, where you are running the client-side JS code that needs to process it is prohibited by default. The solution to this problem is for the server to deliver an appropriate response header to the client-side JS that provides "permission" to access the data. This is known as cross origin resource sharing and permissions are modified with the Access-Control-Allow-Origin header.

Tweetledee does not allow cross origin resource sharing by default but provides you with the option to activate this capability if you need it. This is turned on through a flag that is available in all of the standard JSON data files.

The Default Tweetledee Cross Site Access Control Flag

$TLD_JS = 0;

To activate cross site access, change this flag to 1 like this:

$TLD_JS = 1;

Save the file and upload it to your web server. If you check in your browser developer tools, you will notice that this header is set as such:

Access-Control-Allow-Origin: *

This means that you are providing cross site, client side access to your data for ANY DOMAIN. Read that again. You just opened up your Tweetledee data to the JS for any website that would like to use it. That may or may not be a problem for you, but please be aware that this is the default access level that is specified when you activate the flag.

If you would like to restrict the data access to a specific domain, say your myapp.com domain where your application is hosted, then you can modify the header definition in the Tweetledee file like this:

Default Access-Control-Allow-Origin Header Definition

if ($TLD_JS == 1) {
    header('Access-Control-Allow-Origin: *');
}

is changed to:

Your Site Access-Control-Allow-Origin Header Definition

if ($TLD_JS == 1) {
    header('Access-Control-Allow-Origin: http://www.myapp.com');
}

For more information on the CORS W3C spec, follow this link. This is also a great article that goes into a fair bit of detail on client side implementation with vanilla JS and jQuery, as well as browser support, for interested developers.

Custom RSS Formatting

The default RSS feed format displays a tweet with the tweet sender's username in brackets followed by the tweet text like this:

[username] The tweet text

This is coded in the RSS feed files in the following line:

<title>[<?= $tweeter; ?>] <?= $tweetTitle; ?> </title>

$tweeteris a PHP variable that holds the user who posted the tweet and $tweetTitleis a PHP variable that holds the tweet text.

You can modify this line to display a tweet however you would like. I have had a number of users request help with these modifications and will provide examples of a couple of their changes in order to provide a starting point for others who are interested.

Remove the Brackets and Tweet Sender

This is a straightforward modification of the above line. Simply remove [<?= $tweeter; ?>], save the file, and upload it again to your server. The line should now look like this:

<title><?= $tweetTitle; ?></title>

Reformat the Tweet Sender

A user wanted their tweets displayed like this:

username said: The tweet text

To make this adjustment, you need to remove the brackets, keep the $tweeterPHP variable, and modify the XML text so that it looks like this:

<title><?= $tweeter; ?> said: <?= $tweetTitle; ?></title>

The XML readers will respect the spacing that you use in the file so include the appropriate spaces between words in the line.