README

This package hides away the complexity of "talking" to the Twitter API, but instead offers a few simple functions to execute some basic queries.

Features

• All queries require an API key and API secret to generate App Credentials
• Authorization will be triggered automatically behind the scenes
• Fetch a user's tweets with a single method call
• Search Twitter for a hash tag or keyword
• Get the results in standard JSON format, or use our simplified Tweet objects
• Optional Caching (only Laravel implementation included, see codezero-be/courier)
• Optional Laravel ServiceProvider included

Installation

Install this package through Composer:

"require": {
    "codezero/twitter": "1.*"
}

Setup

Laravel Setup

After installing, update your Laravel config/app.php file to include a reference to this package's service provider in the providers array:

'providers' => [
    'CodeZero\Twitter\TwitterServiceProvider'
]

Next, publish the package config file and enter your API credentials.

With Laravel 4.*:

php artisan config:publish codezero/twitter

With Laravel 5.*:

php artisan vendor:publish --provider="CodeZero\Twitter\TwitterServiceProvider"

Manual Setup

Specify the location of your config file. An example configuration file is included in the src/config folder. You can put this anywhere you want.

$config = '/path/to/configFile.php';

Create Twitter instance:

use CodeZero\Twitter\Twitter;
$twitter = new Twitter($config);

Edit Configuration

Your configuration file should look like the following:

<?php
return [
    'base_url' => 'https://api.twitter.com/',
    'api_version' => '1.1',
    'api_key' => '',
    'api_secret' => ''
];

Be sure to enter your API key and API secret. Twitter requires this for all requests. Also, do not include the API version in the base_url as this would break the authorization request.

Usage

Set options

The number of results to return. Each Twitter request has a maximum limit. If you specify a $count greater than this limit, the maximum results will be returned. (Default: 10)

$count = 10;

The number of minutes the results of the query should be cached. Twitter sets a request limit per hour, so caching is a good idea. Setting this to 0 (zero) will disable caching. (Default: 30)

$cacheMinutes = 30;

This package includes a Tweet object which greatly simplifies the returned results. If you want the full JSON response to be returned, set this to false. (Default: true)

$returnEntities = true;

Get tweets

try
{
    $username = 'laravelphp'; //=> Example...
    $tweets = $twitter->getTweetsFromUser($username, $count, $cacheMinutes, $returnEntities);
}
catch (\CodeZero\Twitter\TwitterException $e)
{
    $error = $e->getMessage(); //=> user not found etc.
}

Response formats

JSON

If you $returnEntities is false, you get a CodeZero\Courier\Response object, which contains the actual JSON response.

$tweets = $twitter->getTweetsFromUser($username);

echo $tweets; //=> Print the JSON
$json = $tweets->getBody(); //=> Returns the JSON
$array = $tweets->toArray(); //=> Convert JSON to an array

For more information on this Response object, refer to codezero-be/courier.

Tweets

If you $returnEntities is true, you get an array of CodeZero\Twitter\Entities\Tweet objects. This is a very simplified Tweet object, which only contains the most useful info about the tweet and its user.

$tweets = $twitter->getTweetsFromUser($username);

foreach ($tweets as $tweet)
{
    $user = $tweet->user();
    $tweetOwner = $user->getName();
    $tweetUsername = $user->getUsername();
    $tweetText = $tweet->getText();
    $tweetDate = $tweet->getCreatedAt();
}

For an overview of all available Tweet and User information, take a look at the source.

Available Requests

Get tweets from a user

$username = 'laravelphp';
$tweets = $twitter->getTweetsFromUser($username, $count, $cacheMinutes, $returnEntities);

Search for tweets with a hash tag or keyword

$query = '#laravel';
$tweets = $twitter->searchTweets($query, $count, $cacheMinutes, $returnEntities);

That's all for now...