Weave Code
Symfony Nats Messenger Laravel Package
idct/symfony-nats-messenger
A Symfony Messenger transport for NATS that lets PHP applications publish and consume messages over NATS subjects with native Symfony integration, configuration, and worker support for event-driven architectures.
Symfony NATS (JetStream) Messenger Bridge
Frequently asked questions about Symfony Nats Messenger
- How do I install idct/symfony-nats-messenger?
- Install it with Composer using composer require idct/symfony-nats-messenger. In Symfony, the shipped IDCTNatsMessengerBundle is auto-registered by Flex so the transport factory and serializer are available for Messenger configuration. In Laravel the bundle is inert, so you must register the transport factory, serializer, and Messenger bus wiring manually in a service provider.
- Is idct/symfony-nats-messenger compatible with Laravel?
- Not natively. It is a Symfony Messenger transport, not an Illuminate\Queue driver, so Laravel's queue system, Horizon, failed_jobs, and queue:retry do not manage it. You can use it in Laravel only by manually registering the transport factory and igbinary serializer and constructing a MessageBus outside Laravel's container conventions.
- What NATS DSN formats does the transport support?
- The transport parses nats-jetstream:// DSNs and nats-jetstream+tls:// DSNs for TLS. It supports TLS/mTLS, JWT and NKey authentication, stream and consumer provisioning, retention and replica settings, batching, DelayStamp scheduling, and Nats-Msg-Id deduplication. Configure the DSN in Symfony Messenger's transport configuration and route messages to NATS subjects.
- How do I run a NATS consumer worker?
- In Symfony, run messenger:consume as usual and let Messenger's worker handle the transport. In Laravel there is no queue:work equivalent for this transport, so you must write and supervise an artisan command that owns the Messenger Worker. That command needs to handle keepalive, graceful termination, memory limits, and restarts, because Laravel does not provide Horizon or failed_jobs for this path.
- Does it support retries and failure transports?
- Yes, the transport is designed to integrate with Symfony Messenger retry and failure transport workflows and honors Messenger envelopes and middleware. Inside Symfony that gives you the usual Messenger retry strategy and failure transport behavior. In Laravel, those workflows are not connected to Laravel's failed_jobs table or queue:retry command, so retry and failure observability remain your responsibility.
- Can non-PHP services consume messages published by this package?
- Not with the default serializer. IgbinarySerializer falls back to PhpSerializer, and both wrap a Symfony Envelope, so the wire format is PHP-shaped and requires replicating the envelope contract in Go, Node, or other consumers. For polyglot messaging you need a custom serializer extending AbstractEnveloperSerializer plus a matching contract on every non-PHP consumer.
- Does idct/symfony-nats-messenger work with Laravel Octane?
- Treat Octane support as unproven. The underlying idct/php-nats-jetstream-client is amphp-coroutine based, and running it under Swoole or RoadRunner means sharing an event loop that Octane already owns. The v5.7.0 reconnect mode adds more long-lived loop state and reconnect bookkeeping, which raises rather than lowers the bar for proving safe Octane coexistence.
- How does version 5.7.0 handle NATS broker restarts?
- With reconnect enabled, a worker now polls through a broker outage shorter than one recovery cycle instead of throwing and exiting. A pull that the server ends for its own shutdown or a leadership change returns an empty batch rather than a missing-consumer error. That turns a common class of broker-restart incidents into a worker that waits, though you still need your own supervised worker command in Laravel.
- How is the package tested and maintained?
- Version 5.7.0 reports 669 unit tests, 99.78 percent statement coverage, and 1008 of 1040 mutants killed, with 32 survivors documented. The repository also describes Behat functional scenarios against a real NATS server and reconnect tests against a scripted connection. The main technical risk is maturity and ownership rather than code quality, especially for Laravel-specific operational seams.
- What alternatives should I evaluate for NATS messaging in Laravel?
- If your application is primarily Laravel, compare against native Illuminate\Queue drivers such as Redis, SQS, or database backed by Horizon, or a custom Laravel queue driver for NATS. Choose idct/symfony-nats-messenger when NATS JetStream is already the cross-service backbone and you accept running a Symfony Messenger subsystem alongside Laravel's queue subsystem. If you need a single retry, failure, and observability model, the extra integration effort may outweigh the transport's benefits.
Weaver
How can I help you explore Laravel packages today?