{"id":13608574,"url":"https://github.com/spatie/twitter-streaming-api","last_synced_at":"2025-04-07T14:10:59.828Z","repository":{"id":15737200,"uuid":"78684837","full_name":"spatie/twitter-streaming-api","owner":"spatie","description":"Easily work with the Twitter Streaming API","archived":false,"fork":false,"pushed_at":"2024-09-23T08:31:15.000Z","size":319,"stargazers_count":170,"open_issues_count":1,"forks_count":31,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-31T13:15:26.178Z","etag":null,"topics":["api","php","twitter","twitter-streaming-api"],"latest_commit_sha":null,"homepage":"https://spatie.be/opensource/php","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":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-01-11T22:15:24.000Z","updated_at":"2025-03-20T06:23:05.000Z","dependencies_parsed_at":"2024-11-07T14:34:27.793Z","dependency_job_id":"faabd502-d9fb-4059-9764-ab470f022ffb","html_url":"https://github.com/spatie/twitter-streaming-api","commit_stats":{"total_commits":70,"total_committers":12,"mean_commits":5.833333333333333,"dds":0.4571428571428572,"last_synced_commit":"aeb6cfe7e19ca5ad662d883a31e1771404c75cf8"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Ftwitter-streaming-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Ftwitter-streaming-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Ftwitter-streaming-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Ftwitter-streaming-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spatie","download_url":"https://codeload.github.com/spatie/twitter-streaming-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247666008,"owners_count":20975787,"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","twitter","twitter-streaming-api"],"created_at":"2024-08-01T19:01:28.391Z","updated_at":"2025-04-07T14:10:59.804Z","avatar_url":"https://github.com/spatie.png","language":"PHP","funding_links":[],"categories":["PHP"],"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# Easily work with the Twitter Streaming API\n\n[![Latest Version on Packagist](https://img.shields.io/packagist/v/spatie/twitter-streaming-api.svg?style=flat-square)](https://packagist.org/packages/spatie/twitter-streaming-api)\n[![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE.md)\n[![run-tests](https://github.com/spatie/twitter-streaming-api/actions/workflows/run-tests.yml/badge.svg)](https://github.com/spatie/twitter-streaming-api/actions/workflows/run-tests.yml)\n[![Total Downloads](https://img.shields.io/packagist/dt/spatie/twitter-streaming-api.svg?style=flat-square)](https://packagist.org/packages/spatie/twitter-streaming-api)\n\nTwitter provides a streaming API with which you can do interesting things such as listening for tweets that contain\nspecific strings or actions a user might take (e.g. liking a tweet, following someone,...). This package makes it very\neasy to work with the API.\n\nHere's a quick example:\n\n```php\nPublicStream::create(\n    $bearerToken,\n    $apiKey,\n    $apiSecretKey\n)-\u003ewhenHears('@spatie_be', function(array $tweet) {\n    echo \"We got mentioned by {$tweet['user']['screen_name']} who tweeted {$tweet['text']}\";\n})-\u003estartListening();\n```\n\nThere's no polling involved. The package will keep an open https connection with Twitter, events will be delivered in\nreal time.\n\n## Support us\n\n[\u003cimg src=\"https://github-ads.s3.eu-central-1.amazonaws.com/twitter-streaming-api.jpg?t=1\" width=\"419px\" /\u003e](https://spatie.be/github-ad-click/twitter-streaming-api)\n\nWe invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can\nsupport 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.\nYou'll find our address on [our contact page](https://spatie.be/about-us). We publish all received postcards\non [our virtual postcard wall](https://spatie.be/open-source/postcards).\n\n## Postcardware\n\nYou're free to use this package (it's [MIT-licensed](LICENSE.md)), but if it makes it to your production environment we\nhighly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using.\n\nOur address is: Spatie, Kruikstraat 22, 2018 Antwerp, Belgium.\n\nThe best postcards will get published on the open source page on our website.\n\n## Installation\n\nYou can install the package via composer:\n\n``` bash\ncomposer require spatie/twitter-streaming-api\n```\n\n## Getting credentials\n\nIn order to use this package you'll need to get some credentials from Twitter. Head over to\nthe [Developer Portal on Twitter](https://developer.twitter.com/) to create an application.\n\nOnce you've created your application, click on the `Keys and tokens` tab to retrieve your `bearer_token`\n, `api_key`, `api_secret_key`.\n![Keys and tokens tab on Twitter](docs/tokens.png)\n\n## Usage\n\nCurrently, this package works with the public stream and the user stream. Both the `PublicStream` and `UserStream`\nclasses provide a `startListening` function that kicks of the listening process. Unless you cancel it your PHP process\nwill execute that function forever. No code after the function will be run.\n\n### The public stream\n\nThe public stream can be used to listen for specific words that are being tweeted, receive Tweets that are being sent\nfrom specific locations or to follow one or more users tweets.\n\n#### Listen for Tweets containing specific words\n\nThe first parameter of `whenHears` must be a string or an array containing the word or words you want to listen for. The\nsecond parameter should be a callable that will be executed when one of your words is used on Twitter.\n\n```php\nPublicStream::create(\n    $bearerToken,\n    $apiKey,\n    $apiSecretKey\n)-\u003ewhenHears('@spatie_be', function(array $tweet) {\n    echo \"We got mentioned by {$tweet['user']['screen_name']} who tweeted {$tweet['text']}\";\n})-\u003estartListening();\n```\n\n#### Listen for Tweets from specific locations\n\nThe first parameter of `whenFrom` must be an array containing one or more bounding boxes, each as an array of 4 element\nlon/lat pairs (looking\nlike `[\u003csouth-west point longitude\u003e, \u003csouth-west point latitude\u003e, \u003cnorth-east point longitude\u003e,  \u003cnorth-east point latitude\u003e]`)\n. The second parameter should be a callable that will be executed when a Tweet from one of your tracked locations is\nbeing sent.\n\n**Track all tweets from San Francisco or New York:**\n\n```php\nPublicStream::create(\n    $bearerToken,\n    $apiKey,\n    $apiSecretKey\n)-\u003ewhenFrom([\n    [-122.75, 36.8, -121.75, 37.8], // San Francisco\n    [-74, 40, -73, 41],             // New York\n], function(array $tweet) {\n        echo \"{$tweet['user']['screen_name']} just tweeted {$tweet['text']} from SF or NYC\";\n})-\u003estartListening();\n```\n\n**Track all tweets with a location (from all over the world):**\n\n```php\nPublicStream::create(\n    $bearerToken,\n    $apiKey,\n    $apiSecretKey\n)-\u003ewhenFrom([\n        [-180, -90, 180, 90] // Whole world\n], function(array $tweet) {\n    echo \"{$tweet['user']['screen_name']} just tweeted {$tweet['text']} with a location attached\";\n})-\u003estartListening();\n```\n\n#### Listen for Tweets from specific users\n\nThe first parameter of `whenTweets` must be a string or an array containing the Twitter user ID or IDs you wish to\nfollow. The second parameter should be a callable that will be executed when one of your followed users tweets. Only\npublic information relating to the Twitter user will be available.\n\n```php\nPublicStream::create(\n    $bearerToken,\n    $apiKey,\n    $apiSecretKey\n)-\u003ewhenTweets('92947501', function(array $tweet) {\n    echo \"{$tweet['user']['screen_name']} just tweeted {$tweet['text']}\";\n})-\u003estartListening();\n```\n\n### The user stream\n\n```php\nUserStream::create(\n    'your_handle',\n    $bearerToken,\n    $apiKey,\n    $apiSecretKey\n)-\u003eonEvent(function(array $event) {\n    if ($event['event'] === 'favorite') {\n        echo \"Our tweet {$event['target_object']['text']} got favorited by {$event['source']['screen_name']}\";\n    }\n})-\u003estartListening();\n```\n\n## A word to the wise\n\nThese APIs work in realtime, so they could report a lot of activity. If you need to do some heavy work processing that\nactivity, it's best to put that work in a queue to keep your listening process fast.\n\nIf you need more advanced functionalities, consider checking\nout [redwebcreation/twitter-streaming-api](https://github.com/redwebcreation/twitter-streaming-api).\n\n## Changelog\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information 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- [Freek Van der Herten](https://github.com/freekmurze)\n- [All Contributors](../../contributors)\n\n## About Spatie\n\nSpatie is a webdesign agency based in Antwerp, Belgium. You'll find an overview of all our open source\nprojects [on our website](https://spatie.be/opensource).\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-streaming-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspatie%2Ftwitter-streaming-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspatie%2Ftwitter-streaming-api/lists"}