README

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

• Recommended: NatsV2 on basis-company/nats
• Supported legacy track: Nats facade + legacy queue/JetStream APIs

Quick Navigation

• What to use
• Install
• Docker setup (local NATS)
• 5-minute quickstart (natsv2)
• Documentation index
• Queue usage
• Legacy command references
• Security and production checks
• Testing and quality checks
• Troubleshooting
• Contributing

What To Use

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)

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

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
• 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 · Changelog: CHANGELOG.md

Docker Setup (Local NATS)

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

docker compose ps

Match your .env to local Docker defaults

NATS_HOST=127.0.0.1
NATS_PORT=4222

Stop services when done

docker compose down

5-Minute Quickstart (NatsV2)

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

use LaravelNats\Laravel\Facades\NatsV2;

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

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

Prefer this canonical map for quick navigation: docs/INDEX.md.

By use case

Start here

• docs/v2/README.md
• docs/v2/GUIDE.md
• docs/v2/FAQ.md

Core feature guides

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

Production and operations

• Security + ACL: docs/v2/SECURITY.md
• Observability: docs/v2/OBSERVABILITY.md
• Correlation headers: docs/v2/CORRELATION.md
• Idempotency: docs/v2/IDEMPOTENCY.md
• Client protocol features: docs/v2/CLIENT_FEATURES.md

Examples

• Example index: docs/v2/examples/README.md

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

Legacy Command References

For teams still using legacy stack workflows:

• Queue and consumer runtime references: check docs/v2/QUEUE.md and 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 and track releases via docs/ROADMAP.md.

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

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

Connection refused

Start NATS locally:

docker compose up -d

Authorization violation

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

Production TLS/config 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.

API Stability

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

See release notes: CHANGELOG.md

Contributing

Before opening a PR, run:

composer ci

License

MIT. See LICENSE.