PHPackages thiagomarini/binocular - 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. thiagomarini/binocular ActiveLibrary[Utility & Helpers](/categories/utility) thiagomarini/binocular ====================== Doing Event Sourcing without building a spaceship 1.0.1(6y ago)373.0k1MITPHPPHP >=7.1.0 Since Jul 1Pushed 6y ago2 watchersCompare [ Source](https://github.com/thiagomarini/binocular)[ Packagist](https://packagist.org/packages/thiagomarini/binocular)[ Docs](https://github.com/thiagomarini/binocular)[ RSS](/packages/thiagomarini-binocular/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (2)Dependencies (1)Versions (3)Used By (0) Binocular ========= [](#binocular) [![CircleCI](https://camo.githubusercontent.com/c8d19567e09d970a758509f096a2675f05d82b7a998410632d2d52ecff8e314e/68747470733a2f2f636972636c6563692e636f6d2f67682f74686961676f6d6172696e692f62696e6f63756c61722e7376673f7374796c653d737667)](https://circleci.com/gh/thiagomarini/binocular) [![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT) Doing CQRS + Event Sourcing without building a spaceship. An attempt to bring event sourcing down from the over-engineering realm. The aim of this project is to enable you to do CQRS + ES in PHP using your current stack, without the need to adopt any new technology. Sometimes classic database models are not enough to represent the state of an application. If you find yourself creating database views or using heavy SQL queries to present data in different ways Binocular is for you, it will bring structure and order to your application. A bit of a mindset shift is necessary to work with events tough, you'll have to think about producing and consuming events. But you don't need to do it everywhere or change the architecture of your application, you can do it only where database models are struggling to represent state. This project focus only on 3 elements of ES + CQRS: - **Event stream**: async stream of events produced by the application. The write side. - **Projections**: will replay and process events from the event stream to calculate state. - **Read models**: will cache the result of the event processing by the projection. The read side. For more information please read [my post](https://medium.com/@marinithiago/doing-event-sourcing-without-building-a-spaceship-6dc3e7eac000) supporting the idea. #### What's different about it? [](#whats-different-about-it) - Binocular is super lightweight and can be used with any framework. - Should only be used where database models are struggling to represent state in the application. - Projections use reducers to calculate the state of read models, a bit like [Redux](https://redux.js.org/basics/reducers): `previousState + event = newState`. Reducers make testing extremely simple, the same input always produces the same output. - Actions and reducers are versioned so events can evolve drama-free. - The only premise is that events need to be persisted somewhere so they can be replayed. - The project consists mostly of interfaces and base classes, you'll need to make your own implementation and know where to place things. #### Why Binocular as project name? [](#why-binocular-as-project-name) Like CQRS, binocular vision happens when two separate images from two eyes are successfully combined into one image in the brain. CQRS has two eyes: the read and write eyes. ### Usage in a nutshell [](#usage-in-a-nutshell) ``` composer require thiagomarini/binocular ``` ``` // save some events $eventRepository->store( new UserSignedUp($userId, ['name' => 'John']) ); $eventRepository->store( new UserNameWasUpdated($userId, ['name' => 'John Smith']) ); // use a projection to process the events and calculate the state of its read model $newState = $onboardingProjection->calculateState($userId); // save the read model state $readModelRepository->store($userId, $newState); print_r($newState); // ['name' => 'John Smith'] ``` ### Laravel Example [](#laravel-example) As already explained Binocular can be used with any framework, you just need to know where to place things. In the case of Laravel, it already has a simple [observer implementation](https://laravel.com/docs/master/events) which is more than enough to make things work with Binocular. I've created an [example app in Laravel](https://github.com/thiagomarini/binocular-laravel). In the example I used the `User` model as the root to be event sourced, meaning that will have its own events table and also a read model table. Conceptually you'll need to: - Create an [Eloquent implementation of the repository](https://github.com/thiagomarini/binocular-laravel/blob/master/app/EventSourcing/Repositories/UserEventRepository.php) if you don't want to use the PDO one. - Create [migrations](https://github.com/thiagomarini/binocular-laravel/tree/master/database/migrations) for event and read model tables. - Create a [custom implementation of the `event()` global helper](https://github.com/thiagomarini/binocular-laravel/blob/01a3449e31f70fd2689e74a601af294cfcbafea5/bootstrap/app.php#L60) in order to save the event before queueing it. - [Place a projection in an event listener](https://github.com/thiagomarini/binocular-laravel/blob/01a3449e31f70fd2689e74a601af294cfcbafea5/app/EventSourcing/Listeners/UserSubscriber.php#L41) to calculate and save the state of the read model. - [Fire events](https://github.com/thiagomarini/binocular-laravel/blob/01a3449e31f70fd2689e74a601af294cfcbafea5/app/Http/Controllers/Auth/RegisterController.php#L77) wherever you think it's appropriate. - The cached state will be available on the [read model](https://github.com/thiagomarini/binocular-laravel/blob/master/app/UserActions.php) and you can use it as any Eloquent model in the application. And remember that read models and projections are 1-1, meaning that one projection should produce state for one read model only. There's also other plain PHP examples on `tests/Examples` folder. ### How to contribute [](#how-to-contribute) PRs are welcome :) ### Health Score 31 — LowBetter than 68% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity27 Limited adoption so far Community11 Small or concentrated contributor base Maturity55 Maturing project, gaining track record Bus Factor1 Top contributor holds 75% 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 ~0 days Total 2 Last Release 2503d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/bfe5c11a846bda8dd46d0c0f7a9d236e4a303f627885c97d4719eff8b2f32614?d=identicon)[thiagomarini](/maintainers/thiagomarini) --- Top Contributors [![thiagomarini](https://avatars.githubusercontent.com/u/1078987?v=4)](https://github.com/thiagomarini "thiagomarini (3 commits)")[![oceanica](https://avatars.githubusercontent.com/u/1458771?v=4)](https://github.com/oceanica "oceanica (1 commits)") --- Tags eventcqrssourcing ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/thiagomarini-binocular/health.svg) ``` [![Health](https://phpackages.com/badges/thiagomarini-binocular/health.svg)](https://phpackages.com/packages/thiagomarini-binocular) ``` ### Alternatives [doctrine/event-manager The Doctrine Event Manager is a simple PHP event system that was built to be used with the various Doctrine projects. 6.1k501.1M114](/packages/doctrine-event-manager)[league/event Event package 1.6k141.6M183](/packages/league-event)[spatie/laravel-event-sourcing The easiest way to get started with event sourcing in Laravel 9003.7M26](/packages/spatie-laravel-event-sourcing)[laminas/laminas-eventmanager Trigger and listen to events within a PHP application 1.0k69.8M225](/packages/laminas-laminas-eventmanager)[ecotone/ecotone Supporting you in building DDD, CQRS, Event Sourcing applications with ease. 558549.8k17](/packages/ecotone-ecotone)[symfony/remote-event Eases handling remote events 293.0M6](/packages/symfony-remote-event) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)