{"id":19324960,"url":"https://github.com/spatie/twitter-labs","last_synced_at":"2025-04-22T20:30:54.748Z","repository":{"id":44051156,"uuid":"237067312","full_name":"spatie/twitter-labs","owner":"spatie","description":"PHP client for Twitter Labs","archived":false,"fork":false,"pushed_at":"2022-03-21T14:37:18.000Z","size":106,"stargazers_count":40,"open_issues_count":0,"forks_count":5,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-08-15T18:15:40.394Z","etag":null,"topics":["api","php","realtime","twitter","twitter-labs"],"latest_commit_sha":null,"homepage":"https://spatie.be/open-source","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spatie.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"spatie","patreon":"spatie"}},"created_at":"2020-01-29T19:42:14.000Z","updated_at":"2024-02-04T15:22:47.000Z","dependencies_parsed_at":"2022-09-04T21:01:37.036Z","dependency_job_id":null,"html_url":"https://github.com/spatie/twitter-labs","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Ftwitter-labs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Ftwitter-labs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Ftwitter-labs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Ftwitter-labs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spatie","download_url":"https://codeload.github.com/spatie/twitter-labs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223903484,"owners_count":17222551,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","php","realtime","twitter","twitter-labs"],"created_at":"2024-11-10T02:07:57.201Z","updated_at":"2024-11-10T02:07:57.903Z","avatar_url":"https://github.com/spatie.png","language":"PHP","funding_links":["https://github.com/sponsors/spatie","https://patreon.com/spatie"],"categories":[],"sub_categories":[],"readme":"\n[\u003cimg src=\"https://github-ads.s3.eu-central-1.amazonaws.com/support-ukraine.svg?t=1\" /\u003e](https://supportukrainenow.org)\n\n# PHP client for Twitter Labs endpoints\n\n[![Latest Version on Packagist](https://img.shields.io/packagist/v/spatie/twitter-labs.svg?style=flat-square)](https://packagist.org/packages/spatie/twitter-labs)\n[![GitHub Tests Action Status](https://img.shields.io/github/workflow/status/spatie/twitter-labs/run-tests?label=tests)](https://github.com/spatie/twitter-labs/actions?query=workflow%3Arun-tests+branch%3Amaster)\n[![Total Downloads](https://img.shields.io/packagist/dt/spatie/twitter-labs.svg?style=flat-square)](https://packagist.org/packages/spatie/twitter-labs)\n\nThis package aims to implement some of the realtime endpoints exposed by Twitter's new API, as the old realtime Twitter streams are being deprecated. \n\n\u003eTwitter Developer Labs is where you’ll have early access to new API endpoints, features and versions. We’ll use Labs to test out new ideas and invite our developer community to share their feedback to help shape our roadmap.\n\n_(from the Twitter Developer Labs website)_\n\nUnder the hood this is using [ReactPHP](https://reactphp.org) for everything async. Even though you can use the package with no knowledge of ReactPHP, it is recommended to familiarize yourself with its [event loop](https://reactphp.org/event-loop/) concept.\n\nIf you're currently using our old [twitter-streaming-api package](https://github.com/spatie/twitter-streaming-api), making the switch to this package should be easy.\n\n## Support us\n\n[\u003cimg src=\"https://github-ads.s3.eu-central-1.amazonaws.com/twitter-labs.jpg?t=1\" width=\"419px\" /\u003e](https://spatie.be/github-ad-click/twitter-labs)\n\nWe invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us).\n\nWe highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on [our contact page](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards).\n\n## Installation\n\nYou can install the package via composer:\n\n```bash\ncomposer require spatie/twitter-labs\n```\n\n## Usage\n\nCurrently, only the **filtered stream endpoints** are implemented. We accept PRs for the other features Twitter Labs exposes.\n\n⚠ You'll need a Twitter Developer account with Twitter Dev Labs access enabled and an application that's enrolled in the filtered streams preview. Have a look at https://developer.twitter.com/en/labs.\n\n### Filtered streams overview\n\nYou can find the Twitter Labs filtered stream API docs [here](https://developer.twitter.com/en/docs/labs/filtered-stream/overview). \n\nTwitter's filtered stream consists of one streaming endpoint that returns tweets in realtime and three endpoints to control what tweets are included in the realtime endpoint:\n\n- `GET /labs/1/tweets/stream/filter` (realtime)\n- `POST /labs/1/tweets/stream/filter/rules` (delete)\n- `GET /labs/1/tweets/stream/filter/rules`\n- `POST /labs/1/tweets/stream/filter/rules` (create)\n\nTo use any of these filtered stream endpoints, you'll need a `FilteredStream` instance. Use the `\\Spatie\\TwitterLabs\\FilteredStream\\FilteredStreamFactory` to create this instance for you. The factory's `create` method takes your API credentials and optionally and event loop instance.\n\n### Basic usage: listening for Tweets\n\n``` php\n$filteredStream = \\Spatie\\TwitterLabs\\FilteredStream\\FilteredStreamFactory::create('twitter api token', 'twitter api secret');\n\n$filteredStream-\u003eaddRule(\n    new \\Spatie\\TwitterLabs\\FilteredStream\\Rule('cat has:media', 'cat photos')\n);\n\n$filteredStream\n    -\u003eonTweet(fn (Tweet $tweet) =\u003e print($tweet-\u003etext . PHP_EOL))\n    -\u003estart();\n```\n\nThe event loop will start when calling `start`. All code after this call will not be executed unless something goes wrong and the event loop is stopped.\n\n#### Managing filters/rules\n\nFilters for realtime streams work slightly different in Twitter Labs compared to the old Twitter API. The main difference being that filter rules are actually stored per API key and are always applied when connecting to the stream. When adding or removing rules, these changes are also applied in realtime to the streaming endpoint without having to reconnect.\n\nThe following methods are available to manage filter rules:\n\n```php\npublic function asyncAddRule(\\Spatie\\TwitterLabs\\FilteredStream\\Rule $rule): PromiseInterface;\npublic function asyncAddRules(\\Spatie\\TwitterLabs\\FilteredStream\\Rule ...$rules): PromiseInterface; \npublic function asyncDeleteRules(string ...$ruleIds): PromiseInterface; \npublic function asyncSetRules(\\Spatie\\TwitterLabs\\FilteredStream\\Rule ...$rules): PromiseInterface;\npublic function asyncGetRules(): PromiseInterface;\n\npublic function addRule(\\Spatie\\TwitterLabs\\FilteredStream\\Rule $rule): \\Spatie\\TwitterLabs\\FilteredStream\\Responses\\Rules\\AddRulesResponse;\npublic function addRules(\\Spatie\\TwitterLabs\\FilteredStream\\Rule ...$rules): \\Spatie\\TwitterLabs\\FilteredStream\\Responses\\Rules\\AddRulesResponse;\npublic function deleteRules(string ...$ruleIds): \\Spatie\\TwitterLabs\\FilteredStream\\Responses\\Rules\\DeleteRulesResponse;\npublic function setRules(\\Spatie\\TwitterLabs\\FilteredStream\\Rule ...$rules): \\Spatie\\TwitterLabs\\FilteredStream\\Responses\\Rules\\ListRulesResponse;\npublic function getRules(): \\Spatie\\TwitterLabs\\FilteredStream\\Responses\\Rules\\ListRulesResponse;\n```\n  \nYou can either use `async` endpoints asynchronously (don't forget to run `$filteredStream-\u003erun()` to start the event loop) or use the regular endpoint synchronously.\n\nBasic example that adds a rule:\n\n```php\nuse Spatie\\TwitterLabs\\FilteredStream\\FilteredStreamFactory;\nuse Spatie\\TwitterLabs\\FilteredStream\\Rule;\n\nFilteredStreamFactory::create('token', 'secret')\n    -\u003eaddRule(new Rule('@spatie_be', 'mentioning_spatie'));\n```\n\nBasic example that adds a rule asynchronously (can be combined with other tasks running in the same event loop):\n\n```php\nuse React\\EventLoop\\Factory;\nuse Spatie\\TwitterLabs\\FilteredStream\\FilteredStreamFactory;\nuse Spatie\\TwitterLabs\\FilteredStream\\Rule;\n\n$loop = Factory::create();\n\nFilteredStreamFactory::create('token', 'secret', $loop)\n    -\u003easyncAddRule(new Rule('@spatie_be', 'mentioning_spatie'));\n\n$loop-\u003erun();\n```\n\nExample that syncs rules by getting all existing rules, then deleting them and adding the new rules.\n\n```php\nuse React\\EventLoop\\Factory;\nuse Spatie\\TwitterLabs\\FilteredStream\\FilteredStreamFactory;\nuse Spatie\\TwitterLabs\\FilteredStream\\Rule;\n\n$loop = Factory::create();\n\nFilteredStreamFactory::create('token', 'secret', $loop)\n    -\u003easyncSetRules(new Rule('cat photos')); // or use `setRules()` synchronously\n\n$loop-\u003erun();\n```\n\n#### Listening for tweets\n\nYou can specify a callback to be executed when Twitter hears a tweet that passes your filter rules. The callback will be executed with just one parameter: `\\Spatie\\TwitterLabs\\FilteredStream\\Responses\\Tweet\\Tweet $tweet`. When everything is set-up you can use the `connect()` method to start listening.\n\n```php\nuse React\\EventLoop\\Factory;\nuse Spatie\\TwitterLabs\\FilteredStream\\Responses\\Tweet\\Tweet;\nuse Spatie\\TwitterLabs\\FilteredStream\\FilteredStreamFactory;\n\n$loop = Factory::create();\n\nFilteredStreamFactory::create('token', 'secret', $loop)\n    -\u003eonTweet(fn(Tweet $tweet) =\u003e print($tweet-\u003etext))\n    -\u003econnect();\n\n$loop-\u003erun();\n```\n\nAs a shorthand, `$filteredStream-\u003estart()` is also available. It will connect to the realtime endpoint and start the event loop, even when no event loop was given. This is especially nice when you don't need the event loop anywhere else:\n\n```php\nuse Spatie\\TwitterLabs\\FilteredStream\\Responses\\Tweet\\Tweet;\nuse Spatie\\TwitterLabs\\FilteredStream\\FilteredStreamFactory;\n\nFilteredStreamFactory::create('token', 'secret')\n    -\u003eonTweet(fn(Tweet $tweet) =\u003e print($tweet-\u003etext))\n    -\u003estart();\n```\n\n### Testing\n\n``` bash\ncomposer test\n```\n\n### Changelog\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.\n\n## Contributing\n\nPlease see [CONTRIBUTING](https://github.com/spatie/.github/blob/main/CONTRIBUTING.md) for details.\n\n### Security\n\nIf you've found a bug regarding security please mail [security@spatie.be](mailto:security@spatie.be) instead of using the issue tracker.\n\n## Credits\n\n- [Alex Vanderbist](https://github.com/AlexVanderbist)\n- [All Contributors](../../contributors)\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspatie%2Ftwitter-labs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspatie%2Ftwitter-labs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspatie%2Ftwitter-labs/lists"}