NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
Packagist, #4682 most downloaded on Packagist
Async-first NATS + JetStream client for PHP 8.2+
Latest stable
v2.28.0
Last release 19 days ago
03 Nov 2026
Ships fairly regularly
a new release about every 3 weeks
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
8 months old
67 releases · first in 2026
Drag across the ruler to compare, or tap a release to open it.
Dynamic test hardening: protocol-parser fuzz + byte-boundary reassembly, reconnect-buffer flush ordering, heartbeat soak, and live nats CLI interopera
#95 — credential exposure via a configured tlsContext. Before 2.3.0 the CONNECT frame (token / user-password / JWT signature / NKey signature) could be transmitted in cleartext when a NatsOptions::$tlsContext was supplied but tlsRequired was off, the DSN used nats://, and the server's INFO did not advertise tls_required. The TLS-required check ignored tlsContext, so the upgrade and the cleartext fail-safe were both skipped. A configured tlsContext now forces the TLS upgrade (and fails fast if TLS cannot be established). Upgrading is recommended for anyone using the tlsContext escape hatch.
max_payload — large messages on big-max_payload servers were undeliverable and forced reconnects.history() tolerates metadata-less deliveries instead of tearing down all dispatch.json_encode in the shared dispatch loop — a binary/non-UTF-8 handler return no longer aborts delivery for every subscription.watch() onCaughtUp (end-of-initial-data) now fires on an empty / no-match bucket.E_WARNING before the typed ProtocolException.nats CLI / nats.go (empty metadata was serialized as a JSON array, which official clients reject).ObjectStoreWatchOptions — opt into reference "snapshot then follow" (last_per_subject) / full history / updates-only for ObjectStore::watch().$SRV.INFO response (ADR-32), so spec-conformant tooling can discover it.NatsOptions config table, WebSocket transport section, observability listeners, standalone-NKey example, and watch/digest PHPDoc.nats CLI interoperability tests; a runnable performance baseline (scripts/benchmark.php).Full changelog: CHANGELOG.md · compare v2.2.0...v2.3.0.
Your coding agent can read these notes before it upgrades. Set up the MCP server →
One column per month.
tlsContext (#95). Versions before 2.3.0 could transmit the
CONNECT frame - which carries the configured credentials (token / user-password / JWT signature / NKey
signature) - in cleartext when a NatsOptions::$tlsContext was supplied but tlsRequired was off,
the DSN used the nats:// scheme, and the server's INFO did not advertise tls_required. The TLS-required
check ignored tlsContext, so the upgrade and the cleartext fail-safe were both skipped. Fixed: a
configured tlsContext now forces the TLS upgrade (and fails fast if TLS cannot be established).
Upgrading is recommended for anyone using the tlsContext escape hatch. See the Fixed entry below.[feature] Object Store: ObjectStoreBucket::watch() now accepts an optional ObjectStoreWatchOptions
to select the delivery policy, mirroring the KeyValue watch matrix and the reference ObjectStore.Watch.
With no options (null) the watcher stays updates-only (deliver_policy=new, unchanged). Passing an
ObjectStoreWatchOptions instance opts into "snapshot then follow" - replay the current metadata of
every existing object first, then live updates (last_per_subject, the reference default) - or full
history (includeHistory) / explicit updates-only (updatesOnly). (#98)[feature] Services: a declared endpoint schema is now also surfaced in the standard $SRV.INFO
response endpoint entries. ADR-32 stabilizes only PING/INFO/STATS, so spec-conformant tooling (nats CLI
micro, nats.go) never queries the non-spec $SRV.SCHEMA verb; carrying the schema in INFO makes it
discoverable. The $SRV.SCHEMA verb is retained for backward compatibility. (#101)[bugfix] Object Store: an object stored with empty/default metadata is now readable by the official
NATS clients. Empty metadata was serialized as a JSON array ("metadata":[]), which the Go client
rejects with "object-store meta information invalid" because it expects a map; the field is now omitted
when empty (matching omitempty), restoring interoperability with the nats CLI / nats.go for the
common default-metadata case. Verified live against the nats CLI. (#109)[bugfix] KeyValue: watch()'s onCaughtUp (end-of-initial-data) signal now fires on an empty or
no-match bucket. Previously it could only fire from a delivered message reporting num_pending = 0, so
with nothing to deliver it never fired and a caller blocking on it hung forever. The signal is now also
derived from the created consumer's num_pending and fires immediately when the consumer starts with
nothing pending. (#99)[bugfix] Protocol: the inbound MSG/HMSG frame bound is now coupled to the server's negotiated
max_payload instead of a fixed 8 MiB. On a server with a raised max_payload (e.g. 16/32/64 MiB), a
legitimately large message larger than 8 MiB was rejected as an oversized frame - throwing a
ProtocolException that the connection turned into a reconnect, so the message was effectively
undeliverable. The parser bound is raised from INFO (max_payload + a header-block margin, never below
the historical 8 MiB), with a generous 64 MiB fallback when max_payload is unknown. (#94)[bugfix] Services: the endpoint success path no longer lets a json_encode failure escape the shared
dispatch loop. A handler returning a value that cannot be JSON-encoded (binary / non-UTF-8 data, NAN/INF)
previously threw a JsonException out of the subscription callback, aborting delivery for every
subscription on the connection. The response publish is now guarded: an encode failure is recorded and
answered with a controlled HANDLER_ERROR/500 reply (mirroring the handler-exception path), so one
endpoint returning binary data can no longer take down the whole client's dispatch. (#97)[bugfix] KeyValue: history() no longer uses the throwing messageMetadata() path. A delivery
lacking a parseable $JS.ACK reply subject (a control / non-conformant frame) is now skipped instead of
throwing out of the shared dispatch loop - which would tear down delivery for every subscription on the
connection (the same class fixed for watch() in #90) - and is no longer recorded as a bogus history
entry. (#96)[bugfix] TLS: a configured NatsOptions::$tlsContext now correctly forces the TLS upgrade, matching
its documented "treated as TLS-required" contract. Previously requiresTls() ignored tlsContext, so
a tlsContext-only configuration over a nats:// DSN to a server that did not advertise tls_required
connected in plaintext and wrote CONNECT (carrying credentials) in cleartext. The credentials fail-safe
now also covers this path, so a tlsContext whose handshake cannot establish TLS fails fast instead of
leaking credentials. (#95)[bugfix] WebSocket: a corrupt permessage-deflate frame no longer emits an uncaught native E_WARNING
from inflate_add()/deflate_add() before the typed ProtocolException. The warning is now suppressed
(the return-value check already raises ProtocolException), so apps that promote warnings to exceptions
get the intended ProtocolException instead of a generic ErrorException leaking from the codec. (#100)[docs] README "Reconnect Behavior" no longer wrongly states that publishes during reconnect are lost.
It now documents the outbound reconnect buffer (publishes are buffered up to reconnectBufferSize,
default 8 MiB, and flushed on reconnect; rejected only when the buffer is full, buffering is disabled, or
the connection is closed/not reconnecting), with test citations. (#102)[docs] README "Configuration Option Mapping" table now lists the 11 previously-omitted NatsOptions
fields - connectionListener, errorListener, jwtProvider, tokenProvider, reconnectBufferSize,
tlsContext, randomizeServers, retryOnFailedInitialConnect, webSocketHeaders,
webSocketCompression, logger - with types/defaults. NatsOptionsTest::testDefaultsMatchDocumentedValues
now asserts these defaults too, keeping the table's "asserted by" claim accurate. (#103)[docs] README: new "WebSocket Transport" section (with an Index entry) showing how to wire
WebSocketTransport, the ws:// / wss:// expectations, and the webSocketHeaders /
webSocketCompression options. (#104)[docs] README: the Observability note now documents the typed connectionListener /
errorListener closures, not just the PSR-3 logger. (#105)[docs] README: added a standalone-NKey authentication example (nkey + nonceSigner, no JWT) to the
Authentication Options block. (#106)[docs] PHPDoc: KeyWatchOptions and KeyValueBucket::watch() now make clear that the
last-per-subject "snapshot then follow" default applies only when a KeyWatchOptions instance is
supplied; watch() called with $options = null is updates-only and replays nothing. (#107)[docs] PHPDoc: ObjectInfo::$digest is no longer described as "Server-provided" - it is the content
digest recorded by the writing client and verified on read. (#108)[docs] Added a runnable performance baseline script (scripts/benchmark.php, request/reply + publish
throughput) and a sample-results table in the README's Performance section.Makes the per-feature NATS server-version requirements visible to users — without forcing a version check on every call.
Makes the per-feature NATS server-version requirements visible to users — without forcing a version check on every call.
Requires NATS X.Y+ notes in the method docblocks (so it shows up in your IDE).IDCT\NATS\JetStream\FeatureSupport::requiredVersion('allow_atomic') → "2.12".IDCT\NATS\Exception\UnsupportedFeatureException (a subclass of JetStreamException). When a request fails because the connected server is too old (it rejects the config field with unknown field "X"), the client raises this exception carrying the feature, the required version, and the server's reported version — instead of an opaque error.use IDCT\NATS\Exception\UnsupportedFeatureException;
try {
$js->batch()->add('orders.created', $payload)->commit()->await();
} catch (UnsupportedFeatureException $e) {
echo "{$e->feature} needs NATS {$e->requiredVersion}; server is {$e->serverVersion}\n";
}
The detection is reactive — derived from the server's own error response on failure, so there is no per-request version probe. Existing catch (JetStreamException) handlers still catch it (JetStreamException is no longer final so it can be specialized).
PHPStan level 8 clean; 497 unit tests passing.
Full changelog: https://github.com/ideaconnect/php-nats-jetstream-client/blob/main/CHANGELOG.md
[feature] Server-version awareness for version-gated features. Each feature's minimum NATS version
is documented (PHPDoc Requires NATS X.Y+ notes + a compatibility table in the README) and exposed
programmatically via the new IDCT\NATS\JetStream\FeatureSupport registry
(FeatureSupport::requiredVersion('allow_atomic') -> "2.12").[feature] New IDCT\NATS\Exception\UnsupportedFeatureException (a subclass of JetStreamException).
When a JetStream request fails because the connected server is too old for a feature (the server
rejects the config field with unknown field "X"), the client now raises this typed exception
carrying the feature, the required version, and the server's reported version - instead of an opaque
error. The detection is reactive (derived from the server's own response on failure); there is no
per-request version probe. JetStreamException is no longer final so it can be specialized
(existing catch (JetStreamException) handlers are unaffected).Verification pass for the 2.1.0 roadmap features against a live NATS 2.12.9 server, plus one bug fix.
Verification pass for the 2.1.0 roadmap features against a live NATS 2.12.9 server, plus one bug fix.
allow_atomic — the server rejects the previously-documented allow_atomic_publish with unknown field. Corrected the JetStreamContext::batch() / BatchPublisher docblocks and CHANGELOG. The BatchPublisher code itself was already correct and is now verified end-to-end (a 3-message batch commits 3/3, with the batch/count ack parsed).directGetLastForSubjects() and directGetBatch() return all messages correctly against the live server.trim($chunk) bug was fixed back in v1.0.1 but had no test guarding it.PHPStan level 8 clean; 491 unit tests and the full 76-test integration suite pass against NATS 2.12.9 (including the auth/TLS/JWT/nkey servers).
Full changelog: https://github.com/ideaconnect/php-nats-jetstream-client/blob/main/CHANGELOG.md
Verification pass for the 2.1.0 roadmap features against a live NATS 2.12.9 server.
[bugfix] Atomic batch publish (#8): the stream-config field is allow_atomic - the server
rejects the previously-documented allow_atomic_publish with unknown field. Corrected the
batch()/BatchPublisher docblocks (the BatchPublisher code itself was already correct and is now
verified end-to-end: a 3-message batch commits 3/3 with the batch/count ack parsed).trim($chunk) bug fixed
in v1.0.1 previously had no test). Full integration suite (76 tests) passes against NATS 2.12.9.NATS 2.11 / 2.12 client feature support. A minor, backward-compatible release (new optional parameters and new methods only); the single behavior chan
NATS 2.11 / 2.12 client feature support. A minor, backward-compatible release (new optional parameters and new methods only); the single behavior change is bug-driven. Implements the roadmap milestone (issues #4–#11, #13), hardened by an adversarial multi-agent review.
Nats-TTL, ADR-43, #4) — publish(..., ttl:), KeyValueBucket::put(..., ttl:), and tombstone TTL on delete()/purge(). New MessageTtl formatter (seconds / Go duration / never).Nats-Msg-Id, #11) — publish(..., msgId:); publish() also takes a generic headers array.@every, 6-field cron, and the predefined aliases (@daily, @hourly, …); @at now accepts RFC3339 numeric offsets. Schedule::every()/cron()/predefined(); optional Nats-Schedule-Source/-Time-Zone/-Rollup headers.AllowMsgCounter/Nats-Incr, ADR-49, #9) — incrementCounter() / counterValue(), arbitrary-precision (string) safe.filter_subjects, #10) — validated, mutually exclusive with the singular filter.AllowAtomicPublish, ADR-50, #8) — JetStreamContext::batch() → BatchPublisher (Nats-Batch-Id/-Sequence/-Commit; start sent as a request so a rejected batch aborts early; capped at 1000).fetchBatch()/fetchNext() pull options (group/min_pending/min_ack_pending/priority/max_bytes/no_wait); PullConsumerIterator setters with Nats-Pin-Id capture and 423 re-pin; new unpinConsumer() / pinIdOf().directGetBatch() / directGetLastForSubjects().Nats-Marker-Reason, ADR-43, #5) — KV get()/getAll()/watch() and Object Store watch()/info() now treat a server-written delete-marker as a tombstone instead of surfacing it as a live empty value. Flagged [bugfix] (so it does not force a major bump); only reachable when a stream has subject_delete_marker_ttl set. See the migration note in the CHANGELOG.Atomic batch publish (#8) and batched Direct Get (#13) are unit-tested at the wire level but not yet verified against a live NATS 2.11/2.12 server.
Full changelog: https://github.com/ideaconnect/php-nats-jetstream-client/blob/main/CHANGELOG.md
NATS 2.11/2.12 client feature support (roadmap milestone, GitHub issues #4-#14). All changes are
backward compatible (new optional parameters / new methods); the one behavior change (#5 delete
markers) is bug-driven and flagged [bugfix], so this is a minor release.
[bugfix] Honor JetStream subject delete-markers (Nats-Marker-Reason: MaxAge/Remove/Purge, ADR-43,
issue #5). A server-written delete-marker is now treated as a tombstone rather than a live value:
KeyValueBucket::get() returns a PURGE entry with a null value (was an empty-string PUT),
getAll() omits the key, watch() emits a tombstone, and ObjectStoreBucket::watch()/info() skip
the marker. Behavior change (flagged bc-break on the issue, but bug-driven so versioned as a
bugfix): only reachable when a stream has subject_delete_marker_ttl set, which this client now also
forwards as a create option.[feature] Batched / multi Direct Get (ADR-31, issue #13). New directGetBatch() collects a
multi-response Direct Get stream (terminated by a 204 EOB or Nats-Num-Pending: 0), and
directGetLastForSubjects() fetches the latest message for many subjects in one request via
multi_last. Additive - the existing per-subject bulk paths (getAll()/list()) are unchanged
pending live verification on a 2.11+ server.[feature] Pull-consumer priority groups and richer pull options (ADR-42, issue #7).
fetchBatch()/fetchNext() accept a $pull array (group, id, min_pending,
min_ack_pending, priority, max_bytes, no_wait); PullConsumerIterator gains
setGroup()/setPriority()/setMinPending()/setMinAckPending()/setMaxBytes()/setNoWait()
and transparently captures the Nats-Pin-Id and re-pins on a 423 stale-pin status. New
unpinConsumer() (CONSUMER.UNPIN) and pinIdOf(); consumer-create validates priority_groups/
priority_policy.[feature] Atomic (all-or-nothing) batch publish (ADR-50, issue #8). JetStreamContext::batch()
returns a BatchPublisher: add() stages messages and commit() sends them with a shared
Nats-Batch-Id, an incrementing Nats-Batch-Sequence, and Nats-Batch-Commit: 1 on the final
message, returning a single PubAck exposing the committed batchCount/batchId. Capped at 1000
messages; an aborted batch surfaces as a JetStreamException. Requires allow_atomic_publish on
the stream.[feature] Multi-subject consumer filters (issue #10, NATS 2.10+). The consumer-create methods now
accept a filter_subjects array (via options), validated client-side and mutually exclusive with the
singular filter subject (combining the two is rejected with a clear error instead of an opaque server
rejection).[feature] Distributed counter CRDT (ADR-49, issue #9). JetStreamContext::incrementCounter()
publishes a Nats-Incr delta (signed/unsigned integer string) and returns the new total;
counterValue() reads the current value via Direct Get ("0" when absent). Values are handled as
strings (decoded with JSON_BIGINT_AS_STRING) so arbitrary-precision counters are not truncated.
The target stream must be created with allow_msg_counter enabled.[feature] JetStreamContext::publish() now accepts optional message headers - a generic
array $headers, a $msgId (Nats-Msg-Id) for server-side de-duplication within the stream's
duplicate_window (issue #11), and a per-message $ttl (Nats-TTL; requires allow_msg_ttl on
the stream - issue #4). KeyValueBucket::put() takes an optional per-key $ttl, and
delete()/purge() take an optional tombstone TTL. TTL values (integer seconds, a Go duration
string, or "never") are validated client-side via the new MessageTtl helper.[feature] Recurring and cron scheduled publishing (ADR-51, issue #6). Schedule::every() builds
an @every <interval> expression (from an integer number of seconds or a Go-style duration string)
and Schedule::cron() validates/returns a 6-field (seconds-resolution) cron expression.
Schedule::predefined() returns a predefined alias (@daily, @hourly, ...).
JetStreamContext::publishScheduled() now accepts @at (with Z or a numeric RFC3339 offset),
@every, cron, and the predefined aliases (previously only @at with Z) and emits the optional
Nats-Schedule-Source, Nats-Schedule-Time-Zone (cron/alias only, rejected otherwise), and
Nats-Schedule-Rollup: sub headers alongside the existing
Nats-Schedule/-Target/-TTL. The target stream must be created with allow_msg_schedules
enabled (e.g. createStream(..., ['allow_msg_schedules' => true])).> See Breaking changes below before upgrading.
Major release. Broad correctness, robustness, security, and performance hardening across the connection, JetStream, KeyValue, ObjectStore, and microservices layers — plus the rewrite of Object Store to the official NATS layout for cross-client interoperability.
Every change ships with tests. The build is green on PHPStan level 8, the unit suite, the live integration suite, and the Behat end-to-end suite across token / user-pass / TLS / TLS-upgrade / NKey / JWT servers.
Heads-up: this release contains intentional, bug-/spec-driven backward-incompatible changes. See Breaking changes below before upgrading.
Object Store rewritten to the official NATS layout (data-format break). Chunks are now stored
under $O.<bucket>.C.<nuid>, the digest is base64url, meta subjects are base64-encoded, and the
meta record carries nuid (was chunk_subject). Buckets written by 1.x are not readable by
2.0 and vice-versa. Upside: buckets are now interoperable with the nats CLI and the official
clients. Migrate by re-uploading objects with 2.0.
ObjectInfo::$chunkSubject removed → renamed to $nuid (and a new ?int $revision was
added). Read $info->nuid instead of $info->chunkSubject; positional new ObjectInfo(...)
construction changed.
ObjectStoreBucket::get() on a deleted object now returns null (was an ObjectData with the
deleted flag set). Use info() to observe a tombstone.
Service endpoints now share queue group "q" by default (addEndpoint() default
$queueGroup changed null → "q"). Multiple instances of a service now load-balance (one
instance handles each request) per the NATS micro spec, instead of fan-out (every instance handled
every request). To keep fan-out, pass queueGroup: null.
TransportInterface gained a required upgradeTls(): Future method, and readLine() must now
signal peer-close (EOF) by throwing TransportClosedException instead of returning ''. Custom
transport implementations must be updated.
SubscriptionQueue::next() with no timeout configured is now non-blocking (a single bounded
cycle returning null when nothing is immediately available), instead of blocking until a message
arrives. Configure a timeout if you need a bounded wait.
Validation tightening (rejecting already-invalid input — bad header names, dotted/consecutive-dot KV keys, dotted bucket names, oversized frames/control lines, non-positive chunk size) is deliberately scoped to invalid usage and does not affect valid callers.
flush() on NatsClient/NatsConnection — PING/PONG round-trip confirming the server has
processed prior writes (e.g. a SUBSCRIBE before a dependent request).ObjectStoreBucket::putStream() — memory-bounded streaming upload from a producer callback
(the counterpart to getToCallback()); blocks of any size are re-chunked, pipelined, and hashed
incrementally.directGetStreamMessage(), directGetLastMessageForSubject(), and
streamSequenceOf(). KeyValue get()/getAll() and Object Store info()/get()/list() read
via Direct Get (served by any replica), with automatic fallback to leader STREAM.MSG.GET when a
stream has allow_direct disabled.TlsAwareTransportInterface, plus the
tlsHandshakeFirst option wired through.addEndpoint(..., metadata:)), advertised in $SRV.INFO, and
spec-compliant queue-group load balancing by default.processIncoming(?Cancellation) accepts an optional cancellation; ObjectInfo::revision is now
populated; SubscriptionQueue gained unsubscribe()/close().Connection / reconnect
drain() always closes the socket and clears state, even on a fatal frame mid-flush.JetStream
$JS.ACK subjects are parsed (gap detection + revision work on
domain/leaf deployments).Nats-Consumer-Stalled subject (throttled
consumers no longer hang).publish()/publishScheduled() translate no-responders into a JetStreamException (503).KeyValue / Object Store
getAll() paginates the subjects map (no silent truncation) and surfaces API errors.list(), fast-paths single-chunk
downloads via Direct Get, and verifies the digest by bytes (tolerating unpadded base64url).JetStreamException (not a raw JsonException).Services / protocol / security
Nats-Service-Error / Nats-Service-Error-Code
headers; start() is atomic with rollback; observers always receive request_end.replyTo, header names/values, and bucket names are validated (protocol-injection safe); the NKey
seed is zeroed after key derivation and checked against any configured nkey; the handshake-first TLS
path no longer risks writing credentials in cleartext.getAll() and Object Store list() read all records concurrently via Direct Get.put()/delete() overlap the previous-revision lookup with the upload; single-chunk
downloads take one round-trip; putStream() re-chunks in O(n).queueGroup: null to addEndpoint() to
restore fan-out.TransportInterface implementations must add upgradeTls() and throw
TransportClosedException on EOF.Full per-change detail with test references is in CHANGELOG.md.
Findings from a deep review against a live NATS 2.12 server (README correctness,
real-server behavior, bugs, and performance). Object Store interoperability with
the nats CLI, idle-connection heartbeat survival, and request-timeout recovery
were all verified working and are unchanged.
[feature] Added flush() (on NatsClient/NatsConnection): sends a PING and waits for the
server's PONG, confirming the server has processed everything written so far (e.g. a SUBSCRIBE
before publishing a dependent request). Bounded by the request timeout.[feature] Service endpoints accept optional per-endpoint metadata (addEndpoint(..., metadata:)),
advertised in the $SRV.INFO response per the NATS micro spec.[bugfix] The protocol parser now rejects a size/sid token that would overflow a PHP int (which
(int) silently saturates to PHP_INT_MAX) as a ProtocolException.[bugfix] NkeySeedSigner now zeroes the raw seed and key-pair buffers (sodium_memzero) once the
Ed25519 key is derived; ProtocolCodec fails fast if a configured nkey does not match the seed
signer's public key. The service started timestamp now carries sub-second precision.[bugfix] ObjectStoreBucket::putStream() no longer recopies the buffer tail per chunk (O(n^2)
for a producer block much larger than chunkSize); it advances a read offset and compacts once per
block. The constructor now rejects a non-positive chunkSize (which made put()/putStream() loop
forever) with a JetStreamException.[bugfix] Object Store info()/get()/list() now populate ObjectInfo::revision from the
record's stream sequence (the Nats-Sequence Direct Get header, or the seq of the STREAM.MSG.GET
fallback) instead of always leaving it null.[bugfix] KeyValue/Object Store bucket names are now validated (^[A-Za-z0-9_-]+$); a name with
dots or wildcards would otherwise mis-scope the backing stream subjects.[bugfix] JetStream publish()/publishScheduled() now translate a no-responders reply into a
JetStreamException (code 503) - e.g. publishing to a subject not bound to any stream - so a
catch (JetStreamException) no longer misses it as a bare NatsException.[bugfix] drain() now always closes the socket and clears state even if a fatal frame surfaces
mid-flush, instead of escaping the flush loop and leaving the connection wedged in Draining.[bugfix] Reconnect no longer deadlocks when a subscription handler publishes during recovery.
Subscription-replay (drainImmediateServerFrames) previously delivered buffered messages to user
callbacks while still inside the reconnect critical section; a callback that published and hit a
write failure re-entered recoverConnection() and awaited the in-progress reconnect, hanging the
recovery fiber. Buffered messages are now delivered after recovery completes (outside the critical
section), so such a callback starts a fresh recovery instead of deadlocking.[bugfix] Microservice endpoint error replies now carry the NATS micro-spec Nats-Service-Error
and Nats-Service-Error-Code reply headers (400 for validation, 500 for handler errors), so a
generic client (Go micro, nats CLI) detects the failure by header instead of treating the
header-less JSON error body as success. The description is collapsed to a single line so a crafted
message cannot break header framing; the JSON error body is unchanged.[bugfix] KeyValue getAll() now paginates the STREAM.INFO subjects map (via offset) instead
of reading a single page, so a bucket with more keys than the server's subjects-map cap is no longer
silently truncated (mirroring Object Store list()), and it now throws on a STREAM.INFO API error
instead of swallowing it into an empty result.[bugfix] Single-record Direct Get reads now fall back to the leader STREAM.MSG.GET path
when Direct Get is unavailable (a stream with allow_direct disabled, or an older server). The
no-responders error is translated to a clear JetStreamException (code 503); KeyValue get() and
Object Store info()/get() (single-chunk fast path) then retry on the leader, so reads keep
working on interop buckets (e.g. created by the nats CLI without allow_direct) instead of
surfacing an opaque error.[bugfix] Ordered-consumer gap detection and streamSequenceOf() (used for KV/Object Store
revision) now parse the 11-token domain-qualified ACK reply subject
($JS.ACK.<domain>.<account>.<stream>... without the trailing random token), not just the 9- and
12-token forms. Previously the sequence fell through to null on JetStream-domain/leaf deployments,
silently disabling gap detection and revision tracking there.[bugfix] The plaintext-credentials fail-safe now also covers the handshake-first TLS path. The
guard that refuses to write CONNECT (which carries jwt/sig/nkey/user/pass/token) over a still-plain
socket was gated on the non-handshake-first branch, so tlsHandshakeFirst=true combined with no TLS
materials (and a nats:// DSN) while the server's INFO advertised tls_required could leak
credentials in cleartext. The fail-fast now runs whenever TLS is required and the handshake did not
establish it, regardless of tlsHandshakeFirst.[bugfix] A JetStream flow-control STALL heartbeat is now answered. The server leaves the message
reply empty for a stall and puts the flow-control reply subject in the Nats-Consumer-Stalled
header value; the client previously detected the stall but published to the empty reply, so the
ack never reached the server and a throttled ordered/flow-controlled consumer could stall
indefinitely with no error surfaced. The normal $JS.FC. flow-control-request reply path is
unchanged.[bugfix] Subscription dispatch is now non-reentrant per SID. If a handler awaits on the
connection (e.g. an ordered consumer recreating itself during gap recovery), a heartbeat tick
or a nested request() self-pump could previously re-enter the per-SID drain and deliver that
subscription's next message on top of the still-suspended handler - corrupting ordered-consumer
recovery state (stale by-reference sequence/consumer-name -> duplicate deleteConsumer/recreate)
and causing overlapping/duplicate delivery. Delivery for a SID in flight is now deferred until
the suspended handler returns (FIFO preserved); other SIDs stay deliverable so nested requests
still complete.[bugfix] The CONNECT frame now advertises the resolved client library version (from the
installed Composer package, with a constant fallback) instead of the stale hardcoded
0.1.0-dev, so server connz/monitoring attributes traffic to the correct version.[bugfix] Header publishes (publishWithHeaders(), KV/Object Store metadata writes) now
build and CR/LF-validate the header wire block once and reuse it for sizing and each write
attempt, instead of re-running toWireBlock() two or three times per publish.[bugfix] The per-chunk subscription drain no longer rescans every subscription that has
ever received a message: a drained (or undeliverable) per-SID queue is now released, so the
drain stays proportional to the subscriptions with pending messages. This also fixed a latent
coupling where the request UNSUB cleanup was gated on the (now-released) pending queue.[bugfix] Object Store get()/getToCallback() now fetch a single-chunk object with one
Direct Get on its chunk subject, instead of creating, pulling from, and deleting a transient
ephemeral consumer - turning the common small-object download from 4 round-trips into 1 (plus
the metadata read). Multi-chunk objects still use the batched pull-consumer path.[bugfix] Object Store put() and delete() now run the previous-revision lookup
concurrently with the chunk upload / tombstone publish, awaiting it only just before the
best-effort chunk purge it feeds. Previously the lookup was a serial round-trip on the
critical path before the first byte was written, roughly doubling small-object write
latency. The lookup is issued at the same coroutine depth as the upload, so request
ordering stays deterministic.[bugfix] Ephemeral push consumers (KeyValue/Object Store watch(), ordered consumer)
now set an inactive_threshold, so the server reaps them once the subscription ends
instead of leaking server-side consumers when a long-running app re-subscribes. An active
subscription keeps the consumer alive; callers may override the threshold.[bugfix] SubscriptionQueue now bounds its polling backlog with
maxPendingMessagesPerSubscription and the configured slow-consumer policy. Previously
the connection's per-chunk drain emptied its (capped) queue into the unbounded polling
queue, so a queue consumed slower than it was fed could grow until OOM.[bugfix] Object Store list() now paginates the meta-subject enumeration (via the
STREAM.INFO offset) instead of reading a single page, so a bucket with more objects
than the server's subjects-map cap is no longer silently truncated. The loop terminates
on the first empty/duplicate page, so it is safe even against a server that ignores
offset.[bugfix] NatsHeaders::toWireBlock() now rejects an empty/blank header name or one
containing whitespace or a colon (previously only CR/LF were rejected, so a bad name
silently produced a malformed/mutated block), and trims surrounding whitespace from
values so they round-trip symmetrically with decode (which already trims).[bugfix] Object Store digest verification now compares the decoded digest bytes
(tolerating missing base64url padding) with hash_equals(), instead of a string compare
that spuriously rejected a byte-identical object whose metadata used unpadded base64url
(some non-Go clients).[bugfix] KeyValue get()/update()/delete()/purge()/getAll() now wrap a
malformed (non-JSON) reply in a JetStreamException instead of leaking a raw
JsonException, consistent with put() and the rest of the API.[bugfix] The protocol parser now bounds an unterminated control line (no CRLF) to 1 MiB
and raises a ProtocolException instead of buffering it without limit. maxFrameSize
only bounded MSG/HMSG payloads (parsed after their control line completes), so a peer
streaming bytes without a CRLF could drive the client to OOM.[bugfix] Service::start() is now atomic: if a subscribe fails partway, it rolls back
the subscriptions already made and rethrows, instead of leaving the service
half-initialized with the idempotency guard then masking a retried start() as a no-op.
A separate started flag tracks completion.[bugfix] Microservice request observers now receive the terminal request_end event
on the schema-validation rejection path too (previously only request_start ->
request_error fired), so observer spans/timers/gauges are not leaked for rejected
(often hostile) traffic.[bugfix] NatsClient::service() now validates the service name
(^[A-Za-z0-9_-]+$) and requires a semantic version, failing fast instead of crashing
start() mid-loop or over-subscribing to discovery subjects when the name contains a
dot/space/wildcard.[bugfix] request() (and every JetStream/KV/Object Store call built on it) no longer
throws a spurious TimeoutException when the reply is delivered in the same event-loop
tick the deadline fires. The wait loop now checks for completion before the deadline, so
a reply that lands as the timeout expires is returned instead of discarded.[bugfix] Ordered-consumer gap recovery now contains a failed consumer recreate
(pruned/deleted stream, leadership change, transient timeout) instead of throwing out of
the shared subscription dispatch loop and aborting delivery for every other subscription
on the connection.[bugfix] PullConsumerIterator infinite mode (setIterations(null)) now survives a
transient 409 (Exceeded MaxAckPending, Leadership Change, Server Shutdown,
Exceeded MaxWaiting) and keeps polling, instead of treating every non-404/408 status
as terminal and silently exiting forever. A terminal 409 Consumer Deleted still stops
the loop, and finite mode is unchanged.[bugfix] drain() no longer busy-spins (100% CPU) or hangs when the server never
sends the flush PONG. The flush loop now yields between empty reads so its deadline can
fire; previously a synchronous 0-frame read starved the event loop, so the
TimeoutCancellation could never fire and drain() never returned.[bugfix] drain() no longer resurrects the connection on a read failure mid-flush. A
peer close during drain previously triggered recoverConnection() - reconnecting and
re-SUBscribing the very subscriptions drain() had just removed (and possibly
re-delivering messages). processIncoming() now skips recovery while the connection is
Draining and treats the read failure as end-of-flush.[bugfix] CredentialsParser now parses real nsc-generated .creds files. The
marker regex required exactly five dashes on both the BEGIN and END lines, but the
NATS toolchain emits five dashes on BEGIN and six on END, so
CredentialsParser::fromFile() threw Credentials file does not contain a NATS USER JWT block on essentially every genuine credentials file - making the documented
JWT-via-.creds auth path unusable. Both markers now accept five-or-more dashes.[bugfix] Object Store now stores a 0-byte object with chunks=0 and publishes no
chunk message, matching the official Object Store layout; previously it wrote one
empty chunk and recorded chunks=1. get() of an empty object also returns
immediately instead of blocking until the download batch expiry waiting for a chunk
that never arrives.[bugfix] Object Store get() and getToCallback() now return null for a deleted
(tombstoned) object, consistent with a missing object and the official not-found
semantics; the tombstone metadata remains observable via info(). Previously get()
returned an ObjectData with null data and getToCallback() returned the
ObjectInfo.[bugfix] Microservice handler errors no longer leak the raw exception message to the
requester: the reply carries a generic Internal server error under the
HANDLER_ERROR code, while the full detail stays server-side (endpoint lastError,
$SRV.STATS, and the request_error observer event).[bugfix] Service $SRV.STATS no longer emits the non-spec requests/errors
aliases; only the spec-compliant num_requests/num_errors remain.[bugfix] Connections now disable Nagle's algorithm (TCP_NODELAY). NATS is a
small-message request/reply protocol, and Nagle combined with delayed ACKs added
roughly 40 ms of latency per round trip; local request/reply throughput improved
about 16x in a single-process benchmark (~22 to ~365 req/s) after this change.[bugfix] Ordered consumers (subscribeOrderedConsumer()) now deliver in order,
gap-free, and without duplicates. Gap detection was based on the stream sequence,
which is non-contiguous for a filtered consumer, so every filtered delivery looked
like a gap; and on a gap the out-of-order message was forwarded and the expected
sequence advanced past it, causing duplicate/out-of-order delivery and a cascading
consumer delete+recreate storm. Detection now uses the JetStream consumer
(delivery) sequence, the out-of-order message is discarded, and the consumer is
recreated from the last in-order stream sequence (resuming from the next available
message if the restart point was pruned).[bugfix] NatsOptions now rejects genuinely-invalid configuration at construction
(non-positive connectTimeoutMs/requestTimeoutMs, maxPendingMessagesPerSubscription
below 1, and negative reconnect/maxPingsOut values) with an InvalidArgumentException,
instead of misbehaving later. Legitimate edge values stay valid: pingIntervalSeconds
<= 0 disables the heartbeat, maxPingsOut 0 is allowed, and an empty servers list
falls back to the default - so this is input validation, not a breaking change.[bugfix] KeyValue keys with a leading, trailing, or consecutive dot (which produce a
malformed $KV.<bucket>.<key> subject) are now rejected up front; dots, colons and
slashes elsewhere in a key remain valid.[bugfix] Object Store put() now pipelines chunk publishes in bounded in-flight
windows instead of awaiting one PubAck round-trip per chunk, so large-object uploads
are no longer strictly round-trip-bound. PUB frames are written to the single
connection in chunk order, so stream order (and download reassembly) is preserved.[bugfix] Single-record reads - KeyValue get() and Object Store info() (and the
metadata read behind get()/getToCallback()) - now use the Direct Get API (served by
any replica) instead of leader-only STREAM.MSG.GET, consistent with getAll()/list().
On clustered/replicated streams this stops concentrating reads on the stream leader. (The
internal put/delete cleanup lookup stays on STREAM.MSG.GET for deterministic ordering.)[bugfix] KeyValue getAll() and Object Store list() now read the latest record
per key/object via the Direct Get API issued concurrently, instead of N+1 sequential
leader-only STREAM.MSG.GET reads. For large buckets this stops hammering the stream
leader and collapses O(keys) serial round-trips into roughly one round-trip of
wall-clock. (Concurrent request/reply on a single connection is covered by a new
integration test.)[bugfix] publish() and publishScheduled() now wrap a malformed (non-JSON)
acknowledgment in a JetStreamException instead of leaking a raw JsonException,
consistent with the other JetStream API calls.[bugfix] Direct Get now rejects an unrecognized response (no status line and no
Nats-Stream/Nats-Sequence headers) with a JetStreamException instead of
returning a garbage body, guarding against a non-conformant server/proxy.[bugfix] KeyValue watch() now delivers updates through a JetStream push consumer
(deliver_policy=new, ack-free) so each entry carries its revision (the stream
sequence). Previously it used a plain core subscription and always reported
revision=null, so a watcher could never feed an entry back into update()/CAS.
Live-updates-only semantics are unchanged.[feature] JetStreamContext::streamSequenceOf() returns the stream sequence of a
JetStream-delivered message (from its $JS.ACK reply).[feature] ObjectStoreBucket::putStream() uploads an object from a producer callback
without holding the whole payload in memory (the streaming counterpart to
getToCallback()): blocks of any size are re-chunked to chunkSize, published in bounded
in-flight windows, and the SHA-256 digest is computed incrementally.[feature] Object Store watch() now delivers updates through a JetStream push consumer
(consistent with KeyValue watch()) and exposes each update's stream sequence via the new
ObjectInfo::$revision field. Previously it used a plain core subscription that carried no
sequence/revision. Live-updates-only semantics (deliver_policy=new, ack-free) are
unchanged; $revision is null on ObjectInfos from get()/info()/list().[bugfix] Service::stop() now tolerates a closed/lost connection: it unsubscribes
each endpoint best-effort and always clears its subscription state, instead of
aborting on the first failure (which leaked the remaining subscriptions and broke a
later start() restart).[bugfix] Service::addEndpoint() now rejects a duplicate subject with an
InvalidArgumentException instead of silently overwriting the earlier endpoint and
handler (which also under-reported them in INFO/SCHEMA/STATS).[bugfix] Service::run() now stops when the connection is unrecoverable (closed
for good) and backs off interruptibly, instead of busy-spinning at ~50 Hz silently
swallowing the error.[bugfix] The microservice discovery handler now swallows an encode/publish failure
(e.g. invalid-UTF-8 metadata) instead of throwing out of the shared dispatch loop,
which would abort delivery of buffered frames for other subscriptions.[feature] NatsClient::state() exposes the current connection state.[feature] SubscriptionQueue::unsubscribe() / close() cancel the queue's own
subscription (convenience for $client->unsubscribe($queue->sid)).[feature] AmpSocketTransport now accepts nats:// DSNs directly (self-normalizing
to tcp://), so the transport is usable standalone, not only via the connection layer.[bugfix] Object Store downloads now use a no-ack (ack_policy=none) consumer. The
read-only download previously used an explicit-ack consumer and acked each chunk; on
a slow link an ack stalling past ack_wait triggered redelivery, which re-hashed a
chunk and produced a spurious digest mismatch.[bugfix] Object Store downloads now fail on a truncated transfer (fewer chunks than
the metadata declares) via a digest-independent completeness check, instead of
silently returning a partial object when the metadata carries no digest.[bugfix] Object Store watch() now tolerates a malformed metadata payload (skips
it) instead of throwing out of the dispatch loop, which would abort delivery of
buffered frames for other subscriptions.[bugfix] listStreams() and listConsumers() now paginate through the JetStream
LIST API (offset/total). Previously they read only the first page, silently
truncating accounts with more than the server page size (256) of streams, or a
stream with more than 256 consumers.[bugfix] PullConsumerIterator infinite mode (setIterations(null)) now keeps
polling past routine empty windows (404/408) instead of terminating on the first
idle gap, so a long-running worker is no longer killed by a quiet period. Terminal
errors (e.g. 409 consumer deleted) still stop the loop, and finite mode is unchanged.[bugfix] The heartbeat watchdog now resets the outstanding-ping counter only when
an actual PONG is received, not on any inbound bytes. Previously a server that
stopped answering PINGs but kept trickling data (or a proxy replaying buffered data)
never tripped maxPingsOut, defeating dead-link detection on busy connections.[bugfix] drain() now waits for the server's PONG (bounded by a deadline) before
closing, instead of bailing on a transient partial/empty read. A larger message
split across socket reads no longer cuts the flush short and drops in-flight
deliveries.[bugfix] SubscriptionQueue::fetchAll() no longer returns early on a transient
empty read (e.g. the heartbeat self-read briefly owning the socket) while its
configured timeout window still has time remaining.[bugfix] recoverConnection() now coalesces concurrent reconnect attempts. A
suspended ping-timer callback resuming while the read path already began recovering
can no longer launch a second reconnect that races on the parser, state, and socket.[bugfix] The protocol parser now rejects malformed frames instead of silently
misframing the stream: non-numeric or negative MSG/HMSG sizes and sids, and HMSG
header bytes exceeding total bytes, raise a ProtocolException. A parse failure now
resyncs past the offending bytes instead of leaving them buffered to re-throw on
every subsequent read, and processIncoming() treats an unparseable stream as a
transport failure (reconnect) rather than letting the exception escape the read loop.[bugfix] The client no longer transmits credentials in plaintext to a TLS-required
server. When the server advertises tls_required (or the option/tls:// scheme
requires TLS) but no TLS materials were configured at connect time, the previous
code performed a no-op "upgrade" and then wrote CONNECT (token/user/pass/JWT/sig)
over the still-plaintext socket, hanging until the handshake deadline. The client
now fails fast with a clear error and never writes CONNECT before TLS is active.[bugfix] A graceful peer close (socket EOF) now triggers reconnect from the read
path. readLine() previously collapsed the EOF null into an empty string, which
the connection treated as "no data this tick", so a server restart / idle-timeout /
load-balancer reap left the client believing it was connected to a dead socket
(never recovering when pings are disabled, recovering only after ~90s otherwise).
Transports now signal EOF via a TransportClosedException, which processIncoming()
and the heartbeat self-read escalate to recoverConnection().[bugfix] SubscriptionQueue::fetch(), next() (with no/zero/negative timeout),
and fetchAll() (with no timeout) no longer block the calling fiber forever on an
idle subject against a real socket. Each now bounds its single poll with a small
cancellation, honoring the documented non-blocking contract.[bugfix] Service::run() now passes its cancellation into processIncoming(),
not only the outer await(). Previously a timed/cancelled run loop left the idle
socket read running detached, wedging the shared connection (every later read
short-circuited and the heartbeat stalled). The read is now torn down on cancel.[bugfix] getStreamMessage() no longer returns an empty payload when the stored
body is the single character 0. The decoded body was passed through a falsy
fallback, so a legitimate "0" payload was replaced with an empty string.[bugfix] getStreamMessage() now preserves headers stored with the message.
Previously the stored header block was dropped and the returned message had no
headers.[bugfix] The heartbeat keep-alive read now delivers any application message it
happens to read while consuming the server reply, instead of leaving it buffered
until the next manual read. This removes a rare case where a reply could be
delayed until its own timeout.[bugfix] Microservice endpoints now default to a shared queue group (q) so
multiple instances of the same service load-balance requests, matching the NATS
micro specification. Previously every instance handled every request, which
duplicated side effects and work across instances. Behavior change: with more
than one instance, each request is now handled by exactly one of them. Pass null
or '' as the endpoint queue group to opt out and fan out to all instances.
(Reclassified from a breaking change to a bugfix because the previous behavior
defeated the framework's scaling model.)[feature] Faster Object Store downloads: object chunks are pulled in bounded
batches rather than one request/reply round-trip per chunk, which significantly
reduces latency for large, multi-chunk objects while keeping peak memory bounded.
Digest verification, in-order delivery, the chunk-by-chunk getToCallback()
contract, and nats CLI interoperability are unchanged.[docs] Corrected the Performance Benchmark Recipe, which previously stalled after
roughly 50 requests because the responder consumed only one transport chunk per
request. The recipe now drives the responder with a single continuous read loop,
and the processIncoming() single-chunk semantics are spelled out.[docs] Corrected the Scheduled Publish example. It now creates the backing stream
with allow_msg_schedules (and allow_msg_ttl when a schedule TTL is used) so the
example runs as written; without those flags the server rejects the publish.[docs] Renamed the "Stream Message Direct Get" section to "Stream Message Get" and
clarified that getStreamMessage() uses the standard stream message get API (not
the JetStream direct-get API) and preserves the stored body and headers.Nothing published for this version
First stable release of idct/php-nats-jetstream-client — an async-first NATS and JetStream client for PHP 8.2+.
First stable release of idct/php-nats-jetstream-client — an async-first NATS and JetStream client for PHP 8.2+.
.creds file parsingSubscriptionQueue with fetch(), next(), fetchAll())no_echo supportmax_payload enforcement and no_responders negotiationDropOldest, DropNewest, Error)maxPingsOut dead-connection detectionINFO updates during connection lifetimeconnectTimeoutMs) and request timeout (requestTimeoutMs)tlsHandshakeFirst TLS optionfetchNext, fetchBatch, ACK / NAK / delayed NAK / TERM / in-progressPullConsumerIterator)@at support via Schedule::at() / Schedule::atTimestamp())RetentionPolicy, StorageBackend, DiscardPolicy, DeliverPolicy, AckPolicy, ReplayPolicyStreamSource)Republish, SubjectTransform)put / get / update / delete / purgewatch with subject filtergetAll / getStatusput / get / delete / list / watchgetToCallback)PING / INFO / STATS / SCHEMA discoveryBasicJsonSchemaValidatorServiceEndpointHandlerInterface), class-stringrun() helper for start + process loop + auto-stopNkeySeedSigner)CredentialsParser::fromFile())declare(strict_types=1))ext-sodium (for NKey/JWT authentication)composer require idct/php-nats-jetstream-client