Repository navigation
Releases
v1.8.0
Added
- Message priority:
OutboxMessageDraft,OutboxMessage::create()and
Outbox::record()takepriority(int, default 0);
OutboxMessage::getPriority()is kept by everywith*()transition. A
storage claims higher priorities first, then oldest first — strict, no
aging — so a few low-volume messages (an audit entry) no longer wait behind
a bulk backlog (an HTTP journal) when the sink recovers. Equal priorities
keep the previous time order, so an outbox that never sets one behaves as
before.InMemoryStorageorders its claims and listings this way;
rasuvaeff/yii3-outbox-db2.6 stores the column (#36). OutboxMessage::MIN_PRIORITY/MAX_PRIORITY(-32768..32767): a priority
outside the range is rejected withInvalidArgumentExceptionby the draft
and the message.Serializerwritespriorityand reads it as optional
(absent → 0, non-integer →InvalidArgumentException).
v1.7.0
Added
Processortakes an optional type scope:new Processor(..., types: ['order.created'])
forwards the list toclaim()/claimReady(), so several consumers can
share one storage without one of them acknowledging what another was
supposed to deliver. The default[]keeps claiming every type. An empty
string in the scope is rejected withInvalidArgumentException(#26).PublishException::terminal()(and aterminal: falseconstructor
parameter,isTerminal()accessor): a publisher that knows no retry can fix
a failure — the receiver is gone, the payload was rejected as malformed —
says so, andProcessormarks the messageFailedat once instead of
spending the remaining attempts. The warning log context carries
terminal(#27).RequeueableStorageInterface(findFailed(),requeue()),
OutboxMessage::withAttemptsReset()andOutbox::requeueFailed(): a
Failedmessage can be put back toPendingwith its attempts reset once
the cause is fixed.requeue()only moves a message the storage currently
holds asFailedand returns whether it did (#28).StatsAwareStorageInterface::stats()returningOutboxStats— one count
per status plus the oldest pending message'screatedAt, with
total(),countOf()andoldestPendingAgeSeconds()for alerting (#29).BatchSavingStorageInterface::saveBatch(),OutboxMessageDraftand
Outbox::recordMany(): several messages recorded with one clock read and,
when the storage supports it, one write; falls back to onesave()per
message otherwise (#30).InMemoryStorageimplements all three new interfaces.
Fixed
- README: the "Recording a message" example used
$storagewithout defining
it (#31). composer.jsondeclaresextra.branch-alias(dev-master→1.x-dev) so
the family's config-merge harness can resolve the package from a path
repository (#32);testo/bridge-infectionis^0.1.6like everywhere
else, not an exact pin (#31).
v1.6.0
Added
BatchAcknowledgingStorageInterface, an optional extension of
StorageInterfacefor backends that can mark many messagesPublishedin
one statement:markPublishedBatch(list<OutboxMessage>). A consumer that
delivers a batch as a unit acknowledges through it instead of one
markPublished()per message; keep-vs-delete of acknowledged rows is the
storage's policy.InMemoryStorageimplements it.Processoris unchanged
(#24).
Changed
- Tests build their doubles with
rasuvaeff/understudy-testoinstead of
hand-written fake classes:SpyLogger,StubPublisher,StubClock,
FixedIdGenerator,FailingStorageandRecordingStorageare gone. The
storage decorators becameUnderstudy::delegate()doubles over the real
InMemoryStorage(a configuredthrows()wins, everything else forwards and
is recorded), the publisher's$publishedIds/$lastPublishedcounters read
the call log, and the logger assertions claim their counts with
verify(..., times:). Rector catches up with its current rule set insrc/
and the tests. Dev-dependency only; the public contract is untouched.
v1.5.0
Added
-
RetryAwareStorageInterface, an optional extension ofStorageInterfacethat
a backend implements when it can apply the retry policy inside the claim
itself, andRetryPolicy::readyThreshold(), which turns the per-message
isReadyForRetry()check into the boundary such a backend filters on.
Processordetects the interface and claims throughclaimReady(); a storage
without it keeps working unchanged
(#20).Until now every
Pendingmessage was claimed and the ones still waiting out
their backoff were written straight back asPending— two writes per
backing-off message per worker iteration, each occupying a slot inbatchSize
that a ready message could have used, so delivery latency grew with the size
of the retry queue.rasuvaeff/yii3-outbox-dbimplements the interface; a
hand-written storage does not have to.An implementation must keep claiming messages whose attempts are spent, in or
out of the backoff window: onlymarkFailed()terminates one, andProcessor
can only fail a message it was given. That is what themaxAttemptsargument
is for, and dropping it strands those rows asPendingforever.
Changed
ProcessingResult::$skippedreads0against a retry-aware storage. It
counts messages a batch claimed and then discarded, and the pushdown means
there are none — the work it used to count is what this release removes. A
dashboard or alert reading$skippedas "how many are backing off" was
already measuring wasted effort rather than queue depth, and now measures
nothing; countPendingrows with a future retry time instead.- A message that arrives with no attempts left is terminated up to
delaySecondslater than before, since it now waits for a batch that
includes it. Processor::process()reads the clock before claiming rather than after, so
one instant serves both the threshold it sends to the storage and the
per-message check it runs on the result — the two cannot disagree about what
"now" is. With a slow claim querylastAttemptAtis stamped marginally
earlier than the attempt itself, which makes the next retry marginally
earlier too.InMemoryStorageimplementsRetryAwareStorageInterface.
v1.4.0
Fixed
Processorno longer strands messages inProcessing. OnlyPublishException
was caught, so anything else a publisher let escape — a transport exception it
forgot to wrap, aTypeError— left every message the batch had claimed stuck
inProcessingwith no API able to move it back. The unexpected exception is
still rethrown (it is a bug, not a delivery failure), but the current message
is persisted per the retry policy and the rest of the claimed batch is
released first
(#18).- A storage failure is no longer reported as a publisher failure.
markPublished()
ran inside the publisher'stry, so throwing there after a successful
publish()loggedOutbox publisher threw an unexpected exceptionand sent an
operator to debug the wrong component. The two calls now have separate
handlers; the message still goes back toPendingand is published again on a
later run, which is the at-least-once behaviour the message id exists to let
consumers deduplicate. - Releasing an aborted batch no longer swallows the exception that aborted it.
release()reaches for the same storage that may be the reason the batch
failed; itssave()throwing replaced the original exception and left the
remaining messages unreleased. Each message is now released independently and
a release failure is logged (Failed to release a claimed outbox message,
Failed to persist an outbox message while aborting the batch) rather than
thrown. The invariant is documented for what it is: best-effort, since a
storage that is down cannot be told anything. - A
Pendingmessage claimed with its attempts already spent is markedFailed
instead of being saved back asPending. It could not be retried and nothing
else would ever terminate it, so it circled claim → skip → save forever while
an alert onFailedsaw nothing
(#18). Serializer::deserialize()now reports malformed dates and unknown statuses
asInvalidArgumentExceptionlike every other rejection in the class, instead
of letting a rawDateMalformedStringExceptionorValueErrorescape. An
empty datetime string — a valid "now" forDateTimeImmutable— is rejected
rather than silently stamping the message with the time it was read
(#18).
Added
- A property over the
Processorbatch lifecycle: for any batch, attempt
counts, backoff states and publisher behaviour (success,PublishException,
unexpected exception), no message is left inProcessingand none is left
Pendingwith its attempts spent. - A property over
Serializer::deserialize(): any input either yields a message
or fails withInvalidArgumentException.
Changed
- Document
SerializerInterfaceas the extension point it is, in both READMEs
andllms.txt; document whatProcessorguarantees about claimed messages. - Raise
rasuvaeff/property-testing-testoto^0.6.
v1.3.0
- Document the transactional invariant the pattern rests on:
Outbox::record()
must be called inside the same DB transaction as the business write, and the
storage must use that same connection. Stated in theStorageInterface::save()
andOutbox::record()PHPDoc, in both READMEs and inllms.txt— it was
unwritten knowledge before. - Document
claim()as the atomic primitiveProcessoractually uses. The
"Implementing storage" example only showedfindPending(), so a hand-written
storage following the README got non-atomic polling and duplicate delivery
across concurrent workers. - Add the missing
Processingcase to theOutboxStatusreference table, and
add aStorageInterfacesection to the API reference. InMemoryStorageimplementsCountable, socount($storage)works next to
the existingcount()method.- Declare
ext-jsoninrequire:Serializercallsjson_encode()/json_decode().
v1.2.0
Outbox::record()andOutboxMessage::create()accept an optionalid:
when a message mirrors a domain event, pass that event's identifier and
republishing it cannot mint a second message id — the consumer (or the
ClickHouseReplacingMergeTreethe messages land in) keeps a stable
deduplication key.- The generated id is now produced by
MessageIdGeneratorInterfaceinstead of
being hard-coded. The defaultRandomHexIdGeneratorkeeps the historical
format (32 random hex characters), so nothing changes unless a generator is
passed;Outbox's newidGeneratorargument is last and optional. - No UUID library is shipped or depended upon:
idisVARCHAR(255)in
rasuvaeff/yii3-outbox-db, so any format fits and the README shows the
five-line generator for both symfony/uid and ramsey/uuid. - Fix
examples/custom_storage.php: itsStorageInterfaceimplementation
still had the pre-1.1findPending(int $limit)signature and noclaim(),
so the script fatalled on run.
v1.1.0
- Ship an AI agent skill (
resources/skills/rasuvaeff-yii3-outbox/SKILL.md+
extra.skillsin composer.json): projects using thellm/skillsComposer
plugin get the skill synced into.agents/skills/automatically on install. - Document
StorageInterface::claim()andOutboxStatus::Processinginllms.txt. - Bump
rasuvaeff/property-testingto^2.6. - Make property-test generator methods
public static(private ones are removed by rector'sRemoveUnusedPrivateMethodRector— they are only called via reflection).
v1.0.2
- Add
/benchmarksand/Makefileto.gitattributesexport-ignore. - Pin
testo/bridge-infectionto0.1.6: 0.1.7/0.1.8 (2026-06-29) misclassify failing tests as passed under mutants, producing false escapes in mutation testing.
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.