Available in Ariadne > 2.7.3

ar\connect\twitter

This module allows you to get tweets from a specific user, current trends, search for tweets, send a tweet for a specific user or let a user login to his or her own twitter account. The entire twitter api is available for use.

Example 1: showing tweets for a specific user

<pinp>
  $twitter = ar('connect/twitter')->client();
  $tweets = $twitter->tweets( 'oreillydotcom' );
  echo '<ul>';
  foreach( $tweets as $tweet ) {
    echo '<li>' . $twitter->friendlyDate( $tweet->created_at )
    . ' : ' . $twitter->parse( $tweet->text ) . '</li>';
  }
  echo '</ul>';
</pinp>

Example 2: sending a tweet for a specific user

<pinp>
  $consumerKey    = 'yourConsumerKey';
  $consumerSecret = 'yourConsumerSecret';
  $twitter = ar('connect/twitter')->client();
  $result = $twitter->login( $consumerKey, $consumerSecret, $thisURL );
  if ($result && !( ar('error')->isError( $result ) ) ) {
    $result = $twitter->tweet( 
      "You've just tweeted through Ariadne." 
    );
  }
</pinp>

 

methods

(object) client Returns a client for the Twitter API.
(string) friendlyDate Parses twitters date format and returns a friendly string like 'yesterday', 'last month', '2 months ago', etc.
(string) parse Parses the text of a tweet and makes all links, users and #references clickable links.

client

(object) ar('connect/twitter')->client( $httpClient = null )

(object) $httpClient Optional http client to use to connect to twitter.com.

Connects to the twitter service and returns an object with the twitter API. You can specify a different http client object to use. This must implement the methods in ar_httpClient, specifically get() and post(). Usually this should not be necessary.

If you want to access features from twitter that require a user to be logged on, the http client must implement the OpenAuth protocol and be logged on. The twitter client has its own login method, which uses OpenAuth, but you can create your own login code and simply pass the logged on http client

friendlyDate

(string) ar('connect/twitter')->friendlyDate( $date, $nls = null, $now = null )

(mixed) $date The date to turn into a friendly date string. Can be a string or a timestamp (integer).
(array) $nls An array with correct language strings for the friendly dates. By default the friendly date is returned in english.
(mixed) $now The date to use to calculate the friendly date with. Default is the current date and time.

This method returns a string like 'yesterday', 'last month' or '2 years ago' for a given date. This date may be a timestamp or any string parseable by strtotime().

If you need non-english friendly dates, you can supply your own translationsin the $nls argument. The english list is:

$nls = array(
  'lastyear'   => 'last year',
  'yearsago'   => '%d years ago',
  'lastmonth'  => 'last month',
  'monthsago'  => '%d months ago',
  'lastweek'   => 'last week',
  'weeksago'   => '%d weeks ago',
  'yesterday'  => 'yesterday',
  'daysago'    => '%d days ago',
  'hourago'    => '1 hour ago',
  'hoursago'   => '%d hours ago',
  'minuteago'  => '1 minute ago',
  'minutesago' => '%d minutes ago',
  'justnow'    => 'just now'
);

The '%d' is parsed with sprintf() so it contains the correct number.

parse

(string) ar('connect/twitter')->parse( $text, $parseLinks = true )

(string) $text The text of the tweet to parse.
(mixed) $parseLinks Whether or not to parse users (@user) and arguments ( #argument ) referenced in the text. You can also specify to parse only one of these and you can specify which link to use.

This method will parse the text of the tweet and automatically change all links in it to clickable hyperlinks. Optionally it will also create clickable links of @user and #argument references. By default it will create links to twitter.com/search.html, but you can change this behaviour.

Setting $parseLinks to false will skip the @user and #argument parsing. Setting it to the value below will only parse arguments and opens these in the same window:

$parseLinks = array(
  'user' => false,
  'argument' => '<a href="http://twitter.com/'
    . 'search?q=%23{argument}">#{argument}</a>'
);

If you specify one of these links as 'true', the default link will be generated.

Twitter client methods

(string) friendlyDate Shortcut to ar_connect_twitter::friendlyDate()
(mixed) login Takes care of logging a user in through OpenAuth.
(mixed) get Does a HTTP GET request on a part of the twitter API.
(string) parse Shortcut to ar_connect_twitter::parse().
(mixed) post Does a HTTP POST request to a part of the twitter API.
(mixed) search Searches for tweets with the given string.
(bool) setAccessToken Sets the OpenAuth access token to access parts of the twitter API for which you need to be logged into an account.
(mixed) trends Returns the current twitter trends.
(mixed) tweet Sends a tweet. You need to be logged in for this.
(mixed) tweets Returns the tweets of a specific user.

login

(mixed) $twitterClient->login( $consumerKey = null, $consumerSecret = null, $callback = null, $redirect = false )

(string) $consumerKey The consumerKey generated by api.twitter.com for your application.
(string) $consumerSecret The consumer secret generated by api.twitter.com for your application.
(string) $callback The name of the callback template or a fully qualified URL. This is where twitter will redirect your user to after logging in.
(bool) $redirect Whether or not login may send a redirect header.

This method implements the OpenAuth authorization scheme for twitter.com. You can build a twitter web application that requires a user to login to their twitter account with this method. You will need to supply the consumer key and secret as well as a callback template or url.

The consumer key and secret can be got from api.twitter.com when you register your application. Registering an application can be done at http://dev.twitter.com/apps. There is a 'register a new app' link to the right. In the details view for your application you can find the Consumer Key and Secret in the OAuth section.

The callback template or URL is something you need to supply yourself. This URL is where twitter.com will return the user after logging in. This callback template or URL should still call login() to work correctly.

Example: simple tweet example 'tweet.html'

<pinp>
  $consumerKey    = 'yourConsumerKey';
  $consumerSecret = 'yourConsumerSecret';
  $twitter = ar('connect/twitter')->client();
  $result = $twitter->login( $consumerKey, $consumerSecret, 'tweet.html' );
  if ($result && !( ar('error')->isError( $result ) ) ) {
    $result = $twitter->tweet( 
      "You've just tweeted through Ariadne." 
    );
  }
</pinp>

In the above example the callback template is the same template again. This means that twitter.com will redirect the user back to the exact same page. The login method will take care of the correct handling. When login() redirects the user to the twitter.com URL to login, it returns false.

If you don't want login() to redirect the user, supply 'false' as the fourth argument. In that case login() will return a url to redirect the user to to login. You can then supply that URL to an iframe or popup window for example.

When login() returns successfully, it returns the twitter.com access_token and secret, including some other information like the users screen_name, as an array. You can store this for later use so you don't need to ask the user to login each time they visit your application. Just remember to store it in a secure way and coupled to this user only.

get

(mixed) $twitterClient->get( $apiPath, $options = array() )

(string) $apiPath The part of api.twitter.com to access.
(array) $options Arguments to pass on to twitter.com.

This method allows you to retrieve any part of the Twitter REST API. E.g. the following URL from api.twitter.com:

http://api.twitter.com/1/statuses/public_timeline.json?trim_user=true

Can be retrieved through the get() method as:

$twitter->get( 
  'statuses/public_timeline', 
  array( 'trim_user' => true ) 
);

Go to dev.twitter.com to read more about the twitter API.

post

(mixed) $twitterClient->post( $apiPath, $options = array() )

(string) $apiPath The part of api.twitter.com to access.
(array) $options Arguments to pass on to twitter.com.

This method sends a HTTP POST request to a part of the Twitter REST API. E.g. the following URL from api.twitter.com:

http://api.twitter.com/1/statuses/update.json

can be posted to like this:

$twitter->post(
  'statuses/update',
  array( 'status' => 'This is a new tweet' )
);

A simpler way to do the above is to use the tweet() method, but the post() and get() method allow access to all parts of the twitter REST API.

search

(mixed) $twitterClient->search( $search )

(mixed) $search Extra arguments to pass on to twitter.com.

Searches through all tweets for tweets matching the search query. The $search argument can be a string, in which case it is passed on as the search query, or it can be an array. In that case the array entries should correspond with the search API's arguments. 

setAccessToken

(bool) $twitterClient->setAccessToken( $accessToken, $accessTokenSecret, $consumerKey = null, $consumerSecret = null )

(string) $accessToken The access token generated by api.twitter.com for your user and application or returned from the login() method.
(string) $accessTokenSecret The access token secret.
(string) $consumerKey The consumer key generated for your application by api.twitter.com.
(string) $consumerSecret The consumer secret for your application.

This method allows you to login to twitter as a specific user. As with the login() method you need to register your application. You can get the access token for your own user simply by browsing to the 'My Access Token' page in the application details view. Or you can store the access_token you got from running the login() method and use that. 

trends

(mixed) $twitterClient->trends( $timeslice, $options = array() )

(string) $timeslice Either 'current', 'daily' or 'weekly'.
(array) $options Extra arguments to pass on to twitter.com.

Returns the current twitter trends. 

Example:

<pinp>
  $results = $twitter->trends();
  echo '<ul>';
  foreach( $results->trends as $date => $trends ) {
    foreach( $trends as $trend ) {
      echo '<li>'.$trend->name.'</li>';
    }
  }
  echo '</ul>';
</pinp>

tweet

(mixed) $twitterClient->tweet( $text, $options = array() )

(string) $text The text to search for.
(array) $options Extra arguments to pass on to twitter.com.

Sends a tweet for the current user. 

tweets

(mixed) $twitterClient->tweets( $user, $options = array() )

(mixed) $user Either the users screen name or user id.
(array) $options Extra arguments to pass on to twitter.com.

Lists the latest tweets for the given user.

Example:

<pinp>
  $tweets = $twitter->tweets( 
    'oreillydotcom', 
    array( 'count' => 10, 'page' => 2 ) 
  );
  echo '<ul>';
  foreach( $tweets as $tweet ) {
    echo '<li>' 
    . $twitter->friendlyDate( $tweet->created_at, $mynls )
    . ' : ' . $twitter->parse( $tweet->text )
    . '</li>';
  }
  echo '</ul>';
</pinp>