PHPackages                             nfarring/redisrpc - 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. [Caching](/categories/caching)
4. /
5. nfarring/redisrpc

ActiveLibrary[Caching](/categories/caching)

nfarring/redisrpc
=================

Lightweight RPC for Redis

0.3.5(14y ago)10575325[7 issues](https://github.com/nfarring/redisrpc/issues)[4 PRs](https://github.com/nfarring/redisrpc/pulls)PHPPHPPHP >=5.3.2

Since Feb 25Pushed 5y ago8 watchersCompare

[ Source](https://github.com/nfarring/redisrpc)[ Packagist](https://packagist.org/packages/nfarring/redisrpc)[ Docs](http://github.com/nfarring/redisrpc)[ RSS](/packages/nfarring-redisrpc/feed)WikiDiscussions master Synced 3w ago

READMEChangelogDependencies (1)Versions (8)Used By (0)

RedisRPC
========

[](#redisrpc)

by Nathan Farrington

RedisRPC is the easiest to use RPC library in the world. (No small claim!) It has implementations in Ruby, PHP, and Python.

Introduction
------------

[](#introduction)

[Redis](http://redis.io/) is a powerful in-memory data structure server that is useful for building fast distributed systems. Redis implements message queue functionality with its use of list data structures and the `LPOP`, `BLPOP`, and `RPUSH` commands. RedisRPC implements a lightweight RPC mechanism using Redis message queues to temporarily hold RPC request and response messages. These messages are encoded as [JSON](http://json.org/) strings for portability.

Many other RPC mechanisms are either programming language specific (e.g. [Java RMI](https://en.wikipedia.org/wiki/Java_remote_method_invocation)) or require boiler-plate code for explicit typing (e.g. [Thrift](https://en.wikipedia.org/wiki/Apache_Thrift)). RedisRPC was designed to be extremely easy to use by eliminating boiler-plate code while also being programming language neutral. High performance was not an initial goal of RedisRPC and other RPC libraries are likely to have better performance. Instead, RedisRPC has better programmer performance; it lets you get something working immediately.

Calculator Example
------------------

[](#calculator-example)

Each library implementation uses the same client and server example based off of a mutable calculator object. The clients and servers from different languages are interoperable.

[![](http://github.com/nfarring/redisrpc/raw/master/docs/redisrpc_example.png)](http://github.com/nfarring/redisrpc/raw/master/docs/redisrpc_example.png)

1. The client issues an RPC Request by using the Redis `RPUSH` command to push an RPC Request message into a Redis list called `calc`.
2. The server retrieves the RPC Request message by using the Redis `BLPOP`command.
3. The server dispatches the RPC Request to a local object, which in this case is a Calculator object.
4. The server accepts the return value (or exception) from the Calculator object.
5. The server issues an RPC Response by using the Redis `RPUSH` command to push an RPC Response message into a Redis list called `calc:rpc:`, which was chosen by the client.
6. The client retrieves the RPC Response message by using the Redis `BLPOP`command.

*Note that the server or client can be made non-blocking by using the Redis LPOP command instead of BLPOP. I currently do not need this feature and have not added support for this, but patches are welcome.*

That's all there is to it!

Ruby Usage
----------

[](#ruby-usage)

### client.rb

[](#clientrb)

```
redis_server = Redis.new
message_queue = 'calc'
calculator = RedisRPC::Client.new redis_server, 'calc'
calculator.clr
calculator.add 5
calculator.sub 3
calculator.mul 4
calculator.div 2
assert calculator.val == 4
```

### server.rb

[](#serverrb)

```
redis_server = Redis.new
message_queue = 'calc'
local_object = Calculator.new
server = RedisRPC::Server.new redis_server, message_queue, local_object
server.run
```

PHP Usage
---------

[](#php-usage)

*Note that the PHP library does not currently support named function arguments.*

### client.php

[](#clientphp)

```
$redis_server = new Predis\Client();
$message_queue = 'calc';
$calculator = new RedisRPC\Client($redis_server, $message_queue);
$calculator->clr();
$calculator->add(5);
$calculator->sub(3);
$calculator->mul(4);
$calculator->div(2);
assert($calculator->val() == 4);
```

### server.php

[](#serverphp)

```
$redis_server = new Predis\Client();
$message_queue = 'calc';
$local_object = new Calculator();
$server = new RedisRPC\Server($redis_server, $message_queue, $local_object);
$server->run();
```

Python Usage
------------

[](#python-usage)

### client.py

[](#clientpy)

```
redis_server = redis.Redis()
message_queue = 'calc'
calculator = redisrpc.Client(redis_server, message_queue)
calculator.clr()
calculator.add(5)
calculator.sub(3)
calculator.mul(4)
calcaultor.div(2)
assert calculator.val() == 4
```

The Python client also takes the additional keyword parameters `timeout`and `transport`. If `transport='pickle'` then it is possible to send Python objects as function arguments, but only if the server is also implemented in Python, and only if the server has access to the same libraries in order to unpickle the objects.

### server.py

[](#serverpy)

```
redis_server = redis.Redis()
message_queue = 'calc'
local_object = calc.Calculator()
server = redisrpc.Server(redis_server, message_queue, local_object)
server.run()
```

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

[](#installation)

### Ruby Installation

[](#ruby-installation)

The [redis-rb](https://github.com/ezmobius/redis-rb) library is required. Install using RubyGems:

```
gem install redisrpc
```

### PHP Installation

[](#php-installation)

The [Predis](https://github.com/nrk/predis) library is required.

The RedisRPC PHP library is available from [Packagist](http://packagist.org/) at: . You can use [Composer](https://github.com/composer/composer) to install into your PHP project.

### Python Installation

[](#python-installation)

The [redis-py](https://github.com/andymccurdy/redis-py) library is required.

The RedisRPC Python library is available from [PyPI](http://pypi.python.org/) at: . You can install with [pip](http://pypi.python.org/pypi/pip).

```
pip install redisrpc
```

Internal Message Formats
------------------------

[](#internal-message-formats)

All RPC messages are JSON objects. User code will never see these objects because they are handled by the RedisRPC library.

### RPC Request

[](#rpc-request)

An RPC Request contains two members: a `function_call` object and a `response_queue` string.

A `function_call` object has one required member: a `name` string for the function name. It also has two optional members: (a) an `args` list for positional function arguments, and (b) a `kwargs` object for named function arguments.

The `response_queue` string is the name of the Redis list where the corresponding RPC Response message should be pushed by the server. This queue is chosen programmatically by the client to be collision free in the Redis namespace. Also, this queue is used only for a single RPC Response message and is not reused for future RPC Response messages.

```
{ "function_call" : {
      "args" : [ 1, 2, 3 ],
      "kwargs" : { "a" : 4, "b" : 5, "c" : 6 },
      "name" : "foo"
    },
  "response_queue" : "calc:rpc:X7Y2US"
}
```

### RPC Response (Successful)

[](#rpc-response-successful)

If an RPC is successful, then the RPC Response object will contain a single member, a `return_value` of some JSON type.

```
{ "return_value" : 4.0 }
```

### RPC Response (Exception)

[](#rpc-response-exception)

If an RPC encounters an exceptional condition, then the RPC Response object will contain a single member, an `exception` string. Note that the value of the `exception` string might not have any meaning to the client since the client and server might be written in different languages or the client might have no knowledge of the server's wrapped object. Therefore the best course of action is probably to display the `exception` value to the user.

```
{ "exception" : "AttributeError(\\"\'Calculator\' object has no attribute \'foo\'\\",)" }
```

Source Code
-----------

[](#source-code)

Source code is available at .

License
-------

[](#license)

This software is available under the [GPLv3](http://www.gnu.org/licenses/gpl.html) or later.

Changelog
---------

[](#changelog)

Version 0.3.5

- Ruby: feature: use multi\_json gem \[Ryan Biesemeyer\]
- Ruby: feature: server.run! flushes queue but server.run does not \[Ryan Biesemeyer\]
- Ruby: performance: only one call to rand instead of eight \[Ryan Biesemeyer\]
- Ruby: bugfix: RedisRPC::VERSION \[Ryan Biesemeyer\]
- Ruby: security: remove eval \[Ryan Biesemeyer\]

Version 0.3.4

- Client now supports optional timeout.
- Server now deletes message queue when starting.
- PHP: Fixed exception handling.

Version 0.3.3

- Ruby: Added a Ruby library implementation.

Version 0.3.2

- Fixed some formatting in README.markdown that was causing problems when converted to reStructredText.
- Added version information to README.markdown.
- Added installation instructions to README.markdown.
- Python: Added RPC message logging using the logging module.
- Python: Added redis as an installation dependency.
- Python: Now using Distribute instead of distutils.

Version 0.3.1

- PHP: Changed composer.json predis dependency version.

Version 0.3.0

- Empty function call args and kwargs are no longer transmitted.
- PHP: Added support for the PHP language.
- PHP: Now installable with PHP Composer.
- Python: Shortened the Client and Server class names.
- Python: Debugging modified to print JSON representation.
- Python: Switched the README file back to ReStructred Text.

Version 0.2.1

- Python: Fixed MANIFEST.in to reflect filename changes.

Version 0.2.0

- Simplified the JSON RPC message format.
- Documented the JSON RPC message format.
- Python: Using HTML file for README, will it work?
- Python: Renamed calc\_client to client.py.
- Python: Renamed calc\_server to server.py.
- Python: Added a RemoteException class, which can be raised by the client.

Version 0.1.2

- Python: Fixed the download\_url in setup.py.
- Python: Renamed the README file to README.rst to support browsing on Github.

Version 0.1.1

- Python: Added README.
- Python: Added long\_description to setup.py.
- Python: Added MANIFEST.in file.
- Python: Added examples/ subdirectory to MANIFEST.
- Python: Modified examples/ directory to be consistent with README file.
- Python: Fixed the download\_url in setup.py.

Version 0.1.0

- Changed to the GPL license.
- Python: Removed unused functionality from python/redisrpc.py.
- Python: Added a setup.py installer script.

###  Health Score

32

—

LowBetter than 69% of packages

Maintenance19

Infrequent updates — may be unmaintained

Popularity30

Limited adoption so far

Community17

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 69.2% 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 ~10 days

Total

6

Last Release

5186d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/459634626e7be3ec5ce0ed4cc4f8dfafb2dcd478ebea9cff5e00087f1b32218d?d=identicon)[nfarring](/maintainers/nfarring)

---

Top Contributors

[![nfarring](https://avatars.githubusercontent.com/u/331701?v=4)](https://github.com/nfarring "nfarring (27 commits)")[![yaauie](https://avatars.githubusercontent.com/u/210924?v=4)](https://github.com/yaauie "yaauie (12 commits)")

---

Tags

rpcredis

### Embed Badge

![Health badge](/badges/nfarring-redisrpc/health.svg)

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

###  Alternatives

[rhubarbgroup/redis-cache

A persistent object cache backend for WordPress powered by Redis. Supports Predis, PhpRedis, Relay, replication, sentinels, clustering and WP-CLI.

527101.4k1](/packages/rhubarbgroup-redis-cache)[symfony-bundles/redis-bundle

Symfony Redis Bundle

291.2M6](/packages/symfony-bundles-redis-bundle)[cache/predis-adapter

A PSR-6 cache implementation using Redis (Predis). This implementation supports tags

242.6M13](/packages/cache-predis-adapter)[pdffiller/qless-php

PHP Bindings for qless

29113.7k2](/packages/pdffiller-qless-php)[contributte/redis

Redis client integration into Nette framework

191.7M2](/packages/contributte-redis)

PHPackages © 2026

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