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);

codezero / twitter

Maintainers

Details