rasuvaeff/yii3-outbox-db

Database-backed outbox storage for Yii3

v1.0.0 2026-06-12 04:53 UTC

Requires

• php: 8.3 - 8.5
• rasuvaeff/yii3-outbox: ^1.0
• yiisoft/db: ^2.0
• yiisoft/db-migration: ^2.0

Requires (Dev)

• ergebnis/composer-normalize: ^2.51
• friendsofphp/php-cs-fixer: ^3.95
• infection/infection: ^0.29
• maglnet/composer-require-checker: ^4.17
• phpunit/phpunit: ^11.5
• rector/rector: ^2.4
• roave/backward-compatibility-check: ^8.0
• vimeo/psalm: ^6.16
• yiisoft/cache: ^3.2
• yiisoft/db-sqlite: ^2.0
• yiisoft/test-support: ^3.0

BSD-3-Clause

• Victor Razuvaev

• database
• storage
• db
• transactional
• outbox
• yii3

README

Database-backed storage for rasuvaeff/yii3-outbox. Durably persists outbox messages in a yiisoft/db table so a worker can publish or export them asynchronously — surviving process restarts and downstream outages.

Using an AI coding assistant? llms.txt has a compact API reference you can use.

Requirements

• PHP 8.3+
• rasuvaeff/yii3-outbox ^1.0
• yiisoft/db ^2.0, yiisoft/db-migration ^2.0

Installation

composer require rasuvaeff/yii3-outbox-db

Usage

Migration

Apply the bundled migration to create the outbox table (default name outbox):

use M260611000000CreateOutboxTable;

(new M260611000000CreateOutboxTable())->up($migrationBuilder);
// custom table: new M260611000000CreateOutboxTable(table: 'my_outbox')

Recording and processing

use Rasuvaeff\Yii3Outbox\Outbox;
use Rasuvaeff\Yii3OutboxDb\DbOutboxStorage;

$storage = new DbOutboxStorage(db: $connection);          // ConnectionInterface
$outbox = new Outbox(storage: $storage, clock: $clock);

// request path — durable, no network call to the sink
$outbox->record(type: 'ab.exposure', payload: '{"experiment":"checkout"}');

// worker — fetch a batch of one consumer's types and process them
$pending = $storage->findPending(types: ['ab.exposure', 'ab.conversion'], limit: 1000);

Storage API

Method	Purpose
save(OutboxMessage)	upsert by id (initial record or retry re-save)
findPending(array $types = [], int $limit = 1000)	pending rows, optional type filter, created_at ASC
markPublished(OutboxMessage)	re-save with Published status
markFailed(OutboxMessage)	re-save with Failed status
getById(string $id)	single message or null
deleteByStatus(OutboxStatus)	housekeeping (e.g. purge Published)

findPending's $types filter lets several consumers — a generic Processor and a specialized exporter — share one outbox without competing for each other's messages.

Yii3 DI

The config-plugin binds StorageInterface to DbOutboxStorage from config/di.php. Core yii3-outbox binds nothing, so this backend (or the application) is the single source of StorageInterface. Set the table name in params:

// config/params.php
'rasuvaeff/yii3-outbox-db' => ['table' => 'outbox'],

Security

• All values are written through yiisoft/db parameterized commands.
• OutboxRowMapper validates every column and rejects corrupt rows with InvalidOutboxRowException — no silent coercion.
• Payloads may contain PII; retention/purging is the application's responsibility (deleteByStatus helps).

Examples

Runnable scripts live in examples/.

Development

make build        # full gate: validate + normalize + require-checker + cs + psalm + test
make cs-fix
make psalm
make test

Core yii3-outbox is consumed via a path repository while unpublished — see AGENTS.md for the monorepo-root Docker invocation.

License

BSD-3-Clause. See LICENSE.md.