hashandsalt / kirby3-twitter
Kirby Twitter Plugin
Installs: 53
Dependents: 0
Suggesters: 0
Security: 0
Stars: 8
Watchers: 2
Forks: 4
Open Issues: 1
Type:kirby-plugin
Requires
- abraham/twitteroauth: ^3.0
- getkirby/composer-installer: ^1.1
README
A small plugin that is a wrapper around twitteroauth. Allows you to display tweets on your website without having use Twitters embedded timelines. The plugin supports both V1.1 and V2 of the API. Plugin was tested on PHP 8 using Kirby 3.6+
Features:
- Display tweets on your site using your own markup.
- Caches results from API, in a unique file per set
- Automagically turns all links, hashtags and @ mentions into clickable links.
Commerical Usage
This plugin is free but if you use it in a commercial project please consider to
How to use Kirby Twitter
First you need access to the Twitter API, and for that you need an account. Register your website as an application here.
Installation
Download
Download and copy this repository to /site/plugins/kirby3-twitter
.
Composer
composer require hashandsalt/kirby3-twitter
Setup
You wont get far without authenticating. Set the following in your config to gain access to your feed:
'cache.hashandsalt.kirby-twitter.tweets' => true,
'twit.bearer' => 'XXX',
'twit.consumerkey' => 'XXX',
'twit.consumersecret' => 'XXX',
'twit.accesstoken' => 'XXX',
'twit.accesstokensecret' => 'XXX',
'twit.apiVersion' => '1.1',
'twit.cachelife' => 30,
Usage
To switch between APIs set the config option accordingly. 'twit.apiVersion' => '1.1'
Assuming the below details to work with:
$tweetid = 1469448484185067523;
$myid = 815859093273509888;
$screenName = 'getkirby';
Snippets
There are two helpful snippets to get you started.
API V1.1
Single Tweet
<?= snippet('twitter/tweet', ['cachename' => 'yourcachename', 'media' => true, 'params' => ['id' => $tweetid, 'tweet_mode' => 'extended']])?>
Users Timeline
<?= snippet('twitter/tweets', ['cachename' => 'yourcachename', 'media' => true, 'params' => ['screen_name' => $screenName, 'tweet_mode' => 'extended', 'count' => 20, 'exclude_replies' => true]])?>
API V2
Single Tweet
<?= snippet('twitter/tweet', ['cachename' => 'yourcachename', 'media' => true, 'params' => ['ids' => $tweetid]])?>
Users Timeline
<?= snippet('twitter/tweets', ['cachename' => 'yourcachename', 'screenname' => $screenName, 'media' => true, 'params' => ['max_results' => 20]])?>
Usage
The Plugin makes three page methods available.
For getting single tweets or timelines
$page->tweets(...);
For getting user info
$page->twitterUserName($myid);
$page->twitterUserId($screenName);
API V1.1
Single Tweet
To get a sungle tweet, set the name of the cache data file as the first param, second param is the API path, followed by optional API parameters.
$result = $page->tweets('mysingletweet', 'statuses/show', ['id' => $tweetid, 'tweet_mode' => 'extended']);
Username From ID
Returns a users name from an ID number
$result2 = $page->twitterUserName($myid);
ID From Username
Returns a users ID from an username
$result3 = $page->twitterUserId($screenName);
Own Time line
Returns a your own timeline given an ID. Set the name of the cache data file as the first param, second param is the API path, followed by optional API parameters.
$result4 = $page->tweets('mytweets', 'statuses/home_timeline', ['count' => 20, 'exclude_replies' => true, 'tweet_mode' => 'extended']);
Other users Time line
Returns a users timeline given an ID. Set the name of the cache data file as the first param, second param is the API path, followed by optional API parameters.
$result5 = $page->tweets('someUser', 'statuses/user_timeline', ['screen_name' => $screenName, 'count' => 20, 'exclude_replies' => true, 'tweet_mode' => 'extended']);
API V2
Single Tweet
To get a sungle tweet, set the name of the cache data file as the first param, second param is the API path, followed by optional API parameters.
$result = $page->tweets('mysingletweet', 'tweets', ['ids' => $tweetid]);
Username From ID
Returns a users name from an ID number
$result2 = $page->twitterUserName($myid);
ID From Username
Returns a users ID from an username
$result3 = $page->twitterUserId($screenName);
Get a users Timeline
Returns a users timeline given an ID. Set the name of the cache data file as the first param, second param is the API path, followed by optional API parameters.
$result4 = $page->tweets($result3, 'users/'.$result3.'/tweets', [
'max_results' => 20
]);
Known Issues
The Twitter API is a bit dumb. It counts retweets as a tweet. If you ask for 6 tweets and only got 4 back, 2 of them were probably retweeted. Not much to be done about that, other then asking for more then you need and only looping out the first 6, but you could still run into the problem again.
License
MIT