102 lines
4.9 KiB
Markdown
102 lines
4.9 KiB
Markdown
# TweetPHP
|
||
|
||
A PHP class for fetching tweets from a Twitter user's timeline, and rendering them as an HTML list.
|
||
|
||
## Features
|
||
|
||
- Works with Twitter API v1.1
|
||
- Tweets are cached to avoid exceeding Twitter’s API request rate limits
|
||
- A fallback is provided in case the twitter feed fails to load
|
||
- Retweets and @replies can optionally be ignored
|
||
- A configuration parameter allows you to specify how many tweets are displayed
|
||
- Dates can optionally be displayed in “Twitter style”, e.g. “12 minutes ago”
|
||
- You can customize the HTML that wraps your tweets, tweet status and meta information
|
||
|
||
## Usage
|
||
|
||
To interact with Twitter's API you will need an API KEY, which you can create at: https://dev.twitter.com/apps
|
||
|
||
After creating your API Key you will need to take note of following values: "Consumer key", "Consumer secret", "Access token", "Access token secret"
|
||
|
||
Those values can be passed as options to the class constructor, along with the Twitter screen name you wish to query:
|
||
|
||
$TweetPHP = new TweetPHP(array(
|
||
'consumer_key' => 'xxxxxxxxxxxxxxxxxxxxx',
|
||
'consumer_secret' => 'xxxxxxxxxxxxxxxxxxxxx',
|
||
'access_token' => 'xxxxxxxxxxxxxxxxxxxxx',
|
||
'access_token_secret' => 'xxxxxxxxxxxxxxxxxxxxx',
|
||
'twitter_screen_name' => 'yourusername'
|
||
));
|
||
|
||
Then you can display the results like so:
|
||
|
||
echo $TweetPHP->get_tweet_list();
|
||
|
||
You can also retreive the raw data received from Twitter:
|
||
|
||
$tweet_array = $TweetPHP->get_tweet_array();
|
||
|
||
## Options
|
||
|
||
Options can be overridden by passing an array of key/value pairs to the class constructor. At a minimum you must set the `consumer_key`, `consumer_secret`, `access_token`, `access_token_secret` and `twitter_screen_name` options, as shown above.
|
||
|
||
Here is a full list of options, and their default values:
|
||
|
||
'consumer_key' => '',
|
||
'consumer_secret' => '',
|
||
'access_token' => '',
|
||
'access_token_secret' => '',
|
||
'twitter_screen_name' => '',
|
||
'enable_cache' => true,
|
||
'cache_dir' => dirname(__FILE__) . '/cache/', // Where on the server to save cached tweets
|
||
'cachetime' => 60 * 60, // Seconds to cache feed (1 hour).
|
||
'tweets_to_retrieve' => 25, // Specifies the number of tweets to try and fetch, up to a maximum of 200
|
||
'tweets_to_display' => 10, // Number of tweets to display
|
||
'ignore_replies' => true, // Ignore @replies
|
||
'ignore_retweets' => true, // Ignore retweets
|
||
'twitter_style_dates' => false, // Use twitter style dates e.g. 2 hours ago
|
||
'twitter_date_text' => array('seconds', 'minutes', 'about', 'hour', 'ago'),
|
||
'date_format' => '%I:%M %p %b %e%O', // The defult date format e.g. 12:08 PM Jun 12th. See: http://php.net/manual/en/function.strftime.php
|
||
'date_lang' => null, // Language for date e.g. 'fr_FR'. See: http://php.net/manual/en/function.setlocale.php
|
||
'twitter_template' => '<h2>Latest tweets</h2><ul id="twitter">{tweets}</ul>',
|
||
'tweet_template' => '<li><span class="status">{tweet}</span><span class="meta"><a href="{link}">{date}</a></span></li>',
|
||
'error_template' => '<li><span class="status">Our twitter feed is unavailable right now.</span> <span class="meta"><a href="{link}">Follow us on Twitter</a></span></li>',
|
||
'debug' => false
|
||
|
||
## Caching
|
||
|
||
Caching is employed because Twitter rate limits how many times their feeds can be accessed per hour.
|
||
|
||
When the user timeline is first loaded, the resultant HTML list is saved as a text file on your web server. The default location for this file is: `cache/twitter.txt`
|
||
|
||
The raw Twitter response is saved as a serialized array in: `cache/twitter-array.txt`
|
||
|
||
You can change these file paths using the `cache_dir` option. For example, to set a path from your root public directory try:
|
||
|
||
$_SERVER['DOCUMENT_ROOT'] . '/path/to/my/cache/dir/'
|
||
|
||
## Debugging
|
||
|
||
If you are experiencing problems using the script please set the `debug` option to `true`. This will set PHP's error reporting level to `E_ALL`, and will also display a debugging report.
|
||
|
||
You can also fetch the debugging report as an array or HTML list, even when the `debug` option is set to `false`:
|
||
|
||
echo $TweetPHP->get_debug_list();
|
||
$debug_array = $TweetPHP->get_debug_array();
|
||
|
||
## Helper methods
|
||
|
||
### autolink
|
||
|
||
Pass raw tweet text to `autolink()` and it will convert all usernames, hashtags and URLs to HTML links.
|
||
|
||
$autolinked_tweet = $TweetPHP->autolink($tweet);
|
||
|
||
This might be handy if you want to process tweets yourself, using the array returned by `get_tweet_array()`.
|
||
|
||
## Credits
|
||
|
||
- Feed parsing uses Matt Harris' [tmhOAuth](https://github.com/themattharris/tmhOAuth)
|
||
- Hashtag/username parsing uses Mike Cochrane's [twitter-text-php](https://github.com/mikenz/twitter-text-php)
|
||
- Other contributors: [Matt Pugh](https://github.com/mattpugh), [Dario Bauer](https://github.com/dariobauer)
|