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

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

basis-company/nats
==================

nats jetstream client for php

1.2.1(1mo ago)201354.3k—6.4%45[14 issues](https://github.com/basis-company/nats.php/issues)[5 PRs](https://github.com/basis-company/nats.php/pulls)16MITPHPPHP >=8.1CI passing

Since Dec 14Pushed 1mo ago7 watchersCompare

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

READMEChangelog (10)Dependencies (8)Versions (81)Used By (16)

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

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

[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT)[![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)[![Coverage Status](https://camo.githubusercontent.com/ce2aa594ad592f449a7880ece40926524c7ea6ea8aff0aa93bd8c72cfd84f0eb/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f62617369732d636f6d70616e792f6e6174732e7068702f62616467652e737667)](https://coveralls.io/github/basis-company)[![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.

- [Nats client for php](#nats-client-for-php)
    - [Installation](#installation)
    - [Connecting](#connecting)
        - [Connecting with TLS](#connecting-with-tls)
        - [Connecting with JWT](#connecting-with-jwt)
    - [Publish Subscribe](#publish-subscribe)
    - [Request Response](#request-response)
    - [JetStream Api Usage](#jetstream-api-usage)
    - [Microservices](#microservices)
    - [Key Value Storage](#key-value-storage)
    - [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.

Connecting
----------

[](#connecting)

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

// you can override any default configuraiton key using constructor
$configuration = new Configuration(
    host: 'nats-service',
    user: 'basis',
    pass: 'secret',
);

// delay configuration options are changed via setters
// 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 with TLS

[](#connecting-with-tls)

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;

// you can override any default configuraiton key using constructor
$configuration = new Configuration(
    host: 'tls-service-endpoint',
    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
```

Connecting with JWT
-------------------

[](#connecting-with-jwt)

To use NKey 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(
    CredentialsParser::fromFile($credentialPath)
    host: 'localhost',
    port: 4222,
);

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

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 until 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()->setSubjectFilters(['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);
```

Microservices
-------------

[](#microservices)

The services feature provides a simple way to create microservices that leverage NATS.

In the example below, you will see an example of creating an index function for the posts microservice. The request can be accessed under "v1.posts" and then individual post by "v1.posts.{post\_id}".

```
// Define a service
$service = $client->service(
    'PostsService',
    'This service is responsible for handling all things post related.',
    '1.0'
);

// Create the version group
$version = $service->addGroup('v1');

// Create the index posts endpoint handler
class IndexPosts implements \Basis\Nats\Service\EndpointHandler {

    public function handle(\Basis\Nats\Message\Payload $payload): array
    {
        // Your application logic
        return [
            'posts' => []
        ];
    }
}

// Create the index endpoint
$version->addEndpoint("posts", IndexPosts::class);

// Create the service group
$posts = $version->addGroup('posts');

// View post endpoint
$posts->addEndpoint(
    '*',
    function (\Basis\Nats\Message\Payload $payload) {
        $postId = explode('.', $payload->subject);
        $postId = $postId[count($postId)-1];

        return [
            'post' => []
        ];
    }
);

// Run the service
$service->run();
```

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']
```

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

[](#performance)

Testing on AMD Ryzen 5 3600X with nats running in docker gives about 370k rps for publish and 360k 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.6.18 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.3.11
Configuration: /home/nekufa/software/github/nats.php/phpunit.xml
Warning:       No code coverage driver available

[2024-12-24T12:07:04.063687+00:00] PerformanceTest.testPerformance.DEBUG: send CONNECT {"headers":true,"pedantic":false,"verbose":false,"lang":"php","version":"dev"}  [] []
[2024-12-24T12:07:04.063725+00:00] PerformanceTest.testPerformance.INFO: start performance test [] []
[2024-12-24T12:07:05.391707+00:00] PerformanceTest.testPerformance.INFO: publishing {"rps":376536.0,"length":500000,"time":1.3278908729553223} []
[2024-12-24T12:07:06.762321+00:00] PerformanceTest.testPerformance.INFO: processing {"rps":364814.0,"length":500000,"time":1.3705589771270752} []

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

Runtime:       PHP 8.3.11
Configuration: /home/nekufa/software/github/nats.php/phpunit.xml
Warning:       No code coverage driver available

[2024-12-24T12:07:43.721568+00:00] PerformanceTest.testPerformance.DEBUG: send CONNECT {"headers":true,"pedantic":false,"verbose":true,"lang":"php","version":"dev"}  [] []
[2024-12-24T12:07:43.721606+00:00] PerformanceTest.testPerformance.INFO: start performance test [] []
[2024-12-24T12:07:45.053410+00:00] PerformanceTest.testPerformance.INFO: publishing {"rps":375456.0,"length":500000,"time":1.3317129611968994} []
[2024-12-24T12:07:46.566548+00:00] PerformanceTest.testPerformance.INFO: processing {"rps":330450.0,"length":500000,"time":1.513084888458252} []

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](#connecting-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.`tlsHandshakeFirst``false`If true, the client performs the TLS handshake immediately after connecting, without waiting for the server’s INFO message.`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

67

—

FairBetter than 100% of packages

Maintenance87

Actively maintained with recent releases

Popularity56

Moderate usage in the ecosystem

Community39

Small or concentrated contributor base

Maturity74

Established project with proven stability

 Bus Factor1

Top contributor holds 65.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 ~19 days

Recently: every ~45 days

Total

80

Last Release

56d ago

Major Versions

0.26.3 → 1.0.02024-12-24

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

0.7.0PHP >=8.1

### Community

Maintainers

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

---

Top Contributors

[![nekufa](https://avatars.githubusercontent.com/u/405067?v=4)](https://github.com/nekufa "nekufa (191 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 (14 commits)")[![oxidmod](https://avatars.githubusercontent.com/u/12136231?v=4)](https://github.com/oxidmod "oxidmod (10 commits)")[![izytechAB](https://avatars.githubusercontent.com/u/1360070?v=4)](https://github.com/izytechAB "izytechAB (5 commits)")[![EmilJimenez21](https://avatars.githubusercontent.com/u/1885357?v=4)](https://github.com/EmilJimenez21 "EmilJimenez21 (5 commits)")[![chazzbg](https://avatars.githubusercontent.com/u/4026105?v=4)](https://github.com/chazzbg "chazzbg (5 commits)")[![g41797](https://avatars.githubusercontent.com/u/9116281?v=4)](https://github.com/g41797 "g41797 (4 commits)")[![vladimir1988](https://avatars.githubusercontent.com/u/7130828?v=4)](https://github.com/vladimir1988 "vladimir1988 (2 commits)")[![digibeuk](https://avatars.githubusercontent.com/u/5148394?v=4)](https://github.com/digibeuk "digibeuk (2 commits)")[![devbastic](https://avatars.githubusercontent.com/u/170054684?v=4)](https://github.com/devbastic "devbastic (2 commits)")[![tonysilva16](https://avatars.githubusercontent.com/u/65446091?v=4)](https://github.com/tonysilva16 "tonysilva16 (1 commits)")[![wirajl](https://avatars.githubusercontent.com/u/28729086?v=4)](https://github.com/wirajl "wirajl (1 commits)")[![zlatkoverk](https://avatars.githubusercontent.com/u/25726655?v=4)](https://github.com/zlatkoverk "zlatkoverk (1 commits)")[![bpacholek](https://avatars.githubusercontent.com/u/3039162?v=4)](https://github.com/bpacholek "bpacholek (1 commits)")[![edipoelwes](https://avatars.githubusercontent.com/u/64846517?v=4)](https://github.com/edipoelwes "edipoelwes (1 commits)")[![edipoelwes2](https://avatars.githubusercontent.com/u/52359155?v=4)](https://github.com/edipoelwes2 "edipoelwes2 (1 commits)")[![flyDuckWithMac](https://avatars.githubusercontent.com/u/199191362?v=4)](https://github.com/flyDuckWithMac "flyDuckWithMac (1 commits)")[![FreeMasen](https://avatars.githubusercontent.com/u/6232026?v=4)](https://github.com/FreeMasen "FreeMasen (1 commits)")

---

Tags

clientjetstreamnatsphpresponserequestclientstreamingqueuestoragepublishmessagingbucketsubscribeKey valuejetstreamnats

###  Code Quality

TestsPHPUnit

Code StylePHP CS Fixer

### Embed Badge

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

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

###  Alternatives

[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)