README

Overview

This is a PHP library for NSQ realtime distributed messaging platform nsqd protocol written in PHP. simplensqclient has no other dependancies outside of the core PHP distribution, but does require PHP > 5.5.

simplensqclient implements most, but not all of NSQ's platform functionality.

"Simple" refers to the subscription handling. The library does not follow the recommendations of the NSQ project for client design, more specifically it does not use any kind of threading, or asynchronous IO event loop for socket handling and message processing. The NSQPHP library (https://github.com/davegardnerisme/nsqphp) utilises the react PHP event loop and library ecosystem to implement this type of client.

Instead simplensqclient uses an asynchronous loop for the connections for a cluster, waiting for one to be ready. Each message is then processed one by one before returning to the loop waiting for more ready connections. The API presented is a Generator returning each messages one by one, a much simpler API design than having your processing in an event loop.

This does present one major limitation: If you do a lot of intensive processing with each message, you are going to get problems with throughput and message timeouts. However, for short, event-like message processing though, it should work fine, and a larger throughput can be acheived by running more subscription clients.

This library is currently alpha status. simplensqclient has no real world production use (AFAIK).

Supported NSQ protocol features

Feature	Supported	notes
PUB	Yes
SUB	Yes	only 1 message inflight from each nsqd instance
TLS	Yes
Deflate	Yes	requires PHP compiled with zlib and doesn't work in any known released PHP without patching the zlib stream wrapper, see PHP BUG #48725
AUTH	Yes
Reconnect Backoff	Yes
Discovery	Yes
Message Backoff	No	Probably not needed because the client never ramps up to backoff currently.
Snappy	No	no stream wrapper support in PHP
Sampling	No

Getting started

Add scottaubrey/simplensqclient to composer using the composer require command

composer.phar require "scottaubrey/simplensqclient"

Then you can publish a message to an nsqd:

//create an NSQ instance with default hostname and port
$nsq = new NsqConnection;

//publish a simple string message
$nsq->publish("TestTopic", "My Message");

and subscribe to a single nsqd (one message at a time):

//create an NSQ instance with default hostname and port
$nsq = new NsqConnection;

//publish a simple string message
foreach ($nsq->subscribe("TestTopic", "MyTestChannel") as $messageId => $message) {
    $nsq->finish($messageId);
}

There are other examples in the examples directory

Roadmap

These are the tasks to be done before 1.0:

Connection options - particularly allow configuring message timeout and heartbeat interval.
Tidy up API, Doc blocks
Publish strategies - currently only round-robin publishing is supported.

Things to try at some point:

Investigate support for PCNTL and/or pthreads (https://github.com/krakjoe/pthreads) - with one thread for reading the connections, while processing messages in another process/thread.
Deduplication of messages - NSQPHP (https://github.com/davegardnerisme/nsqphp) provides a deduplication layer on top of the base library based on a bloom filter. This library, for the moment, assumes the comsumer is aware of the At-Least-Once nature of the NSQ platform.

License

This library is license under the open source MIT license, the text included in the root folder.

scottaubrey / simplensqclient

Maintainers

Details