PHPackages                             spatie/twitter-streaming-api - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. spatie/twitter-streaming-api

ActiveLibrary[API Development](/categories/api)

spatie/twitter-streaming-api
============================

Easily work with the Twitter Streaming API

2.0.0(5y ago)17394.2k—8.7%32[1 PRs](https://github.com/spatie/twitter-streaming-api/pulls)5MITPHPPHP ^8.0CI passing

Since Jan 12Pushed 2d ago7 watchersCompare

[ Source](https://github.com/spatie/twitter-streaming-api)[ Packagist](https://packagist.org/packages/spatie/twitter-streaming-api)[ Docs](https://github.com/spatie/twitter-streaming-api)[ RSS](/packages/spatie-twitter-streaming-api/feed)WikiDiscussions master Synced yesterday

READMEChangelog (10)Dependencies (5)Versions (14)Used By (5)

Easily work with the Twitter Streaming API
==========================================

[](#easily-work-with-the-twitter-streaming-api)

[![Latest Version on Packagist](https://camo.githubusercontent.com/958265ddd7a4710596163e3e0e9425d1072f407820691adbf8e1f30683dea28f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7370617469652f747769747465722d73747265616d696e672d6170692e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/spatie/twitter-streaming-api)[![Software License](https://camo.githubusercontent.com/55c0218c8f8009f06ad4ddae837ddd05301481fcf0dff8e0ed9dadda8780713e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](LICENSE.md)[![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)[![Total Downloads](https://camo.githubusercontent.com/afec7e7cbd6a9fddb40bbd0a850660ceedd16513bda323c36f5b312e3b3ac0fa/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7370617469652f747769747465722d73747265616d696e672d6170692e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/spatie/twitter-streaming-api)

Twitter provides a streaming API with which you can do interesting things such as listening for tweets that contain specific strings or actions a user might take (e.g. liking a tweet, following someone,...). This package makes it very easy to work with the API.

Here's a quick example:

```
PublicStream::create(
    $bearerToken,
    $apiKey,
    $apiSecretKey
)->whenHears('@spatie_be', function(array $tweet) {
    echo "We got mentioned by {$tweet['user']['screen_name']} who tweeted {$tweet['text']}";
})->startListening();
```

There's no polling involved. The package will keep an open https connection with Twitter, events will be delivered in real time.

Support us
----------

[](#support-us)

[![](https://camo.githubusercontent.com/235e194be31a6c05e12c89b91e884a6b875d64554eebc3e2d35ef9d1ac6de820/68747470733a2f2f6769746875622d6164732e73332e65752d63656e7472616c2d312e616d617a6f6e6177732e636f6d2f747769747465722d73747265616d696e672d6170692e6a70673f743d31)](https://spatie.be/github-ad-click/twitter-streaming-api)

We 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).

We 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).

Postcardware
------------

[](#postcardware)

You're free to use this package (it's [MIT-licensed](LICENSE.md)), but if it makes it to your production environment we highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using.

Our address is: Spatie, Kruikstraat 22, 2018 Antwerp, Belgium.

The best postcards will get published on the open source page on our website.

Installation
------------

[](#installation)

You can install the package via composer:

```
composer require spatie/twitter-streaming-api
```

Getting credentials
-------------------

[](#getting-credentials)

In order to use this package you'll need to get some credentials from Twitter. Head over to the [Developer Portal on Twitter](https://developer.twitter.com/) to create an application.

Once you've created your application, click on the `Keys and tokens` tab to retrieve your `bearer_token`, `api_key`, `api_secret_key`. [![Keys and tokens tab on Twitter](docs/tokens.png)](docs/tokens.png)

Usage
-----

[](#usage)

Currently, this package works with the public stream and the user stream. Both the `PublicStream` and `UserStream`classes provide a `startListening` function that kicks of the listening process. Unless you cancel it your PHP process will execute that function forever. No code after the function will be run.

### The public stream

[](#the-public-stream)

The public stream can be used to listen for specific words that are being tweeted, receive Tweets that are being sent from specific locations or to follow one or more users tweets.

#### Listen for Tweets containing specific words

[](#listen-for-tweets-containing-specific-words)

The first parameter of `whenHears` must be a string or an array containing the word or words you want to listen for. The second parameter should be a callable that will be executed when one of your words is used on Twitter.

```
PublicStream::create(
    $bearerToken,
    $apiKey,
    $apiSecretKey
)->whenHears('@spatie_be', function(array $tweet) {
    echo "We got mentioned by {$tweet['user']['screen_name']} who tweeted {$tweet['text']}";
})->startListening();
```

#### Listen for Tweets from specific locations

[](#listen-for-tweets-from-specific-locations)

The first parameter of `whenFrom` must be an array containing one or more bounding boxes, each as an array of 4 element lon/lat pairs (looking like `[, , ,  ]`) . The second parameter should be a callable that will be executed when a Tweet from one of your tracked locations is being sent.

**Track all tweets from San Francisco or New York:**

```
PublicStream::create(
    $bearerToken,
    $apiKey,
    $apiSecretKey
)->whenFrom([
    [-122.75, 36.8, -121.75, 37.8], // San Francisco
    [-74, 40, -73, 41],             // New York
], function(array $tweet) {
        echo "{$tweet['user']['screen_name']} just tweeted {$tweet['text']} from SF or NYC";
})->startListening();
```

**Track all tweets with a location (from all over the world):**

```
PublicStream::create(
    $bearerToken,
    $apiKey,
    $apiSecretKey
)->whenFrom([
        [-180, -90, 180, 90] // Whole world
], function(array $tweet) {
    echo "{$tweet['user']['screen_name']} just tweeted {$tweet['text']} with a location attached";
})->startListening();
```

#### Listen for Tweets from specific users

[](#listen-for-tweets-from-specific-users)

The first parameter of `whenTweets` must be a string or an array containing the Twitter user ID or IDs you wish to follow. The second parameter should be a callable that will be executed when one of your followed users tweets. Only public information relating to the Twitter user will be available.

```
PublicStream::create(
    $bearerToken,
    $apiKey,
    $apiSecretKey
)->whenTweets('92947501', function(array $tweet) {
    echo "{$tweet['user']['screen_name']} just tweeted {$tweet['text']}";
})->startListening();
```

### The user stream

[](#the-user-stream)

```
UserStream::create(
    'your_handle',
    $bearerToken,
    $apiKey,
    $apiSecretKey
)->onEvent(function(array $event) {
    if ($event['event'] === 'favorite') {
        echo "Our tweet {$event['target_object']['text']} got favorited by {$event['source']['screen_name']}";
    }
})->startListening();
```

A word to the wise
------------------

[](#a-word-to-the-wise)

These APIs work in realtime, so they could report a lot of activity. If you need to do some heavy work processing that activity, it's best to put that work in a queue to keep your listening process fast.

If you need more advanced functionalities, consider checking out [redwebcreation/twitter-streaming-api](https://github.com/redwebcreation/twitter-streaming-api).

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](https://github.com/spatie/.github/blob/main/CONTRIBUTING.md) for details.

Security
--------

[](#security)

If you've found a bug regarding security please mail  instead of using the issue tracker.

Credits
-------

[](#credits)

- [Freek Van der Herten](https://github.com/freekmurze)
- [All Contributors](../../contributors)

About Spatie
------------

[](#about-spatie)

Spatie is a webdesign agency based in Antwerp, Belgium. You'll find an overview of all our open source projects [on our website](https://spatie.be/opensource).

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

57

—

FairBetter than 98% of packages

Maintenance65

Regular maintenance activity

Popularity47

Moderate usage in the ecosystem

Community30

Small or concentrated contributor base

Maturity75

Established project with proven stability

 Bus Factor1

Top contributor holds 57.9% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~176 days

Recently: every ~310 days

Total

10

Last Release

1873d ago

Major Versions

0.0.2 → 1.0.02017-01-13

1.4.2 → 2.0.02021-05-17

PHP version history (3 changes)0.0.1PHP ^7.0

1.4.2PHP ^8.0|^7.0

2.0.0PHP ^8.0

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/7535935?v=4)[Spatie](/maintainers/spatie)[@spatie](https://github.com/spatie)

---

Top Contributors

[![freekmurze](https://avatars.githubusercontent.com/u/483853?v=4)](https://github.com/freekmurze "freekmurze (55 commits)")[![AdrianMrn](https://avatars.githubusercontent.com/u/12762044?v=4)](https://github.com/AdrianMrn "AdrianMrn (10 commits)")[![felixdorn](https://avatars.githubusercontent.com/u/55788595?v=4)](https://github.com/felixdorn "felixdorn (7 commits)")[![Nielsvanpach](https://avatars.githubusercontent.com/u/10651054?v=4)](https://github.com/Nielsvanpach "Nielsvanpach (5 commits)")[![votintsev](https://avatars.githubusercontent.com/u/3229523?v=4)](https://github.com/votintsev "votintsev (4 commits)")[![ilukecurtis](https://avatars.githubusercontent.com/u/6358950?v=4)](https://github.com/ilukecurtis "ilukecurtis (4 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (3 commits)")[![AlexVanderbist](https://avatars.githubusercontent.com/u/6287961?v=4)](https://github.com/AlexVanderbist "AlexVanderbist (2 commits)")[![JonasDoebertin](https://avatars.githubusercontent.com/u/1367270?v=4)](https://github.com/JonasDoebertin "JonasDoebertin (2 commits)")[![lorenzbausch](https://avatars.githubusercontent.com/u/20989792?v=4)](https://github.com/lorenzbausch "lorenzbausch (1 commits)")[![blueclock](https://avatars.githubusercontent.com/u/586174?v=4)](https://github.com/blueclock "blueclock (1 commits)")[![sebastiandedeyne](https://avatars.githubusercontent.com/u/1561079?v=4)](https://github.com/sebastiandedeyne "sebastiandedeyne (1 commits)")

---

Tags

apiphptwittertwitter-streaming-apispatietwitter-streaming-api

###  Code Quality

TestsPHPUnit

Static AnalysisPsalm

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/spatie-twitter-streaming-api/health.svg)

```
[![Health](https://phpackages.com/badges/spatie-twitter-streaming-api/health.svg)](https://phpackages.com/packages/spatie-twitter-streaming-api)
```

###  Alternatives

[spatie/laravel-query-builder

Easily build Eloquent queries from API requests

4.5k30.7M296](/packages/spatie-laravel-query-builder)[spatie/laravel-fractal

An easy to use Fractal integration for Laravel applications

1.9k16.0M118](/packages/spatie-laravel-fractal)[spatie/fractalistic

A developer friendly wrapper around Fractal

38716.3M8](/packages/spatie-fractalistic)[spatie/laravel-json-api-paginate

A paginator that plays nice with the JSON API spec

6445.1M51](/packages/spatie-laravel-json-api-paginate)[spatie/laravel-route-attributes

Auto register routes using PHP attributes

8941.2M22](/packages/spatie-laravel-route-attributes)[spatie/dropbox-api

A minimal implementation of Dropbox API v2

3126.5M39](/packages/spatie-dropbox-api)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)