Download the PHP package rasuvaeff/yii3-outbox without Composer
On this page you can find all versions of the php package rasuvaeff/yii3-outbox. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download rasuvaeff/yii3-outbox
More information about rasuvaeff/yii3-outbox
Files in rasuvaeff/yii3-outbox
Package yii3-outbox
Short Description Transactional outbox pattern for Yii3
License BSD-3-Clause
Homepage https://github.com/rasuvaeff/yii3-outbox
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package yii3-outbox
rasuvaeff/yii3-outbox
Русская версия
Transactional outbox pattern implementation for Yii3. Provides a stateless core for reliably publishing messages with configurable retry policies.
Using an AI coding assistant? llms.txt has a compact API reference you can use. Projects using the llm/skills Composer plugin also get this package's agent skill synced into
.agents/skills/automatically on install.
Requirements
- PHP 8.3+
psr/clock^1.0psr/log^3.0
Installation
Usage
Recording a message
The transactional guarantee
The pattern is only worth its name when the outbox write commits atomically with the business write it describes. The core cannot enforce this: it opens no transaction and knows nothing about your connection. Two obligations are therefore yours:
- Call
record()inside the same database transaction as the business write. - Use a storage that writes through the same connection as your business
tables —
rasuvaeff/yii3-outbox-dbtakes aConnectionInterfacefor exactly this reason.
Break either obligation and the guarantee is void: commit the order without the
message and the event is lost forever; commit the message without the order and
consumers observe an event that never happened. A storage backed by a different
database — or by a message broker — cannot provide this guarantee at all, and
InMemoryStorage is a test double, not a durable one.
Message ids
The message id is the primary key of the outbox table and, when messages are
exported to ClickHouse, the deduplication key of the ReplacingMergeTree.
Two ways to control it:
Pass the domain event's id — the right choice whenever the message mirrors an event that already has an identifier. Republishing the same event then cannot mint a second id, so the consumer has something stable to deduplicate on:
Bind a generator for messages that have no domain id. The default
RandomHexIdGenerator keeps the historical format (32 random hex characters);
a time-ordered id makes inserts append instead of scattering across InnoDB
pages and gives batches a stable order:
The package ships no UUID implementation and depends on no UUID library —
id is VARCHAR(255) in rasuvaeff/yii3-outbox-db, so any format fits and
the choice stays yours.
Implementing storage
claim() is the primitive the whole polling loop rests on — Processor calls
it, never findPending(). It must atomically move messages to Processing and
return them, so that two workers polling the same table never receive the same
message. findPending() is the read-only counterpart: safe for dashboards and
diagnostics, unsafe as a worker's fetch.
Implementing a publisher
Processing the outbox
Retry behaviour
When a publish fails:
- If attempts <
maxAttempts→ message staysPending, will be retried afterdelaySeconds - If attempts >=
maxAttempts→ message is markedFailed(terminal)
Using InMemoryStorage for tests
API reference
Outbox
| Method | Description |
|---|---|
__construct(storage, clock, idGenerator?) |
Main entry point; default generator = RandomHexIdGenerator |
record(type, payload, aggregateId?, id?) |
Create and persist message, returns OutboxMessage. id = the domain event's id; omitted → generator. Call inside the business transaction |
StorageInterface
| Method | Description |
|---|---|
save(message) |
Persist. Must commit with the business write — see The transactional guarantee |
claim(types = [], limit = 1000) |
Atomically moves up to limit Pending messages to Processing and returns them. What Processor uses; safe for concurrent workers |
findPending(types = [], limit = 1000) |
Read-only listing of Pending messages. No atomicity — for dashboards, not for workers |
markPublished(message) |
Terminal success |
markFailed(message) |
Terminal failure |
getById(id) |
?OutboxMessage |
types filters by message type (empty = all), which is how several consumers
share one outbox. Since claim() hands a message to exactly one caller, the
type sets of independent consumers must not overlap — otherwise each message
reaches only whichever worker claimed it first.
OutboxMessage
| Method | Description |
|---|---|
create(type, payload, aggregateId?, createdAt?, id?) |
Factory; id omitted → 32-char hex |
getId() |
Message ID (32-char hex) |
getType() |
Message type |
getPayload() |
Raw payload string |
getStatus() |
OutboxStatus enum |
getCreatedAt() |
DateTimeImmutable |
getAttempts() |
Number of publish attempts |
getLastAttemptAt() |
?DateTimeImmutable |
getAggregateId() |
?string |
withStatus(status) |
Returns new instance with status |
withAttempt(at) |
Returns new instance with incremented attempts and timestamp |
MessageIdGeneratorInterface
| Implementation | Produces |
|---|---|
RandomHexIdGenerator (default) |
32 hex characters, 128 random bits |
| your own | anything non-empty; id is VARCHAR(255) in the DB adapter |
OutboxStatus
| Case | Value | Meaning |
|---|---|---|
Pending |
'pending' |
Awaiting publication, including retries with attempts > 0 |
Processing |
'processing' |
Claimed by a worker; no other worker may take it |
Published |
'published' |
Terminal success |
Failed |
'failed' |
Terminal failure, retries exhausted |
RetryPolicy
| Method | Description |
|---|---|
__construct(maxAttempts, delaySeconds) |
Default: 3 attempts, 60s delay |
shouldRetry(message) |
Checks attempt count |
isReadyForRetry(message, now) |
Checks attempts + delay elapsed |
Processor
| Method | Description |
|---|---|
__construct(storage, publisher, retryPolicy, clock, batchSize, logger) |
Default batch: 100 |
process() |
Returns ProcessingResult |
ProcessingResult
| Property/Method | Description |
|---|---|
$published |
Count of successfully published messages |
$failed |
Count of publish exceptions this run |
$skipped |
Count of messages not ready for retry |
total() |
Sum of all counters |
Serializer
| Method | Description |
|---|---|
serialize(message) |
Message to JSON |
deserialize(data) |
JSON to Message |
Security
- Storage implementations must use parameterized queries for all user values.
- Message payload is stored as-is; validate before saving if needed.
Examples
See examples/ for complete usage examples.
Development
make test-coverage and make mutation bootstrap pcov inside the
composer:2 container because the base image has no coverage driver.
License
BSD-3-Clause. See LICENSE.md.
