PHPackages                             mperusso/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. mperusso/nats

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

mperusso/nats
=============

nats jetstream client for php compatible with php 7.3

0.24.2(1y ago)212.7k↓27.5%mitPHPPHP >=7.3

Since Dec 14Pushed 1y agoCompare

[ Source](https://github.com/mperusso/nats.php)[ Packagist](https://packagist.org/packages/mperusso/nats)[ RSS](/packages/mperusso-nats/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (4)Dependencies (4)Versions (67)Used By (0)

Nats client for php
===================

[](#nats-client-for-php)

[![License](https://camo.githubusercontent.com/6455a3142f01370a4f2fe5c67258d325cbd4f309479648d2e172438405baa1c8/68747470733a2f2f706f7365722e707567782e6f72672f62617369732d636f6d70616e792f6e6174732f6c6963656e73652e706e67)](https://packagist.org/packages/basis-company/nats)[![Testing](https://github.com/basis-company/nats.php/actions/workflows/tests.yml/badge.svg)](https://github.com/basis-company/nats.php/actions/workflows/tests.yml)[![Latest Version](https://camo.githubusercontent.com/2e00b7aef4f0a130938f4a544ff7c4014ba770edfd18c7a1d9423772ed42aab3/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f72656c656173652f62617369732d636f6d70616e792f6e6174732e7068702e737667)](https://github.com/basis-company/nats.php/releases)[![Total Downloads](https://camo.githubusercontent.com/f4d6e2c09b2382655580ad7898a47e347bffdbedd723e3652229a5bd434577b7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f62617369732d636f6d70616e792f6e6174732e737667)](https://packagist.org/packages/basis-company/nats)

Feel free to contribute or give any feedback.

- [Installation](#installation)
- [Connection](#connection)
- [Publish Subscribe](#publish-subscribe)
- [Request Response](#request-response)
- [JetStream Api Usage](#jetstream-api-usage)
- [Key Value Storage](#key-value-storage)
- [Using NKeys with JWT](#using-nkeys-with-jwt)
- [Performance](#performance)
- [Configuration Options](#configuration-options)

Installation
------------

[](#installation)

The recommended way to install the library is through [Composer](http://getcomposer.org):

```
$ composer require basis-company/nats
```

The NKeys functionality requires Ed25519, which is provided in `libsodium` extension or `sodium_compat` package.

Connection
----------

[](#connection)

```
use Basis\Nats\Client;
use Basis\Nats\Configuration;

// this is default options, you can override anyone
$configuration = new Configuration([
    'host' => 'localhost',
    'jwt' => null,
    'lang' => 'php',
    'pass' => null,
    'pedantic' => false,
    'port' => 4222,
    'reconnect' => true,
    'timeout' => 1,
    'token' => null,
    'user' => null,
    'nkey' => null,
    'verbose' => false,
    'version' => 'dev',
]);

// default delay mode is constant - first retry be in 1ms, second in 1ms, third in 1ms
$configuration->setDelay(0.001);

// linear delay mode - first retry be in 1ms, second in 2ms, third in 3ms, fourth in 4ms, etc...
$configuration->setDelay(0.001, Configuration::DELAY_LINEAR);

// exponential delay mode - first retry be in 10ms, second in 100ms, third in 1s, fourth if 10 seconds, etc...
$configuration->setDelay(0.01, Configuration::DELAY_EXPONENTIAL);

$client = new Client($configuration);
$client->ping(); // true
```

### Connecting to a cluster with TLS enabled

[](#connecting-to-a-cluster-with-tls-enabled)

Typically, when connecting to a cluster with TLS enabled the connection settings do not change. The client lib will automatically switch over to TLS 1.2. However, if you're using a self-signed certificate you may have to point to your local CA file using the tlsCaFile setting.

When connecting to a nats cluster that requires the client to provide TLS certificates use the tlsCertFile and tlsKeyFile to point at your local TLS certificate and private key file.

Nats Server documentation for:

- [Enabling TLS](https://docs.nats.io/running-a-nats-service/configuration/securing_nats/tls)
- [Enabling TLS Authentication](https://docs.nats.io/running-a-nats-service/configuration/securing_nats/auth_intro/tls_mutual_auth)
- [Creating self-signed TLS certs for Testing](https://docs.nats.io/running-a-nats-service/configuration/securing_nats/tls#self-signed-certificates-for-testing)

Connection settings when connecting to a nats server that has TLS and TLS Client verify enabled.

```
use Basis\Nats\Client;
use Basis\Nats\Configuration;

// this is default options, you can override anyone
$configuration = new Configuration([
    'host' => 'localhost',
    'jwt' => null,
    'lang' => 'php',
    'pass' => null,
    'pedantic' => false,
    'port' => 4222,
    'reconnect' => true,
    'timeout' => 1,
    'token' => null,
    'user' => null,
    'nkey' => null,
    'verbose' => false,
    'version' => 'dev',
    'tlsCertFile' => "./certs/client-cert.pem",
    'tlsKeyFile'  => "./certs/client-key.pem",
    'tlsCaFile'  => "./certs/client-key.pem",
]);

$configuration->setDelay(0.001);

$client = new Client($configuration);
$client->ping(); // true
```

Publish Subscribe
-----------------

[](#publish-subscribe)

```
// queue usage example
$queue = $client->subscribe('test_subject');

$client->publish('test_subject', 'hello');
$client->publish('test_subject', 'world');

// optional message fetch
// if there are no updates null will be returned
$message1 = $queue->fetch();
echo $message1->payload . PHP_EOL; // hello

// locks untill message is fetched from subject
// to limit lock timeout, pass optional timeout value
$message2 = $queue->next();
echo $message2->payload . PHP_EOL; // world

$client->publish('test_subject', 'hello');
$client->publish('test_subject', 'batching');

// batch message fetching, limit argument is optional
$messages = $queue->fetchAll(10);
echo count($messages);

// fetch all messages that are published to the subject client connection
// queue will stop message fetching when another subscription receives a message
// in advance you can time limit batch fetching
$queue->setTimeout(1); // limit to 1 second
$messages = $queue->fetchAll();

// reset subscription
$client->unsubscribe($queue);

// callback hell example
$client->subscribe('hello', function ($message) {
    var_dump('got message', $message); // tester
});

$client->publish('hello', 'tester');
$client->process();

// if you want to append some headers, construct payload manually
use Basis\Nats\Message\Payload;

$payload = new Payload('tester', [
    'Nats-Msg-Id' => 'payload-example'
]);

$client->publish('hello', $payload);
```

Request Response
----------------

[](#request-response)

There is a simple wrapper over publish and feedback processing, so payload can be constructed manually same way.

```
$client->subscribe('hello.request', function ($name) {
    return "Hello, " . $name;
});

// async interaction
$client->request('hello.request', 'Nekufa1', function ($response) {
    var_dump($response); // Hello, Nekufa1
});

$client->process(); // process request

// sync interaction (block until response get back)
$client->dispatch('hello.request', 'Nekufa2'); // Hello, Nekufa2
```

JetStream Api Usage
-------------------

[](#jetstream-api-usage)

```
use Basis\Nats\Stream\RetentionPolicy;
use Basis\Nats\Stream\StorageBackend;

$accountInfo = $client->getApi()->getInfo(); // account_info_response object

$stream = $client->getApi()->getStream('mailer');

$stream->getConfiguration()
    ->setRetentionPolicy(RetentionPolicy::WORK_QUEUE)
    ->setStorageBackend(StorageBackend::MEMORY)
    ->setSubjects(['mailer.greet', 'mailer.bye']);

// stream is created with given configuration
$stream->create();

// and put some tasks so workers would be doing something
$stream->put('mailer.greet', 'nekufa@gmail.com');
$stream->put('mailer.bye', 'nekufa@gmail.com');

var_dump($stream->info()); // can stream info

// this should be set in your worker
$greeter = $stream->getConsumer('greeter');
$greeter->getConfiguration()->setSubjectFilter('mailer.greet');
// consumer would be created would on first handle call
$greeter->handle(function ($address) {
    mail($address, "Hi there!");
});

var_dump($greeter->info()); // can consumer info

$goodbyer = $stream->getConsumer('goodbyer');
$goodbyer->getConfiguration()->setSubjectFilter('mailer.bye');
$goodbyer->create(); // create consumer if you don't want to handle anything right now
$goodbyer->handle(function ($address) {
    mail($address, "See you later");
});

// you can configure batching and iteration count using chain api
$goodbyer
    ->setBatching(2) // how many messages would be requested from nats stream
    ->setIterations(3) // how many times message request should be sent
    ->handle(function () {
        // if you need to break on next iteration simply call interrupt method
        // batch will be processed to the end and the handling would be stopped
        // $goodbyer->interrupt();
    });

// consumer can be used via queue interface
$queue = $goodbyer->getQueue();
while ($message = $queue->next()) {
    if (rand(1, 10) % 2 == 0) {
        mail($message->payload, "See you later");
        $message->ack();
    } else {
        // not ack with 1 second timeout
        $message->nack(1);
    }
    // stop processing
    if (rand(1, 10) % 2 == 10) {
        // don't forget to unsubscribe
        $client->unsubscribe($queue);
        break;
    }
}

// use fetchAll method to batch process messages
// let's set batch size to 50
$queue = $goodbyer->setBatching(50)->create()->getQueue();

// fetching 100 messages provides 2 stream requests
// limit message fetching to 1 second
// it means no more that 100 messages would be fetched
$messages = $queue->setTimeout(1)->fetchAll(100);

$recipients = [];
foreach ($messages as $message) {
    $recipients[] = (string) $message->payload;
}

mail_to_all($recipients, "See you later");

// ack all messages
foreach ($messages as $message) {
    $message->ack();
}

// you also can create ephemeral consumer
// the only thing that ephemeral consumer is created as soon as object is created
// you have to create full consumer configuration first
use Basis\Nats\Consumer\Configuration as ConsumerConfiguration;
use Basis\Nats\Consumer\DeliverPolicy;

$configuration = (new ConsumerConfiguration($stream->getName()))
    ->setDeliverPolicy(DeliverPolicy::NEW)
    ->setSubjectFilter('mailer.greet');

$ephemeralConsumer = $stream->createEphemeralConsumer($configuration);

// now you can use ephemeral consumer in the same way as durable consumer
$ephemeralConsumer->handle(function ($address) {
    mail($address, "Hi there!");
});

// the only difference - you don't have to remove it manually, it will be deleted by NATS when socket connection is closed
// be aware that NATS will not remove that consumer immediately, process can take few seconds
var_dump(
    $ephemeralConsumer->getName(),
    $ephemeralConsumer->info(),
);

// if you need to append some headers, construct payload manually
use Basis\Nats\Message\Payload;

$payload = new Payload('nekufa@gmail.com', [
    'Nats-Msg-Id' => 'single-send'
]);

$stream->put('mailer.bye', $payload);
```

Key Value Storage
-----------------

[](#key-value-storage)

```
$bucket = $client->getApi()->getBucket('bucket_name');

// basics
$bucket->put('username', 'nekufa');
echo $bucket->get('username'); // nekufa

// safe update (given revision)
$entry = $bucket->getEntry('username');
echo $entry->value; // nekufa
$bucket->update('username', 'bazyaba', $entry->revision);

// delete value
$bucket->delete('username');

// purge value history
$bucket->purge('username');

// get bucket stats
var_dump($bucket->getStatus());

// in advance, you can fetch all bucket values
$bucket->update('email', 'nekufa@gmail.com');
var_dump($bucket->getAll()); // ['email' => 'nekufa@gmail.com', 'username' => 'nekufa']
```

Using NKeys with JWT
--------------------

[](#using-nkeys-with-jwt)

To use NKeys with JWT, simply provide them in the `Configuration` options as `jwt` and `nkey`. You can also provide a credentials file with `CredentialsParser`

```
use Basis\Nats\Client;
use Basis\Nats\Configuration;
use Basis\Nats\NKeys\CredentialsParser;

$configuration = new Configuration(
    [
        'host' => 'localhost',
        'port' => 4222
    ],
    CredentialsParser::fromFile($credentialPath)
);

$client = new Client($configuration);
```

Performance
-----------

[](#performance)

Testing on AMD Ryzen 5 3600X with nats running in docker gives about 400k rps for publish and 330k rps for receive in non-verbose mode.

You can run tests on your environment.

```
 % wget https://getcomposer.org/download/latest-stable/composer.phar
...
Saving to: ‘composer.phar’

 % ./composer.phar install
Installing dependencies from lock file (including require-dev)
...

 % export NATS_HOST=0.0.0.0
 % export NATS_PORT=4222
 % export NATS_CLIENT_LOG=1
 % composer run perf-test
PHPUnit 9.5.28 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.3.3-1+ubuntu22.04.1+deb.sury.org+1
Configuration: /home/nekufa/software/github/nats.php/phpunit.xml.dist
Warning:       No code coverage driver available

[2024-03-11T17:06:30.907277+00:00] PerformanceTest.testPerformance.DEBUG: send CONNECT {"headers":true,"pedantic":false,"verbose":false,"lang":"php","version":"dev"}  [] []
[2024-03-11T17:06:30.907312+00:00] PerformanceTest.testPerformance.INFO: start performance test [] []
[2024-03-11T17:06:32.135674+00:00] PerformanceTest.testPerformance.INFO: publishing {"rps":407072.0,"length":500000,"time":1.228281021118164} []
[2024-03-11T17:06:33.412134+00:00] PerformanceTest.testPerformance.INFO: processing {"rps":391723.0,"length":500000,"time":1.2764089107513428} []

 % export NATS_CLIENT_VERBOSE=1
 % composer run perf-test
PHPUnit 9.5.28 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.3.3-1+ubuntu22.04.1+deb.sury.org+1
Configuration: /home/nekufa/software/github/nats.php/phpunit.xml.dist
Warning:       No code coverage driver available

[2024-03-11T17:07:12.829135+00:00] PerformanceTest.testPerformance.DEBUG: send CONNECT {"headers":true,"pedantic":false,"verbose":true,"lang":"php","version":"dev"}  [] []
[2024-03-11T17:07:12.829172+00:00] PerformanceTest.testPerformance.INFO: start performance test [] []
[2024-03-11T17:07:14.069321+00:00] PerformanceTest.testPerformance.INFO: publishing {"rps":403207.0,"length":500000,"time":1.2400550842285156} []
[2024-03-11T17:07:15.548207+00:00] PerformanceTest.testPerformance.INFO: processing {"rps":338104.0,"length":500000,"time":1.4788329601287842} []
.                                                                   1 / 1 (100%)

nekufa@fasiga ~ % cat /proc/cpuinfo | grep AMD
model name	: AMD Ryzen 5 3600X 6-Core Processor
```

Configuration Options
---------------------

[](#configuration-options)

The following is the list of configuration options and default values.

OptionDefaultDescription`inboxPrefix``"_INBOX"`Sets de prefix for automatically created inboxes`jwt`Token for [JWT Authentication](https://docs.nats.io/running-a-nats-service/configuration/securing_nats/auth_intro/jwt). Alternatively you can use [CredentialsParser](#using-nkeys-with-jwt)`nkey`Ed25519 based public key signature used for [NKEY Authentication](https://docs.nats.io/running-a-nats-service/configuration/securing_nats/auth_intro/nkey_auth).`pass`Sets the password for a connection.`pedantic``false`Turns on strict subject format checks.`pingInterval``2`Number of seconds between client-sent pings.`port``4222`Port to connect to (only used if `servers` is not specified).`timeout`1Number of seconds the client will wait for a connection to be established.`token`Sets a authorization token for a connection.`tlsKeyFile`TLS 1.2 Client key file path.`tlsCertFile`TLS 1.2 Client certificate file path.`tlsCaFile`TLS 1.2 CA certificate filepath.`user`Sets the username for a connection.`verbose``false`Turns on `+OK` protocol acknowledgements.

###  Health Score

34

—

LowBetter than 77% of packages

Maintenance32

Infrequent updates — may be unmaintained

Popularity28

Limited adoption so far

Community16

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 57.6% 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 ~14 days

Recently: every ~21 days

Total

66

Last Release

698d ago

PHP version history (3 changes)0.1.0PHP >=8

0.7.0PHP >=8.1

v0.18.3PHP >=7.3

### Community

Maintainers

![](https://www.gravatar.com/avatar/dda0cbc703c8270bfc0f1e9c4823ccb9a9fd6b8f8d149178338ea50779e8e8f8?d=identicon)[mperusso](/maintainers/mperusso)

---

Top Contributors

[![nekufa](https://avatars.githubusercontent.com/u/405067?v=4)](https://github.com/nekufa "nekufa (106 commits)")[![adam-lmi](https://avatars.githubusercontent.com/u/99648011?v=4)](https://github.com/adam-lmi "adam-lmi (22 commits)")[![dmccarthy-bluefin](https://avatars.githubusercontent.com/u/61543249?v=4)](https://github.com/dmccarthy-bluefin "dmccarthy-bluefin (15 commits)")[![ro0NL](https://avatars.githubusercontent.com/u/1047696?v=4)](https://github.com/ro0NL "ro0NL (13 commits)")[![oxidmod](https://avatars.githubusercontent.com/u/12136231?v=4)](https://github.com/oxidmod "oxidmod (10 commits)")[![matheusperusso](https://avatars.githubusercontent.com/u/218663214?v=4)](https://github.com/matheusperusso "matheusperusso (6 commits)")[![g41797](https://avatars.githubusercontent.com/u/9116281?v=4)](https://github.com/g41797 "g41797 (3 commits)")[![vladimir1988](https://avatars.githubusercontent.com/u/7130828?v=4)](https://github.com/vladimir1988 "vladimir1988 (2 commits)")[![devbastic](https://avatars.githubusercontent.com/u/170054684?v=4)](https://github.com/devbastic "devbastic (2 commits)")[![nikola-primeinsights](https://avatars.githubusercontent.com/u/147150207?v=4)](https://github.com/nikola-primeinsights "nikola-primeinsights (1 commits)")[![edipoelwes](https://avatars.githubusercontent.com/u/64846517?v=4)](https://github.com/edipoelwes "edipoelwes (1 commits)")[![digibeuk](https://avatars.githubusercontent.com/u/5148394?v=4)](https://github.com/digibeuk "digibeuk (1 commits)")[![smsteel](https://avatars.githubusercontent.com/u/2188716?v=4)](https://github.com/smsteel "smsteel (1 commits)")[![tonysilva16](https://avatars.githubusercontent.com/u/65446091?v=4)](https://github.com/tonysilva16 "tonysilva16 (1 commits)")

---

Tags

responserequestclientstreamingqueuestoragepublishmessagingbucketsubscribeKey valuejetstreamnats

###  Code Quality

TestsPHPUnit

### Embed Badge

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

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

###  Alternatives

[basis-company/nats

nats jetstream client for php

201354.3k19](/packages/basis-company-nats)[nuwber/rabbitevents

The Nuwber RabbitEvents package

120515.8k3](/packages/nuwber-rabbitevents)[enqueue/amqp-lib

Message Queue Amqp Transport

1078.5M61](/packages/enqueue-amqp-lib)[microsoft/azure-storage-queue

This project provides a set of PHP client libraries that make it easy to access Microsoft Azure Storage Queue APIs.

142.6M17](/packages/microsoft-azure-storage-queue)[enqueue/simple-client

Message Queue Simple Client

221.1M26](/packages/enqueue-simple-client)

PHPackages © 2026

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