zhaohai/rocketmq-client-php

Official PHP client for Apache RocketMQ - A distributed messaging and streaming platform

Maintainers

Package info

github.com/zhaohai666/rocketmq-client-php

Homepage

Issues

Documentation

pkg:composer/zhaohai/rocketmq-client-php

Statistics

Installs: 35

Dependents: 0

Suggesters: 0

Stars: 0

Security

Advisories: 0

Aikido package health analysis

v1.1.24 2026-04-21 07:24 UTC

Requires

Requires (Dev)

Apache-2.0 5f73c31512b5bffddf477eacab5579161a6d527c

queuemessagingstreamingapacherocketMq

This package is auto-updated.

Last update: 2026-04-21 07:24:43 UTC

README

License PHP Version RocketMQ Version

English | 简体中文 | RocketMQ Website

Overview

Here is the PHP implementation of the client for Apache RocketMQ. Different from the legacy clients, this implementation is based on the computing-storage separation architecture of RocketMQ 5.x, which is the recommended approach for accessing RocketMQ services.

Prerequisites you need to know (or refer to quick start):

  1. PHP 7.4+ for runtime;
  2. Setup namesrv, broker, and proxy.

Getting Started

Installation

Install dependencies using Composer:

composer install

Generate gRPC Code

Before using the client, you need to generate gRPC code from proto files:

cd php
bash scripts/grpc_tool.sh generate

For detailed instructions, see Generate gRPC Code section below.

Quick Example

Producer

use Apache\Rocketmq\ClientServiceProvider;
use Apache\Rocketmq\ClientConfiguration;

$provider = ClientServiceProvider::getInstance();
$config = new ClientConfiguration('your-endpoints:8080');

$producer = $provider->newProducerBuilder()
    ->setClientConfiguration($config)
    ->setTopics('your-topic')
    ->build();

$result = $producer->sendNormalMessage("Hello RocketMQ", "TagA", "key1");
echo "Message sent: " . $result->getMessageId() . "\n";

$producer->close();

PushConsumer

use Apache\Rocketmq\ClientServiceProvider;
use Apache\Rocketmq\ClientConfiguration;
use Apache\Rocketmq\Consumer\ConsumeResult;

$provider = ClientServiceProvider::getInstance();
$config = new ClientConfiguration('your-endpoints:8080');

$consumer = $provider->newPushConsumerBuilder()
    ->setClientConfiguration($config)
    ->setConsumerGroup('GID-test-group')
    ->setTopic('your-topic')
    ->setMessageListener(function($message) {
        echo "Received: " . $message->getBody() . "\n";
        return ConsumeResult::SUCCESS;
    })
    ->build();

$consumer->start();

More examples are available in the examples directory to help you work with different message types:

  • Normal messages
  • FIFO ordered messages
  • Delayed/scheduled messages
  • Transaction messages
  • Priority messages
  • Lite topic messages

Logging System

The PHP client uses a custom Logger class that follows SLF4J-style formatting (compatible with Java's logging pattern).

Log output path: $HOME/logs/rocketmq/rocketmq-client.log

You can configure log level by setting environment variable:

export ROCKETMQ_LOG_LEVEL=DEBUG  # Options: DEBUG, INFO, WARN, ERROR

Features

Core Features

  • ✅ Normal message send and consume
  • ✅ FIFO ordered messages (with consume accelerator)
  • ✅ Scheduled/delayed messages
  • ✅ Transaction messages
  • ✅ Priority messages
  • ✅ Lite topic messages
  • ✅ Message tags and keys
  • ✅ SimpleConsumer mode (active pull)
  • ✅ PushConsumer mode (listener push)
  • ✅ Async message sending
  • ✅ Message acknowledgment (ACK)

Advanced Features

  • ✅ Batch message sending
  • ✅ Message interceptor
  • ✅ Connection health check
  • ✅ Metrics monitoring (Prometheus compatible)
  • ✅ Exponential backoff retry policy
  • ✅ Route cache
  • ✅ Builder pattern API
  • ✅ Custom exceptions

Generate gRPC Code

Prerequisites

  1. Protocol Buffer Compiler

    macOS:

    brew install protobuf

    Ubuntu/Debian:

    apt-get install protobuf-compiler

  2. gRPC PHP Plugin

    Method 1 - Using automated script (recommended):

    bash scripts/grpc_tool.sh install

    Method 2 - Compile from source:

    git clone --recursive https://github.com/grpc/grpc.git
cd grpc
mkdir cmake/build && cd cmake/build
cmake -DgRPC_INSTALL=ON -DgRPC_BUILD_CODEGEN=ON ../..
make grpc_php_plugin
sudo make install

Generate Code

bash scripts/grpc_tool.sh generate

This will generate all necessary gRPC classes in the grpc/ directory.

Examples

See the examples directory for complete working examples:

Testing

Run tests to verify your setup:

cd php
php tests/test_producer_consumer.php

Troubleshooting

Issue: grpc_php_plugin not found

Solution: Install the plugin using:

bash scripts/grpc_tool.sh install

Issue: Permission denied when cleaning /tmp/grpc

Solution: Use sudo to remove old files:

sudo rm -rf /tmp/grpc

Issue: Swoole coroutine API must be called in coroutine

Solution: Ensure Swoole APIs like \Swoole\Coroutine::sleep() are called within a coroutine context created by \Swoole\Coroutine::create() or go().

References