PHPackages automattic/stream-builder - 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. [Utility & Helpers](/categories/utility) 4. / 5. automattic/stream-builder ActiveLibrary[Utility & Helpers](/categories/utility) automattic/stream-builder ========================= A library for generating a stream of content from a variety of sources. 1.0.0(6mo ago)142328[3 PRs](https://github.com/Automattic/stream-builder/pulls)GPL-2.0-or-laterPHPPHP >=7.4CI passing Since Jul 3Pushed 1mo ago14 watchersCompare [ Source](https://github.com/Automattic/stream-builder)[ Packagist](https://packagist.org/packages/automattic/stream-builder)[ RSS](/packages/automattic-stream-builder/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (10)Dependencies (12)Versions (19)Used By (0) [![Coverage Status](https://camo.githubusercontent.com/6ffbad05613203c9f58d8c777bfbb0d9fb7a3969678caaf954ff39f87974f71f/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f4175746f6d61747469632f73747265616d2d6275696c6465722f62616467652e737667)](https://coveralls.io/github/Automattic/stream-builder) StreamBuilder ============= [](#streambuilder) StreamBuilder is Tumblr's custom framework we use to power the dashboard and most of the feeds on the platform. The primary architecture centers around “streams” of content. In our implementation, those streams can be posts from a blog, a list of blogs you’re following, posts using a specific tag, or posts relating to a search. These are separate kinds of streams, which can be mixed together, filtered based on certain criteria, ranked for relevancy or engagement likelihood, and more. On the Tumblr dashboard today you can see how there are posts from blogs you follow, mixed with posts from tags you follow, mixed with blog recommendations. Each of those is a separate stream, with its own logic, but sharing this same framework. We inject those recommendations at certain intervals, filter posts based on who you’re blocking, and rank the posts for relevancy if you have the “Best stuff first” setting enabled. Those are all examples of the functionality StreamBuilder affords for us. What's included in this repo: - The full framework library of code that we use today, on Tumblr, to power almost every feed of content you see on the platform. - A YAML syntax for composing streams of content, and how to filter, inject, and rank them. - Abstractions for programmatically composing, filtering, ranking, injecting, and debugging streams. - Abstractions for composing streams together—such as with carousels, for streams-within-streams. - An abstraction for cursor-based pagination for complex stream templates. - Unit tests covering the public interface for the library and most of the underlying code. We're still working to add more documentation and examples. Check out [the announcement post on the Tumblr Engineering blog](https://engineering.tumblr.com/post/722102563011493888/streambuilder-our-open-source-framework-for) for more info. Get started by reading the [StreamBuilder Beginner's Guide](docs/StreamBuilder-Beginners-Guide.md). We also have an example app in the `example/` folder to try! Installation ------------ [](#installation) StreamBuilder expects PHP 7.4+. Install StreamBuilder by using [Composer](https://getcomposer.org/) and running `composer require automattic/stream-builder` in your project. To access the examples and unit tests, please use `composer require --prefer-source automattic/stream-builder` to make a local git clone. Contributing ------------ [](#contributing) If you want to change the StreamBuilder code, please: 1. Create an issue and describe your idea or desired change for discussion. Please mention `Automattic/stream-builders` for visibility and feedback. Please do this before proceeding! 2. Create a PR and add `Automattic/stream-builders` to the reviewers. Please write unit tests or update unit tests for your change. 3. Make sure unit tests and PHPCS are returning green (use `make test` to run the unit test suite and `make cs` to fix code style issues). 4. Add a description of your changes and testing instructions. 5. If you are making a breaking change, make it really clear! Changing a namespace from an existing class? That's a breaking change. Changing the way a cursor works? That's a breaking change. If you are making a major refactor, changing interfaces, or any other breaking changes, we may not approve your PR. Tumblr relies on StreamBuilder for all our feeds, and we wouldn't want to change a lot of code unless there is a very good reason to do so. Once approved, we will merge your PR and publish a new version. You can then update the version number in your `composer.json` file and deploy your changes. All breaking changes will be published as a major version. If you are using a major version, you will need to update your code to use the new interfaces. We don't expect that to occur often. Creating a new release ---------------------- [](#creating-a-new-release) **Only applies to Automatticians with repository write permissions** 1. Merge your change via a PR in this repository; see the Contributing section. 2. Head over to and click "Draft a new release". 3. Select "Choose a tag" and create a new version if you haven't already. Not a breaking change? Increment the minor version by 0.0.1. Breaking change? Increment the major version by 0.1.0. 4. Make sure you are targeting the `main` branch. 5. Click "generate release notes". This will generate a list of all the PRs merged since the last release. 6. Hit the green "Publish release" button. Are you a Tumblr employee? You can now update the version number in any internal `composer.json` files and deploy your changes. Release often! We want to make sure we are shipping new features and bug fixes as often as possible. We don't want to get into a situation where we are shipping a lot of changes at once. ### Health Score 46 — FairBetter than 93% of packages Maintenance81 Actively maintained with recent releases Popularity23 Limited adoption so far Community23 Small or concentrated contributor base Maturity52 Maturing project, gaining track record Bus Factor2 2 contributors hold 50%+ of commits 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 ~56 days Recently: every ~157 days Total 16 Last Release 202d ago Major Versions 0.12.1 → 1.0.02025-10-27 ### Community Maintainers ![](https://www.gravatar.com/avatar/7c5869ecbb8e0eac7e8b8e0f3cf7bdd8d5fcdc4abc10a72281872c53f8639d44?d=identicon)[automattic](/maintainers/automattic) --- Top Contributors [![lucila](https://avatars.githubusercontent.com/u/3482310?v=4)](https://github.com/lucila "lucila (10 commits)")[![markbiek](https://avatars.githubusercontent.com/u/917632?v=4)](https://github.com/markbiek "markbiek (9 commits)")[![sanmai](https://avatars.githubusercontent.com/u/139488?v=4)](https://github.com/sanmai "sanmai (8 commits)")[![kchro3](https://avatars.githubusercontent.com/u/62481661?v=4)](https://github.com/kchro3 "kchro3 (2 commits)")[![bnu0](https://avatars.githubusercontent.com/u/5695343?v=4)](https://github.com/bnu0 "bnu0 (1 commits)")[![marco-altran](https://avatars.githubusercontent.com/u/69607277?v=4)](https://github.com/marco-altran "marco-altran (1 commits)")[![nicola-barbieri](https://avatars.githubusercontent.com/u/84461105?v=4)](https://github.com/nicola-barbieri "nicola-barbieri (1 commits)")[![leoasis](https://avatars.githubusercontent.com/u/328001?v=4)](https://github.com/leoasis "leoasis (1 commits)")[![cyle](https://avatars.githubusercontent.com/u/770158?v=4)](https://github.com/cyle "cyle (1 commits)")[![eltongo](https://avatars.githubusercontent.com/u/13062352?v=4)](https://github.com/eltongo "eltongo (1 commits)")[![lengare](https://avatars.githubusercontent.com/u/25574979?v=4)](https://github.com/lengare "lengare (1 commits)") ### Code Quality TestsPHPUnit Static AnalysisPHPStan, Psalm Code StylePHP CS Fixer Type Coverage Yes ### Embed Badge ![Health badge](/badges/automattic-stream-builder/health.svg) ``` [![Health](https://phpackages.com/badges/automattic-stream-builder/health.svg)](https://phpackages.com/packages/automattic-stream-builder) ``` ### Alternatives [orchestra/canvas Code Generators for Laravel Applications and Packages 21017.2M158](/packages/orchestra-canvas)[lullabot/drainpipe An automated build tool to allow projects to have a set standardized operations scripts. 41716.4k2](/packages/lullabot-drainpipe)[netgen/content-browser Netgen Content Browser is a Symfony bundle that provides an interface which selects items from any kind of backend and returns the IDs of selected items back to the calling code. 14112.1k8](/packages/netgen-content-browser) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)