Consume the Twitter Stream API v2 in real-time.

This package is the spiritual successor of fennb/phirehose. It also uses some of salsify/jsonstreamingparser and maxakawizard/json-collection-parser.

You need an approved developer account. If you don't have one, apply here. Once you are in, create an "Application" in the Developer Portal and generate a new bearer token.

Requires PHP 8.1+

You can install the package via composer:

composer require redwebcreation/twitter-stream-api

Then, create a connection:

$connection = new \Felix\TwitterStream\TwitterConnection(
    bearerToken: '...' # the one you got from the Developer Portal
);

• \Felix\TwitterStream\Streams\VolumeStream
• \Felix\TwitterStream\Streams\FilteredStream

$stream = new \Felix\TwitterStream\Streams\VolumeStream();
// or
$stream = new \Felix\TwitterStream\Streams\FilteredStream();

• withTweetLimit(int) - Limit the number of tweets a connection should process

  $stream->withTweetLimit(100_000);

• fields(string[]) - See Fields
• expansions(...string) - See Expansions

• withBufferSize(int = 85) - How many bytes should the parser store before trying to parse the JSON, on very high-volume streams, using a larger buffer size is recommended (2500, 10000, depending on the volume). Setting to a big value > 2000 on a low-volume stream would result in 0 tweets being processed until there are enough tweets in the buffer.

• stopListening() - Stops listening to the stream.
• createdAt(): int - The UNIX timestamp at which you started listening
• timeElapsedInSeconds(): int - How much time passed since you started listening
• tweetsReceived(): int - How much the stream sent

• response(): Psr\Http\Message\ResponseInterface - The response sent by Twitter

$stream->listen($connection, function (object $tweet) {
    echo $tweet->data->text . PHP_EOL;
});

This part only applies if you're interested in the filtered stream.

Note, If you change your rules while connected to the stream, Twitter will use the new rules immediately.

You can not update rules.

use Felix\TwitterStream\Rule\RuleManager;

$rule = new RuleManager($connection);

Let's create a rule:

$rule->save(
	# tweets must contain the word cat and have at least one image
	"cat has:images",
	"images of cats"
);

You may now retrieve your newly saved rule:

$rule->all();

Which returns an array of Felix\TwitterStream\Rule\Rule:

[
	0 => Felix\TwitterStream\Rule\Rule{
		+value: "cat has:images",
		+tag: "images of cats",
		+id: "4567654567654567654"
	}
]

Note, the Felix\TwitterStream\Rule\Rule is merely a Data Object, it does not contain any method.

To delete the rule pass its ID to the delete method:

$rule->delete('4567654567654567654');

To save many rules at once:

use Felix\TwitterStream\Rule\Rule;

$rule->saveMany([  
   new Rule("cats has:images", "cat pictures"),  
   new Rule("dogs has:images", "dog pictures"),  
   new Rule("horses has:images", "horse picture"),  
]);

To delete these new rules,

$rule->delete([
	'[RULE ID]',
	'[RULE ID]',
	'[RULE ID]',
]);

You can either use the validate() method:

# returns a list of errors
$errors = $rule->validate('cats ha:images');

Or, the save and saveMany method both have a dryRun parameter:

$rule->save('...', '...', dryRun: true);

$rule->saveMany([...], dryRun: true);

Every operator is available, here's an example:

$rule->new('listening to music')
    ->raw('#nowplaying')
    ->isNotRetweet()
    ->lang('en')
    ->save();

You may also use and[Operator], or[Operator], for example orNotFrom('ID') or andBioLocation('location').

Compiling this would produce the following:

#nowplaying -is:retweet lang:en sample:10

• To directly add a string to the rule, use raw(string)
• You may call dump() or dd() to quickly debug your rule.
• and is the default operator, you may omit it. For example, andIsNotRetweet() is the same as isNotRetweet().

Fields allow for more customization regarding the payload returned per tweet. Let's see that in an example below:

$stream
    ->fields([
        'tweet' => 'author_id'
         // or,
         // 'tweet' => ['author_id', '...']
    ])
    ->listen(...);

Which could return:

{
  "data": {
    "id": "1234321234321234321",
    "text": "Hello world!",
    "author_id": "5678765678765678765"
  }
}

Here's the list of all the available field types and their respective object model (last updated: Aug. 2022):

• Tweet
• User
• Media
• Poll
• Place

You can also check out Twitter’s documentation for more details.

Expansions let you expand ids to their complete object, for example, if you request an extra author_id field, you may expand it using the author_id expansion:

$stream
    ->fields(['tweet' => 'author_id'])
    ->expansions('author_id')
    ->listen(...);

Which could return:

{
  "data": {
    "id": "1234321234321234321",
    "text": "Hello world!",
    "author_id": "5678765678765678765"
  },
  "includes": {
    "users": [
      {
        "id": "5678765678765678765",
        "name": "John Doe",
        "username": "johndoe"
      }
    ]
  }
}

The list of expansions is quite extensive and not all expansions work the same, please check out Twitter's documentation. on the subject.

composer test

Twitter Stream API was created by Félix Dorn under the MIT License.