{"id":13729470,"url":"https://github.com/felixdorn/twitter-stream-api","last_synced_at":"2025-05-08T01:32:38.311Z","repository":{"id":41184374,"uuid":"365006025","full_name":"felixdorn/twitter-stream-api","owner":"felixdorn","description":"Consume the Twitter Stream API in real-time.","archived":false,"fork":true,"pushed_at":"2023-05-25T08:17:49.000Z","size":378,"stargazers_count":31,"open_issues_count":2,"forks_count":9,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-01T22:14:57.459Z","etag":null,"topics":["package","php","twitter","twitter-api","twitter-api-stream"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"fennb/phirehose","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/felixdorn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-05-06T18:43:17.000Z","updated_at":"2024-10-24T09:34:14.000Z","dependencies_parsed_at":"2023-02-09T02:46:01.577Z","dependency_job_id":null,"html_url":"https://github.com/felixdorn/twitter-stream-api","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felixdorn%2Ftwitter-stream-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felixdorn%2Ftwitter-stream-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felixdorn%2Ftwitter-stream-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felixdorn%2Ftwitter-stream-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/felixdorn","download_url":"https://codeload.github.com/felixdorn/twitter-stream-api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252981687,"owners_count":21835467,"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":["package","php","twitter","twitter-api","twitter-api-stream"],"created_at":"2024-08-03T02:01:00.750Z","updated_at":"2025-05-08T01:32:38.036Z","avatar_url":"https://github.com/felixdorn.png","language":"PHP","funding_links":[],"categories":["Libraries"],"sub_categories":["PHP"],"readme":"# Twitter Stream API (v2)\n\n[![Tests](https://github.com/redwebcreation/twitter-stream-api/actions/workflows/tests.yml/badge.svg?branch=master)](https://github.com/redwebcreation/twitter-stream-api/actions/workflows/tests.yml)\n[![Formats](https://github.com/redwebcreation/twitter-stream-api/actions/workflows/formats.yml/badge.svg?branch=master)](https://github.com/redwebcreation/twitter-stream-api/actions/workflows/formats.yml)\n[![Version](https://poser.pugx.org/redwebcreation/twitter-stream-api/version)](//packagist.org/packages/redwebcreation/twitter-stream-api)\n[![Total Downloads](https://poser.pugx.org/redwebcreation/twitter-stream-api/downloads)](//packagist.org/packages/redwebcreation/twitter-stream-api)\n[![codecov](https://codecov.io/gh/felixdorn/twitter-stream-api/branch/main/graph/badge.svg?token=0bB80l3Hgt)](https://codecov.io/gh/felixdorn/twitter-stream-api)\n\nConsume the Twitter Stream API v2 in real-time.\n\nThis package is the spiritual successor of `fennb/phirehose`. It also uses some of `salsify/jsonstreamingparser` and `maxakawizard/json-collection-parser`.\n\n## Getting started\n\nYou need an approved developer account. If you don't have\none, [apply here](https://developer.twitter.com/en/docs/twitter-api/getting-started/getting-access-to-the-twitter-api).\nOnce you are in, create an \"Application\" in the Developer Portal and generate a new bearer token.\n\n\u003e Requires [PHP 8.1+](https://www.php.net/releases/)\n\n\nYou can install the package via composer:\n\n```bash\ncomposer require redwebcreation/twitter-stream-api\n```\n\nThen, create a connection:\n\n```php\n$connection = new \\Felix\\TwitterStream\\TwitterConnection(\n    bearerToken: '...' # the one you got from the Developer Portal\n);\n```\n\n## Usage\n\n### Streams\n\n* [\\Felix\\TwitterStream\\Streams\\VolumeStream](src/Streams/VolumeStream.php)\n* [\\Felix\\TwitterStream\\Streams\\FilteredStream](src/Streams/FilteredStream.php)\n\n### Creating a stream\n\n```php\n$stream = new \\Felix\\TwitterStream\\Streams\\VolumeStream();\n// or\n$stream = new \\Felix\\TwitterStream\\Streams\\FilteredStream();\n```\n\n### Configuring a stream\n\n* `withTweetLimit(int)` - Limit the number of tweets a connection should process\n    ```php\n    $stream-\u003ewithTweetLimit(100_000);\n    ```\n* `fields(string[])` - See [Fields](#fields)\n* `expansions(...string)` - See [Expansions](#expansions)\n\n#### For advanced use\n\n* `withBufferSize(int = 85)` - How many bytes should the parser store before trying to parse the JSON, on very\n  high-volume streams, using a larger buffer size is recommended (2500, 10000, depending on the volume). Setting to a big\n  value \u003e 2000 on a low-volume stream would result in 0 tweets being processed until there are enough tweets in the buffer.\n\n### Interacting with a stream\n\n* `stopListening()` - Stops listening to the stream.\n* `createdAt(): int` - The UNIX timestamp at which you started listening\n* `timeElapsedInSeconds(): int` - How much time passed since you started listening\n* `tweetsReceived(): int` - How much the stream sent\n\n#### For advanced use\n\n* `response(): Psr\\Http\\Message\\ResponseInterface` - The response sent by Twitter\n\n### Listening to a stream\n\n```php\n$stream-\u003elisten($connection, function (object $tweet) {\n    echo $tweet-\u003edata-\u003etext . PHP_EOL;\n});\n```\n\n## Filtering the stream\n\n**This part only applies if you're interested in the *filtered stream*.**\n\n### Building a rule\n\n\u003e Note, If you change your rules while connected to the stream, Twitter will use the new rules immediately.\n\n#### Save, read and delete rules\n\n\u003e You can not update rules.\n\n```php\nuse Felix\\TwitterStream\\Rule\\RuleManager;\n\n$rule = new RuleManager($connection);\n```\n\nLet's create a rule:\n\n```php\n$rule-\u003esave(\n\t# tweets must contain the word cat and have at least one image\n\t\"cat has:images\",\n\t\"images of cats\"\n);\n```\n\nYou may now retrieve your newly saved rule:\n\n```php\n$rule-\u003eall();\n```\n\nWhich returns an array of `Felix\\TwitterStream\\Rule\\Rule`:\n\n```php\n[\n\t0 =\u003e Felix\\TwitterStream\\Rule\\Rule{\n\t\t+value: \"cat has:images\",\n\t\t+tag: \"images of cats\",\n\t\t+id: \"4567654567654567654\"\n\t}\n]\n```\n\u003e Note, the `Felix\\TwitterStream\\Rule\\Rule` is merely a Data Object, it does not contain any method.\n\nTo delete the rule pass its ID to the `delete` method:\n```php\n$rule-\u003edelete('4567654567654567654');\n```\n\n##### Batch Processing\n\nTo save many rules at once:\n\n```php\nuse Felix\\TwitterStream\\Rule\\Rule;\n\n$rule-\u003esaveMany([  \n   new Rule(\"cats has:images\", \"cat pictures\"),  \n   new Rule(\"dogs has:images\", \"dog pictures\"),  \n   new Rule(\"horses has:images\", \"horse picture\"),  \n]);\n```\n\nTo delete these new rules,\n\n```php\n$rule-\u003edelete([\n\t'[RULE ID]',\n\t'[RULE ID]',\n\t'[RULE ID]',\n]);\n```\n\n#### Validating your rules\n\nYou can either use the `validate()` method:\n\n```php\n# returns a list of errors\n$errors = $rule-\u003evalidate('cats ha:images');\n```\n\n\nOr, the `save` and `saveMany` method both have a dryRun parameter:\n\n```php\n$rule-\u003esave('...', '...', dryRun: true);\n\n$rule-\u003esaveMany([...], dryRun: true);\n```\n\n#### Rule Builder\n\nEvery operator is available, here's an example:\n\n```php\n$rule-\u003enew('listening to music')\n    -\u003eraw('#nowplaying')\n    -\u003eisNotRetweet()\n    -\u003elang('en')\n    -\u003esave();\n```\n\nYou may also use `and[Operator]`, `or[Operator]`, for example `orNotFrom('ID')` or `andBioLocation('location')`.\n\nCompiling this would produce the following:\n```\n#nowplaying -is:retweet lang:en sample:10\n```\n\n##### Tips\n* To directly add a string to the rule, use `raw(string)`\n* You may call `dump()` or `dd()` to quickly debug your rule.\n* `and` is the default operator, you may omit it. For example, `andIsNotRetweet()` is the same as `isNotRetweet()`.\n\n## Fields\n\nFields allow for more customization regarding the payload returned per tweet. Let's see that in an example below:\n\n```php\n$stream\n    -\u003efields([\n        'tweet' =\u003e 'author_id'\n         // or,\n         // 'tweet' =\u003e ['author_id', '...']\n    ])\n    -\u003elisten(...);\n```\n\nWhich could return:\n\n```json\n{\n  \"data\": {\n    \"id\": \"1234321234321234321\",\n    \"text\": \"Hello world!\",\n    \"author_id\": \"5678765678765678765\"\n  }\n}\n```\n\nHere's the list of all the available field types and their respective object model (last updated: Aug. 2022):\n\n* Tweet\n* User\n* Media\n* Poll\n* Place\n\nYou can also check out [Twitter’s documentation](https://developer.twitter.com/en/docs/twitter-api/fields) for more\ndetails.\n\n## Expansions\n\nExpansions let you expand ids to their complete object, for example, if you request an extra author_id field, you may\nexpand it using the author_id expansion:\n\n```php\n$stream\n    -\u003efields(['tweet' =\u003e 'author_id'])\n    -\u003eexpansions('author_id')\n    -\u003elisten(...);\n```\n\nWhich could return:\n\n```json\n{\n  \"data\": {\n    \"id\": \"1234321234321234321\",\n    \"text\": \"Hello world!\",\n    \"author_id\": \"5678765678765678765\"\n  },\n  \"includes\": {\n    \"users\": [\n      {\n        \"id\": \"5678765678765678765\",\n        \"name\": \"John Doe\",\n        \"username\": \"johndoe\"\n      }\n    ]\n  }\n}\n```\n\nThe list of expansions is quite extensive and not all expansions work the same, please check\nout [Twitter's documentation](https://developer.twitter.com/en/docs/twitter-api/expansions). on the subject.\n\n## Testing\n\n```bash\ncomposer test\n```\n\n**Twitter Stream API** was created by [Félix Dorn](https://twitter.com/afelixdorn) under\nthe [MIT License](https://opensource.org/licenses/MIT).\n\n\u003c!-- (179) --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffelixdorn%2Ftwitter-stream-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffelixdorn%2Ftwitter-stream-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffelixdorn%2Ftwitter-stream-api/lists"}