README

TwitterStreaming is a new PHP client that you can use to connect to the Twitter Streaming API and retrieve data in real-time. Throughout this document we'll see that its usage is simple, which can facilitate their integration with multiples systems/workflows.

Installation
Features
More examples
Contributing

Installation

TwitterStreaming PHP is a Composer package. It will install the package and its dependencies. The main dependency is Guzzle which is a PHP HTTP Client.

To install via composer, run the following command.

composer require rbadillap/twitterstreaming

You will need to create a Twitter Application. Follow its indications to get the keys.

TwitterStreaming PHP suggests to use PHP DotEnv by Vance Lucas to store you Twitter Application credentials, and keep separately from the code. If you wanna use it, you can include it in your package.json typing:

composer require vlucas/phpdotenv

Then create an .env file in the root of your project and put the values that you will see in: https://apps.twitter.com/app/[YOUR_APP_ID]/keys.

TWITTERSTREAMING_CONSUMER_KEY=[Consumer Key (API Key)]
TWITTERSTREAMING_CONSUMER_SECRET=[Consumer Secret (API Secret)]
TWITTERSTREAMING_TOKEN=[Access Token]
TWITTERSTREAMING_TOKEN_SECRET=[Access Token Secret]

Elsewhere if you won't use this library, you should provide those credentials in the code at the moment you instance the Tracker class (take a look the file: WithoutDotEnv.php located in the examples folder). Also, if you wanna provide the credentials despite that you are already using the DotEnv library, you just need to provide those credentials through the instance creation and TwitterStreaming PHP will prioritize that.

TwitterStreaming PHP will throw an error if were unable to find the .env file or the Twitter credentials are invalid.

Features

Following PSR-2 Coding Style Guide
Following PSR-4 Autoloader standard
Extendible (you can create your own extensions if you want/need).
Following the best practices to connect to Twitter API (one single connection of course).
Following the Twitter API documentation to parse the data and responses.
... and so on

How it works

After give the composer the authority to download the package and generate the autoloader, you will be able to use the namespaces of TwitterStreaming.

Something like this.

require_once 'vendor/autoload.php'; // The autoload from composer

use TwitterStreaming\Tracker;

(new Tracker);

Obviously, we would like to add more configurations. So you need to work close with the official documentation of Twitter Streaming API: https://dev.twitter.com/streaming/overview to understand how this app works.

Endpoints

First of all, something very important to understand, is that Twitter gives to you 3 official endpoints.

In TwitterStreaming PHP you can set an endpoint using the method endpoint on this way:

require_once 'vendor/autoload.php'; // The autoload from composer

use TwitterStreaming\Tracker;

(new Tracker)
	->endpoint('__endpoint__', '__type__');

Note:

If you see in the official documentation, there is another API to interact deeper with Twitter, to make searches, read user profile information or post tweets for example, called REST API, which doesn't belong to this package due there is a lot of good clients already written.

In some cases the second argument type won't be necessary.

How to define an endpoint

Depending of the endpoint that you're going to work, you may define the type as well. For example, the Public Endpoint.

See: https://dev.twitter.com/streaming/public

As you can see, this endpoint, provides 3 types: filter, sample and firehose. At this moment, the only functional types are filter and sample. The type firehose requires special permission from Twitter.

To define this endpoint you can do something like this;

require_once 'vendor/autoload.php'; // The autoload from composer

use TwitterStreaming\Tracker;

(new Tracker)
	->endpoint('public', 'filter');

Also you can add the class directly if you want.

require_once 'vendor/autoload.php'; // The autoload from composer

use TwitterStreaming\Tracker;
use TwitterStreaming\Endpoints; // add this line

(new Tracker)
	->endpoint(Endpoints\PublicEndpoint::class, 'filter');

Or the User Endpoint, that doesn't need an specific type.

require_once 'vendor/autoload.php'; // The autoload from composer

use TwitterStreaming\Tracker;
use TwitterStreaming\Endpoints;

(new Tracker)
	->endpoint(Endpoints\UserEndpoint::class);

If you notice, we don't need to specify any URL or any other feature to run an specific endpoint. We have covered all in our library :)

Parameters

After defining the endpoint, you can continue with the parameters that you'd like to send to Twitter.

An important point to understand is that you can set the parameters based on what Twitter allows to you to use.

For example, if you wants filter tweets using the Public Endpoint and the Filter type, you can see a list of available parameters here: https://dev.twitter.com/streaming/reference/post/statuses/filter you can add all of those parameters in TwitterStreaming PHP. How?

require_once 'vendor/autoload.php'; // The autoload from composer

use TwitterStreaming\Tracker;
use TwitterStreaming\Endpoints;

(new Tracker)
	->endpoint(Endpoints\PublicEndpoint::class, 'filter')
	->parameters([
		'track' => '#twitter',
		'location' => '-122.75,36.8,-121.75,37.8'
	]);

You can filter by two or more hashtags as well, for example.

require_once 'vendor/autoload.php'; // The autoload from composer

use TwitterStreaming\Tracker;
use TwitterStreaming\Endpoints;

(new Tracker)
	->endpoint(Endpoints\PublicEndpoint::class, 'filter')
	->parameters([
		'track' => [
			'#twitter', '#facebook', '#instagram'
		],
		'location' => '-122.75,36.8,-121.75,37.8'
	]);

This will convert the track to something like: #twitter OR #facebook OR #instagram

If you wanna filter tweets with all those hashtags (instead of OR use AND) just put the words in a same line.

require_once 'vendor/autoload.php'; // The autoload from composer

use TwitterStreaming\Tracker;
use TwitterStreaming\Endpoints;

(new Tracker)
	->endpoint(Endpoints\PublicEndpoint::class, 'filter')
	->parameters([
		'track' => '#twitter #facebook #instagram',
		'location' => '-122.75,36.8,-121.75,37.8'
	]);

See: https://dev.twitter.com/streaming/overview/request-parameters

Track

After define the endpoint and parameters, you will be able to track the tweets. TwitterStreaming PHP will throw to you every single tweet, and you can manipulate them as your convenience.

Just use the method track.

// track.php
require_once 'vendor/autoload.php'; // The autoload from composer

use TwitterStreaming\Tracker;
use TwitterStreaming\Endpoints;

(new Tracker)
	->endpoint(Endpoints\PublicEndpoint::class, 'filter')
	->parameters([
		'track' => '#twitter #facebook #instagram',
		'location' => '-122.75,36.8,-121.75,37.8'
	])
	->track(function($tweet) {
		// Do a print_r($tweet) if you wanna see more
		// details of the tweet.
		print "Tweet details:" . PHP_EOL;
		print "User: @" . $tweet->user->screen_name . PHP_EOL;
		print "Content: " . $tweet->text . PHP_EOL;
	});

Disconnect

In some cases you may need to disconnect from the stream after meeting some criteria. In this case you can use the disconnect() method from inside the track() closure method. To do so you can pass a second optional $request argument to the closure. Here is the same example from above with a disconnect() implemented.

// track.php
require_once 'vendor/autoload.php'; // The autoload from composer

use TwitterStreaming\Tracker;
use TwitterStreaming\Endpoints;

(new Tracker)
	->endpoint(Endpoints\PublicEndpoint::class, 'filter')
	->parameters([
		'track' => '#twitter #facebook #instagram',
		'location' => '-122.75,36.8,-121.75,37.8'
	])
	->track(function($tweet,$request) {
		// Do a print_r($tweet) if you wanna see more
		// details of the tweet.
		print "Tweet details:" . PHP_EOL;
		print "User: @" . $tweet->user->screen_name . PHP_EOL;
		print "Content: " . $tweet->text . PHP_EOL;

		//disconnect from stream after reaching tweet limit
		if($this-tweetCount >= $this->tweetLimit) {
			$request->disconnect();
		}

	});

More examples

We have attached a folder called examples with samples about how TwitterStreaming PHP works in different scenarios.

Contributing

Use the same workflow as many of the packages that we have here in Github.

Fork the project.
Create your feature branch with a related-issue name.
Try to be clear with the code committed and follow the PSR-2 Coding Style Guide.
Run the tests (and create your new ones if necessary).
Commit and push the branch.
Create the Pull Request.

rbadillap / twitterstreaming

Maintainers

Details