README

实时消费 Twitter Stream API v2。

本包是 fennb/phirehose 的精神继承者。它还使用了一些 salsify/jsonstreamingparser 和 maxakawizard/json-collection-parser 的功能。

入门指南

您需要一个经过批准的开发者账户。如果您还没有，请在此处申请。一旦您进入，在开发者门户中创建一个“应用程序”并生成一个新的bearer token。

需要 PHP 8.1+

您可以通过composer安装此包

composer require redwebcreation/twitter-stream-api

然后，创建一个连接

$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) - 限制连接应处理的推文数量

  $stream->withTweetLimit(100_000);

• fields(string[]) - 查看 字段
• expansions(...string) - 查看 扩展

高级使用

• withBufferSize(int = 85) - 解析器在尝试解析JSON之前应存储多少字节，在非常高的流量流中，建议使用较大的缓冲区大小（2500，10000，取决于流量）。在低流量流中将此值设置为大于2000的大值会导致在没有足够的推文进入缓冲区之前不处理任何推文。

与流交互

• stopListening() - 停止监听流。
• createdAt(): int - 开始监听时的UNIX时间戳
• timeElapsedInSeconds(): int - 自您开始监听以来经过的时间
• tweetsReceived(): int - 流发送的数量

高级使用

• response(): Psr\Http\Message\ResponseInterface - Twitter发送的响应

监听流

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

过滤流

本部分仅适用于您对 过滤流 感兴趣。

构建规则

注意，如果您在连接到流时更改规则，Twitter将立即使用新规则。

保存、读取和删除规则

您不能更新规则。

use Felix\TwitterStream\Rule\RuleManager;

$rule = new RuleManager($connection);

让我们创建一个规则

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

现在您可以检索您新保存的规则

$rule->all();

它返回一个包含 Felix\TwitterStream\Rule\Rule 的数组

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

注意，Felix\TwitterStream\Rule\Rule 只是一个数据对象，它不包含任何方法。

要删除规则，请将其ID传递给 delete 方法

$rule->delete('4567654567654567654');

批量处理

一次保存许多规则

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"),  
]);

要删除这些新规则，

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

验证您的规则

您可以使用 validate() 方法

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

或者，save 和 saveMany 方法都具有 dryRun 参数

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

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

规则构建器

每个操作符都可用，以下是一个示例

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

您还可以使用 and[Operator]，or[Operator]，例如 orNotFrom('ID') 或 andBioLocation('location')。

编译此代码将产生以下结果

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

提示

• 要直接将字符串添加到规则中，请使用 raw(string)
• 您可以调用 dump() 或 dd() 来快速调试您的规则。
• and 是默认操作符，您可以省略它。例如，andIsNotRetweet() 与 isNotRetweet() 相同。

字段

字段允许对每条推文返回的负载进行更多定制。下面通过一个示例来看一下

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

可能会返回

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

以下是所有可用字段类型及其相应的对象模型列表（最后更新：2022年8月）

• 推文
• 用户
• 媒体
• 投票
• 地点

您还可以查看Twitter的文档以获取更多详细信息。

扩展

扩展允许您将ID扩展到其完整对象，例如，如果您请求额外的author_id字段，可以使用author_id扩展将其扩展

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

可能会返回

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

扩展列表相当广泛，并且并非所有扩展都相同，请参阅Twitter的文档。

测试

composer test

Twitter Stream API 由 Félix Dorn 创建，遵循 MIT 许可。