Nats Laravel Package

Product Decisions This Supports

• Build vs. buy for async messaging: Writing a NATS protocol client (handshake, reconnects with constant/linear/exponential backoff, JetStream consumer state, acks, TLS, NKeys/JWT auth) is multi-week engineering. MIT-licensed and dependency-light, so the real "buy" cost is an integration sprint, not a license negotiation.
• Monolith → services decomposition: The request/reply and service() endpoint APIs give PHP teams a first-class way to expose Laravel domain logic as subject-addressable endpoints (v1.posts.*) without standing up HTTP gateways between internal services.
• Event-driven / queue architecture choice: JetStream streams with WORK_QUEUE retention plus ack()/nack(timeout) and batching (setBatching, setIterations, fetchAll) map directly onto work-queue semantics — a credible alternative to Redis/SQS for durable at-least-once delivery, particularly if NATS is already in the infra footprint.
• Roadmap for operational primitives: KV Storage (put/update with revision guards, getAll, purge) covers feature flags, config distribution, and lightweight distributed locks — features that otherwise become a separate service or a schema on top of Redis.
• Cross-language platform bets: If Go/Node/Python services already speak NATS, adopting the PHP client is the cheapest path to making Laravel a peer participant in that fabric rather than an HTTP-bound outlier.
• Throughput-sensitive decisions: The README's benchmark (~370k publish / ~360k receive rps in non-verbose mode) is a client-protocol ceiling, not an application ceiling — useful for ruling out the client as a bottleneck, not for capacity planning.

When to Consider This Package

Adopt when:

• NATS (and ideally JetStream) is already operated by the platform team — this is a client, not a broker; adopting it without existing NATS ops expertise imports an operational burden.
• You need durable consumers with explicit ack/nack retry semantics, not just fire-and-forget pub/sub.
• Your services are polyglot and NATS is the chosen substrate; a PHP-native client keeps Laravel inside the fabric.
• You need JWT/NKey or mTLS auth — TLS 1.2 auto-upgrade, tlsCaFile/tlsCertFile/tlsKeyFile, and CredentialsParser::fromFile() are all documented, which is a meaningful signal for production use.
• Your team is on PHP 8+ with Composer and libsodium (or accepts sodium_compat), and can own a thin Laravel wrapper internally.

Look elsewhere when:

• You want Laravel-native ergonomics out of the box. This is a framework-agnostic PHP client — there is no service provider, facade, config publish, queue driver, or Horizon-equivalent monitoring. Budget roughly a sprint for a wrapper (provider, config, connection lifecycle, health check, reconnect telemetry).
• You need a drop-in Laravel queue driver for dispatch()/ShouldQueue — evaluate dedicated queue-driver packages or stay on Redis/SQS.
• You require vendor-backed support, an SLA, or a security-response commitment. 0 Packagist dependents and a single-organization maintenance model mean ecosystem validation and bus-factor risk are unproven; treat MIT licensing plus a small, readable codebase as the mitigation (forkable, not vendor-locked).
• You need full JetStream parity with official clients (mirrors/sources, stream republish transforms, KV watchers, exactly-once publish semantics). Feature coverage is documented only via README examples — verify against your specific feature list before committing; absence of docs is not proof of absence, but it is a diligence item.
• High-volume synchronous request/reply inside a PHP-FPM request cycle — blocking dispatch() will burn a worker; this fits long-running CLI workers, not web requests.

How to Pitch It (Stakeholders)

To executives: This is a low-cost, zero-license-fee way to make our Laravel services first-class participants in an event-driven architecture alongside our other language runtimes. It ships everything we'd otherwise build ourselves — connection resilience, TLS/mTLS, JWT auth, durable JetStream consumers with retry semantics, a key-value store for feature flags and config, and a microservice endpoint layer — under an MIT license with no vendor lock-in. The trade-off is ecosystem maturity: negligible third-party adoption and a single maintainer, so we treat it as a forkable dependency we pin and wrap, not a strategic vendor. Recommended decision: adopt behind an internal abstraction for one bounded use case (durable work queue or internal service endpoint), with a two-week integration spike and a security/dependency review.

To engineering: You get a protocol implementation you don't have to write, with exponential-backoff reconnects, TLS and NKey/JWT credentials, request/reply (request/dispatch), JetStream streams and consumers (durable and ephemeral), ack/nack with timeout, batching over fetchAll, and KV with revision-guarded updates. Costs: you own the Laravel glue (service provider, config, worker lifecycle, observability), you pin the version and review upgrades manually given low downstream usage, and you validate JetStream feature coverage against our roadmap before we design around it. Non-negotiable: run consumers as long-lived CLI workers, make handlers idempotent, and never block inside a web request.