PHPackages                             zaeem2396/laravel-nats - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Queues & Workers](/categories/queues)
4. /
5. zaeem2396/laravel-nats

ActiveLibrary[Queues & Workers](/categories/queues)

zaeem2396/laravel-nats
======================

Laravel NATS - v2 basis stack (basis-company/nats), subscriber, NatsV2 JetStream helpers, queue driver, legacy JetStream, Artisan commands

v1.6.2(6d ago)6534MITPHPPHP ^8.2CI passing

Since Feb 4Pushed 3w agoCompare

[ Source](https://github.com/zaeem2396/laravel-nats)[ Packagist](https://packagist.org/packages/zaeem2396/laravel-nats)[ RSS](/packages/zaeem2396-laravel-nats/feed)WikiDiscussions main Synced yesterday

READMEChangelog (10)Dependencies (32)Versions (20)Used By (0)

Laravel NATS
============

[](#laravel-nats)

[![Tests](https://github.com/zaeem2396/laravel-nats/actions/workflows/tests.yml/badge.svg)](https://github.com/zaeem2396/laravel-nats/actions/workflows/tests.yml)[![Static Analysis](https://github.com/zaeem2396/laravel-nats/actions/workflows/static-analysis.yml/badge.svg)](https://github.com/zaeem2396/laravel-nats/actions/workflows/static-analysis.yml)[![Code Style](https://github.com/zaeem2396/laravel-nats/actions/workflows/code-style.yml/badge.svg)](https://github.com/zaeem2396/laravel-nats/actions/workflows/code-style.yml)[![Pint](https://github.com/zaeem2396/laravel-nats/actions/workflows/pint.yml/badge.svg)](https://github.com/zaeem2396/laravel-nats/actions/workflows/pint.yml)

Laravel wrapper for NATS with two tracks and an index-first docs experience:

- **Recommended:** `NatsV2` on [`basis-company/nats`](https://github.com/basis-company/nats.php)
- **Supported legacy track:** `Nats` facade + legacy queue/JetStream APIs

Quick Navigation
----------------

[](#quick-navigation)

- [What to use](#what-to-use)
- [Install](#install)
- [Docker setup (local NATS)](#docker-setup-local-nats)
- [5-minute quickstart (natsv2)](#5-minute-quickstart-natsv2)
- [Documentation index](#documentation-index)
- [Queue usage](#queue-usage)
- [Legacy command references](#legacy-command-references)
- [Security and production checks](#security-and-production-checks)
- [Testing and quality checks](#testing-and-quality-checks)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)

What To Use
-----------

[](#what-to-use)

### NatsV2 (recommended)

[](#natsv2-recommended)

Use `NatsV2` for new code:

- `NatsV2::publish` / `NatsV2::subscribe`
- basis-client JetStream helpers
- `nats_basis` queue driver
- optional idempotency, observability, and security controls

### Legacy (still supported)

[](#legacy-still-supported)

Use legacy `Nats` APIs only when you must keep existing workloads unchanged. Migration guide: [`docs/v2/MIGRATION.md`](docs/v2/MIGRATION.md).

Install
-------

[](#install)

Requirements:

- PHP 8.2+
- Laravel 10.x / 11.x / 12.x / 13.x
- NATS Server 2.x

Laravel 13 applications require PHP 8.3+; the package minimum remains PHP 8.2 for Laravel 10-12.

```
composer require zaeem2396/laravel-nats
php artisan vendor:publish --tag=nats-config
```

Version map:

- **1.3.0+**: `NatsV2` publish/subscribe foundation
- **1.4.0+**: basis JetStream + `nats_basis` queue + idempotency + observability
- **1.5.0+**: config validation, TLS production guard, optional ACL
- **1.5.1**: documentation refresh (navigation + cross-links)
- **1.5.2**: README/docs index layout; Docker local NATS section; [`docs/INDEX.md`](docs/INDEX.md)
- **1.6.0+**: v2.7 header helpers, optional W3C trace context, subject-prefix connection selection, outbox recipe; Laravel 13 supported in package dev constraints; CI tests PHP 8.5 on Laravel 11–13
- **1.6.1**: expanded Pest coverage, Pint CI workflow, `composer ci` script; no public API changes
- **1.6.2**: connection reconnect helpers and transport cleanup for legacy and basis clients

Roadmap: [`docs/ROADMAP.md`](docs/ROADMAP.md) · Changelog: [`CHANGELOG.md`](CHANGELOG.md)

Docker Setup (Local NATS)
-------------------------

[](#docker-setup-local-nats)

### Start NATS with project compose file

[](#start-nats-with-project-compose-file)

```
docker compose up -d
```

This starts a local NATS server using the repository's `docker-compose.yml`.

### Verify container is running

[](#verify-container-is-running)

```
docker compose ps
```

### Match your `.env` to local Docker defaults

[](#match-your-env-to-local-docker-defaults)

```
NATS_HOST=127.0.0.1
NATS_PORT=4222
```

### Stop services when done

[](#stop-services-when-done)

```
docker compose down
```

5-Minute Quickstart (NatsV2)
----------------------------

[](#5-minute-quickstart-natsv2)

### 1) Configure env

[](#1-configure-env)

```
NATS_HOST=127.0.0.1
NATS_PORT=4222
NATS_USER=
NATS_PASS=
NATS_TOKEN=
NATS_BASIS_VALIDATE_CONFIG=false
NATS_TLS_REQUIRE_IN_PRODUCTION=false
```

### 2) Publish

[](#2-publish)

```
use LaravelNats\Laravel\Facades\NatsV2;

NatsV2::publish('orders.created', ['order_id' => 123], ['X-Request-Id' => 'req-1']);
```

### 3) Subscribe

[](#3-subscribe)

```
use LaravelNats\Laravel\Facades\NatsV2;
use LaravelNats\Subscriber\InboundMessage;

NatsV2::subscribe('orders.created', function (InboundMessage $message): void {
    $payload = $message->envelopePayload();
    logger()->info('Order received', (array) $payload);
});

while (true) {
    NatsV2::process(null, 1.0);
}
```

Documentation Index
-------------------

[](#documentation-index)

Prefer this canonical map for quick navigation: [`docs/INDEX.md`](docs/INDEX.md).

### By use case

[](#by-use-case)

If you want to...Go herePublish/subscribe on v2 quickly[`docs/v2/GUIDE.md`](docs/v2/GUIDE.md)Build long-running consumers[`docs/v2/SUBSCRIBER.md`](docs/v2/SUBSCRIBER.md)Run queue workers on basis client[`docs/v2/QUEUE.md`](docs/v2/QUEUE.md)Work with JetStream streams/consumers[`docs/v2/JETSTREAM.md`](docs/v2/JETSTREAM.md)Propagate trace headers or route by subject[`docs/v2/TRACE_CONTEXT.md`](docs/v2/TRACE_CONTEXT.md), [`docs/v2/CONNECTION_SELECTION.md`](docs/v2/CONNECTION_SELECTION.md)Add a transactional outbox around publishes[`docs/v2/OUTBOX.md`](docs/v2/OUTBOX.md)Harden config and subject access[`docs/v2/SECURITY.md`](docs/v2/SECURITY.md)Move from legacy APIs to v2[`docs/v2/MIGRATION.md`](docs/v2/MIGRATION.md)### Start here

[](#start-here)

- [`docs/v2/README.md`](docs/v2/README.md)
- [`docs/v2/GUIDE.md`](docs/v2/GUIDE.md)
- [`docs/v2/FAQ.md`](docs/v2/FAQ.md)

### Core feature guides

[](#core-feature-guides)

- Subscriber: [`docs/v2/SUBSCRIBER.md`](docs/v2/SUBSCRIBER.md)
- JetStream (v2): [`docs/v2/JETSTREAM.md`](docs/v2/JETSTREAM.md)
- Queue (`nats_basis`): [`docs/v2/QUEUE.md`](docs/v2/QUEUE.md)
- Trace context: [`docs/v2/TRACE_CONTEXT.md`](docs/v2/TRACE_CONTEXT.md)
- Connection selection: [`docs/v2/CONNECTION_SELECTION.md`](docs/v2/CONNECTION_SELECTION.md)
- Outbox recipe: [`docs/v2/OUTBOX.md`](docs/v2/OUTBOX.md)
- Migration: [`docs/v2/MIGRATION.md`](docs/v2/MIGRATION.md)

### Production and operations

[](#production-and-operations)

- Security + ACL: [`docs/v2/SECURITY.md`](docs/v2/SECURITY.md)
- Observability: [`docs/v2/OBSERVABILITY.md`](docs/v2/OBSERVABILITY.md)
- Correlation headers: [`docs/v2/CORRELATION.md`](docs/v2/CORRELATION.md)
- Idempotency: [`docs/v2/IDEMPOTENCY.md`](docs/v2/IDEMPOTENCY.md)
- Client protocol features: [`docs/v2/CLIENT_FEATURES.md`](docs/v2/CLIENT_FEATURES.md)

### Examples

[](#examples)

- Example index: [`docs/v2/examples/README.md`](docs/v2/examples/README.md)

Queue Usage
-----------

[](#queue-usage)

Two queue drivers are available:

- **`nats`**: legacy driver on `LaravelNats\Core\Client`
- **`nats_basis`**: recommended driver on `Basis\Nats\Client`

Use with Laravel worker:

```
php artisan queue:work nats_basis --queue=default --tries=3
```

Queue guide: [`docs/v2/QUEUE.md`](docs/v2/QUEUE.md)

Legacy Command References
-------------------------

[](#legacy-command-references)

For teams still using legacy stack workflows:

- Queue and consumer runtime references: check [`docs/v2/QUEUE.md`](docs/v2/QUEUE.md) and [`docs/v2/MIGRATION.md`](docs/v2/MIGRATION.md) for current behavior and migration-safe usage.
- Legacy JetStream stream/consumer workflows remain available while migration is in progress.
- Plan migration paths with [`docs/v2/MIGRATION.md`](docs/v2/MIGRATION.md) and track releases via [`docs/ROADMAP.md`](docs/ROADMAP.md).

Security And Production Checks
------------------------------

[](#security-and-production-checks)

For hardened environments (1.5.0+):

- optional boot validation: `NATS_BASIS_VALIDATE_CONFIG=true`
- optional TLS requirement in production: `NATS_TLS_REQUIRE_IN_PRODUCTION=true`
- optional publish/subscribe ACL: `NATS_ACL_*`
- explicit validator command: `php artisan nats:v2:config:validate`

Full details: [`docs/v2/SECURITY.md`](docs/v2/SECURITY.md)

Testing And Quality Checks
--------------------------

[](#testing-and-quality-checks)

```
# Optional local NATS (integration tests)
docker compose up -d

# Full local CI gate (Pest + PHPStan + Pint + PHP-CS-Fixer)
composer ci

# Individual checks
composer test
composer analyse
composer pint:check
composer format:check
composer test:coverage   # optional; requires PCOV or Xdebug
```

For release prep, run `composer ci` and ensure `CHANGELOG.md` reflects the release scope.

Troubleshooting
---------------

[](#troubleshooting)

### Connection refused

[](#connection-refused)

Start NATS locally:

```
docker compose up -d
```

### Authorization violation

[](#authorization-violation)

Verify `.env` credentials and server auth mode (`NATS_USER`/`NATS_PASS` vs `NATS_TOKEN`).

### Production TLS/config errors

[](#production-tlsconfig-errors)

If you get `NatsConfigurationException`, validate your `nats_basis` connection rows:

```
php artisan nats:v2:config:validate
```

Then confirm TLS values in [`docs/v2/SECURITY.md`](docs/v2/SECURITY.md).

API Stability
-------------

[](#api-stability)

Public Laravel-facing APIs are stable under semver. Internal implementation classes (especially under core internals) may evolve.

See release notes: [`CHANGELOG.md`](CHANGELOG.md)

Contributing
------------

[](#contributing)

Before opening a PR, run:

```
composer ci
```

License
-------

[](#license)

MIT. See [`LICENSE`](LICENSE).

###  Health Score

49

—

FairBetter than 94% of packages

Maintenance96

Actively maintained with recent releases

Popularity23

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity56

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~13 days

Recently: every ~19 days

Total

12

Last Release

6d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/31367343?v=4)[Zaeem Ansari](/maintainers/zaeem2396)[@zaeem2396](https://github.com/zaeem2396)

---

Top Contributors

[![zaeem2396](https://avatars.githubusercontent.com/u/31367343?v=4)](https://github.com/zaeem2396 "zaeem2396 (723 commits)")

---

Tags

laravelqueuemessagingpub-submicroservicesjetstreamnatsbasis-nats

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/zaeem2396-laravel-nats/health.svg)

```
[![Health](https://phpackages.com/badges/zaeem2396-laravel-nats/health.svg)](https://phpackages.com/packages/zaeem2396-laravel-nats)
```

###  Alternatives

[basis-company/nats

nats jetstream client for php

206455.7k37](/packages/basis-company-nats)[nuwber/rabbitevents

The Nuwber RabbitEvents package

122529.7k4](/packages/nuwber-rabbitevents)[enqueue/laravel-queue

Laravel Queue Extension. It uses Enqueue transports

240490.0k2](/packages/enqueue-laravel-queue)[goodway/laravel-nats

Nats jetstream queue driver with client for Laravel

345.9k](/packages/goodway-laravel-nats)[iamfarhad/laravel-rabbitmq

Native ext-amqp RabbitMQ queue driver for Laravel production workloads with connection pooling, publisher confirms, Horizon support, Octane support, quorum queues, and high-performance workers

3319.5k](/packages/iamfarhad-laravel-rabbitmq)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)