PHPackages                             gosuperscript/zero-downtime-event-replays - 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. [Queues & Workers](/categories/queues)
4. /
5. gosuperscript/zero-downtime-event-replays

ActiveLibrary[Queues & Workers](/categories/queues)

gosuperscript/zero-downtime-event-replays
=========================================

Zero downtime event replay for Spatie's Laravel event sourcing package

3612.2k4[2 issues](https://github.com/gosuperscript/zero-downtime-event-replays/issues)[3 PRs](https://github.com/gosuperscript/zero-downtime-event-replays/pulls)PHP

Since Sep 27Pushed 3mo ago1 watchersCompare

[ Source](https://github.com/gosuperscript/zero-downtime-event-replays)[ Packagist](https://packagist.org/packages/gosuperscript/zero-downtime-event-replays)[ RSS](/packages/gosuperscript-zero-downtime-event-replays/feed)WikiDiscussions main Synced 2d ago

READMEChangelogDependenciesVersions (8)Used By (0)

Zero downtime event replay for Spatie's Laravel event sourcing package
======================================================================

[](#zero-downtime-event-replay-for-spaties-laravel-event-sourcing-package)

---

Usually you have to deal with a few problems that might cause downtime when replaying events. Your read models will be truncated at the beginning of a replay, and won't have the correct data until the replay has finished. Besides that, you'd have to wait with projecting newly recorded events until the replay has finished, to protect the replay order.

This package solves both problems, allowing a replay to happen to a copy of your read models. Once the replay is up to speed, newly recorded events will be played to both projections, so that your copy is kept up to date with the live read model. After verifying that the new replay is correct, the package enabled to promote your replay to live. Resulting in a (near) zero downtime release.

Usually running a new reply will look like this:

1. Create a new replay, ang give it key to identify it. For example "add\_extra\_field\_to\_balance\_projection". You also specify the projectors you want to play to in this step.

```
$manager = resolve(\Gosuperscript\ZeroDowntimeEventReplays\ReplayManager::class);
// Create a replay
$manager->createReplay('add_extra_field_to_balance_projection', [
    "App\Projectors\BalanceProjector"
]);
```

2. The replay can be started. When replaying, it calls the `useConnection` method on the projector. So the projector knows where it should write its data to. This package comes with an EloquentZeroDowntimeProjector that gives you some magic for dealing with different connections.

```
$manager->startReplay('add_extra_field_to_balance_projection');
```

3. Once the replay is finished, but there is still some lag to production because of newly recorded events. You can start the replay again, it will start from the latest projected event. Its always possible to monitor the state of the replay and the lag compared to production.

```
// get the state & progress of your replay
$manager->getReplay('add_extra_field_to_balance_projection');

// how many events is the replay behind the event stream?
$manager->getReplayLag('add_extra_field_to_balance_projection');
```

4. Once there is no lag, we can start projecting new events to replays.

```
$manager->startProjectingToReplay('add_extra_field_to_balance_projection');
```

5. Once every thing checks out, you can promote your replay to production.

```
    $manager->putReplayLive('add_extra_field_to_balance_projection');
```

6. Lastly you can cleanup your replay

```
    $manager->removeReplay('add_extra_field_to_balance_projection');
```

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

[](#installation)

You can install the package via composer:

```
composer require gosuperscript/zero-downtime-event-replays
```

Usage
-----

[](#usage)

```
$manager = resolve(\Gosuperscript\ZeroDowntimeEventReplays\ReplayManager::class);
// Create a replay
$manager->createReplay('your_replay_key', ['projectorA', 'projectorB']);

// Start replay history
$manager->startReplay('your_replay_key');

// get the state & progress of your replay
$manager->getReplay('your_replay_key');

// how many events is the replay behind the event stream?
$manager->getReplayLag('your_replay_key');

// once a replay is up to date with the event stream, we can project events to it when they happen
$manager->startProjectingToReplay('your_replay_key');

// Once the replay is approved, we can promote it to production
$manager->putReplayLive('your_replay_key');

// Or we can delete the replay
$manager->removeReplay('your_replay_key');
```

ZeroDowntime projectors
-----------------------

[](#zerodowntime-projectors)

In order to make projectors work with zero downtime replays, they have to implement the `ZeroDowntimeProjector` interface. This interface asks you to implement the following methods:

```
interface ZeroDowntimeProjector
{
    // This method lets the projector know that its replaying on a replay
    public function forReplay(): self;

    // Sets the connection to replay to, using the replay key. Each connection must be treated as a clone of the production schema.
    public function useConnection(string $connection): self;

    // Promote your connection to production
    public function promoteConnectionToProduction(): void;

    // cleanup/remove connection
    public function removeConnection();
}
```

Since most projections probably are replaying to eloquent, this package includes a `EloquentZeroDowntimeProjector` abstract class and a `Projectable` trait to be used on your eloquent read models.

To make your projectors work with this package:

1. Make sure your projector extends the `EloquentZeroDowntimeProjector`.
2. On all read models used by the projector, add the `Projectable` trait.
3. Implement a `models` method on your projector, that returns all models that the projector writes to. This is used by the EloquentZeroDowntimeProjector in order to setup the right db scheme and promote the right models to production.

```
    public function models(): array
    {
        return [
            new BalanceProjector(),
        ];
    }
```

4. Everywhere where you query or update your read model, use the `forProjection` method.

```
    // when truncating
    Balance::forProjection($this->connection)->truncate();

    // when querying
    Balance::forProjection($this->connection)->where('user_id', $event->user_id)->first();

    // when updating
    Balance::forProjection($this->connection)->where('user_id', $event->user_id)->increment('total', $event->amount);

    // when newing an instance
    $balance = Balance::newForProjection($this->connection, ['id' => $event->user_id, 'total' => $event->amount]);
    $balance->save();
```

Testing
-------

[](#testing)

```
composer test
```

Changelog
---------

[](#changelog)

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

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

[](#contributing)

Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

Credits
-------

[](#credits)

- [Robertbaelde](https://github.com/robertbaelde)
- [All Contributors](../../contributors)

License
-------

[](#license)

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

###  Health Score

33

—

LowBetter than 75% of packages

Maintenance41

Moderate activity, may be stable

Popularity33

Limited adoption so far

Community15

Small or concentrated contributor base

Maturity35

Early-stage or recently created project

 Bus Factor1

Top contributor holds 76.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.

### Community

Maintainers

![](https://www.gravatar.com/avatar/de7b0560fc6f16a90b64b73f125ab92331171f08d22a1569972ead0341eb9c01?d=identicon)[erikgaal](/maintainers/erikgaal)

---

Top Contributors

[![Robertbaelde](https://avatars.githubusercontent.com/u/4356288?v=4)](https://github.com/Robertbaelde "Robertbaelde (50 commits)")[![erikgaal](https://avatars.githubusercontent.com/u/1234268?v=4)](https://github.com/erikgaal "erikgaal (9 commits)")[![ekvedaras](https://avatars.githubusercontent.com/u/3586184?v=4)](https://github.com/ekvedaras "ekvedaras (4 commits)")[![eithed](https://avatars.githubusercontent.com/u/795678?v=4)](https://github.com/eithed "eithed (1 commits)")[![morrislaptop](https://avatars.githubusercontent.com/u/67807?v=4)](https://github.com/morrislaptop "morrislaptop (1 commits)")

### Embed Badge

![Health badge](/badges/gosuperscript-zero-downtime-event-replays/health.svg)

```
[![Health](https://phpackages.com/badges/gosuperscript-zero-downtime-event-replays/health.svg)](https://phpackages.com/packages/gosuperscript-zero-downtime-event-replays)
```

###  Alternatives

[league/geotools

Geo-related tools PHP 7.3+ library

1.4k5.3M26](/packages/league-geotools)[amphp/parser

A generator parser to make streaming parsers simple.

14952.8M16](/packages/amphp-parser)[amphp/serialization

Serialization tools for IPC and data storage in PHP.

13451.1M18](/packages/amphp-serialization)[enqueue/enqueue

Message Queue Library

19820.0M56](/packages/enqueue-enqueue)[deliciousbrains/wp-background-processing

WP Background Processing can be used to fire off non-blocking asynchronous requests or as a background processing tool, allowing you to queue tasks.

1.1k409.8k6](/packages/deliciousbrains-wp-background-processing)[react/async

Async utilities and fibers for ReactPHP

2238.8M171](/packages/react-async)

PHPackages © 2026

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