Lenats Laravel Package

Getting Started

LeNats is archived and marked DEPRECATED — treat it as a reference implementation for legacy Symfony apps already on NATS Streaming (STAN), not a greenfield choice. NATS Streaming itself was superseded by JetStream, the bundle has 0 dependents, and the GPL-3.0 license is a real constraint for proprietary apps. Read it for pattern ideas before you composer require.

If you're maintaining an existing install:

• composer require lebrains/lenats (or restore from your composer.lock; archived packages tend to drop off Packagist eventually).
• Register the bundle in config/bundles.php.
• Add a config block under the bundle's key (check DependencyInjection/Configuration.php — likely lenats: or le_nats:) with cluster ID, client ID, and NATS URL, and point it at a running nats-streaming-server (the nats-streaming Docker image works).
• First use case: replace an in-process Symfony event with a NATS subject so another service can consume it — publish order.created from your service after the DB commit, consume it in a separate Symfony app.

Look first at the bundle's Service//Publisher/ classes and any examples in tests — those are the only reliable docs.

Implementation Patterns

• Publish after commit. Inject the publisher and call it after the transaction commits; never inside a transaction you might roll back.
• Consumers are long-running processes. Write a console command that subscribes and dispatches into your domain, then run it under Supervisor/Systemd. Not php-fpm, not a web request.
• Serialize explicitly. JSON DTOs with a type/event header and a version field; consumers route on the header without parsing the payload twice.
• Don't conflate the two "events." Symfony's EventDispatcher and NATS subjects share a word and nothing else. Map NATS messages to App\Event\* objects at the boundary, then use normal listeners.
• Use durable subscriptions + queue groups for competing consumers; use a plain durable named subscription for fan-out per service.
• Bridge to Symfony Messenger: have the NATS consumer re-dispatch via MessageBusInterface::dispatch() so retries/transports stay in one place.

Gotchas and Tips

• The whole stack is dead. NATS Streaming is EOL in favor of JetStream, the bundle is archived, and you will get no fixes for PHP 8.x deprecations or security issues. Budget a migration from day one.
• GPL-3.0 is copyleft. Linking it into a proprietary codebase is a legal decision, not just a technical one.
• PHP is shared-nothing: a subscription lives only as long as your worker. Ack-wait, max-in-flight, and redelivery settings on the STAN server are your real reliability controls — at-least-once is not free.
• Silent encoding failures with DateTime, enums, and binary blobs. Pick explicit formats and test round-trips.
• Config caching: run bin/console cache:clear after editing the bundle config; DI compiler passes rarely invalidate on their own.
• Debug at the server, not the bundle. nats-streaming-server logs and the monitoring port tell you more than the PHP layer; capture the raw message before mapping it to a domain event.
• Extension point: wrap the bundle's publisher behind your own interface. The day you swap in basis-company/nats against JetStream, you change one class instead of every caller.
• For new code, evaluate basis-company/nats.php (JetStream) or Symfony Messenger with a community NATS transport — both maintained.