Consume the Twitter Stream API v2 in real-time.
This package is a temporary PHP 7.4 compatible version of felixdorn/twitter-stream-api. Most of the documentation below still references the original.
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 7.4+
This is not currently available on Packagist (composer), but you can add it manually see example.
Then, create a connection:
$connection = new \stevecoug\TwitterStream\TwitterConnection(
bearerToken: '...' # the one you got from the Developer Portal
);
$stream = new \stevecoug\TwitterStream\Streams\VolumeStream();
// or
$stream = new \stevecoug\TwitterStream\Streams\FilteredStream();
withTweetLimit(int)
- Limit the number of tweets a connection should process$stream->withTweetLimit(100_000);
fields(string[])
- See Fieldsexpansions(...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 it to a value smaller than 85 is inefficient as the shortest payload returned is at least 85 characters long. Setting to a big value > 2000 on a low-volume stream would result in 0 tweets being processed until there is 2000 bytes in the buffer.
stopListening()
- Stops listening to the stream.createdAt(): int
- The UNIX timestamp at which you started listeningtimeElapsedInSeconds(): int
- How much time passed since you started listeningtweetsReceived(): int
- How much the stream sent
response(): Psr\Http\Message\ResponseInterface
- The response sent by Twitterstream(): Psr\Http\Message\StreamInterface
- The response's body. A reference of this object is passed to the JSON parser.jsonParser(): JsonStreamingParser\Parser
- The JSON parser that parses incoming data from the stream. Holds a reference to the response's body.
$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 stevecoug\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 stevecoug\TwitterStream\Rule\Rule
:
[
0 => stevecoug\TwitterStream\Rule\Rule{
+value: "cat has:images",
+tag: "images of cats",
+id: "4567654567654567654"
}
]
Note, the
stevecoug\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 stevecoug\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->deleteMany([
'[A RULE ID]',
'[A RULE ID]',
'[A RULE ID]',
]);
You can either use the validate()
method:
$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]
.
To add a raw string to the rule, use raw(string)
You may call dump()
or dd()
to quickly debug your rule.
Compiling this would produce the following:
#nowplaying -is:retweet lang:en sample:10
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.