README

Repositorio con utilidades mínimas para trabajar con RabbitMQ: clientes (RPC y topic) y servidores que consumen RPC y mensajes topic.

Este README explica cómo usar el código, cómo extender las clases base y cómo probar el proyecto usando los scripts de ejemplo incluidos en tests/Scripts/.

Contenido relevante del repositorio

src/ — implementaciones principales:
- Core/RabbitMQClient.php — clase base para clientes (RPC + topic).
- Core/RabbitMQServer.php — clase base para servidores (RPC + topic).
- Interfaces/RPCActionHandler.php — contrato para handlers RPC.
- Traits/RabbitmqToolsUtilsTrait.php — helpers útiles (p. ej. response).
tests/ — ejemplos y clases de prueba:
- TestClient.php, TestServer.php, TestActionHandler.php — ejemplos de cliente/servidor/handler.
tests/Scripts/ — scripts de ejemplo:
- start_server.php — arranca TestServer.
- rpc_client.php — cliente RPC de ejemplo.
- topic_client.php — cliente topic de ejemplo.
docker-compose.yaml — incluye un servicio rabbitmq y contenedores php útiles para pruebas locales.

Descripción rápida

Las clases base facilitan:

Envío de mensajes a un exchange topic.
Realizar llamadas RPC y esperar la respuesta correlacionada.
Crear y gestionar colas y bindings necesarios en el servidor.

La idea es que extiendas RabbitMQClient y RabbitMQServer definiendo las colas/exchanges que usas y los handlers RPC (implementando RPCActionHandler).

Requisitos

PHP 7.4+ (el proyecto dispone de imágenes Docker para 7.4 y 8.3 en docker-compose.yaml).
Composer.
Extensión ext-json.
RabbitMQ (puedes usar Docker/docker-compose incluido).

Dependencias PHP definidas en composer.json: php-amqplib/php-amqplib.

Instalación

Instala las dependencias con Composer:

composer install

(Opcional) Levanta RabbitMQ con Docker Compose (recomendado para pruebas):

docker-compose up -d rabbitmq

Credenciales por defecto en el compose: user / password.

Si quieres levantar también los contenedores PHP listados en docker-compose.yaml:

docker-compose up -d

Ejemplos de uso

Los scripts de ejemplo usan clases definidas en tests/:

TestClient extiende RabbitMQClient y define rpcQueue() y topicExchangeName().
TestServer extiende RabbitMQServer, define rpcActionMap() y topicRoutingKeys() y un topicCallback() para imprimir mensajes.
TestActionHandler implementa RPCActionHandler y devuelve una respuesta JSON simple.

Parámetros por defecto en los scripts de ejemplo:

host: rabbitmq
port: 5672
user: user
password: password
vhost: /

Ejecutar los ejemplos localmente (PHP CLI)

Arranca el servidor de ejemplo en una terminal:

php tests/Scripts/start_server.php

Deberías ver algo como:

Listening to RPC action: test-action -> Beat\RabbitmqTools\Tests\TestActionHandler
Listening to topic: #.pokemon
Listening to topic: weekday.*
Listening to topic: beateam.newsletter

En otra terminal, envía una petición RPC:

php tests/Scripts/rpc_client.php test-action "hola"

Salida esperada (ejemplo):

RPC Response:
Array
(
    [message] => Action handled successfully
    [params] => Array
        (
        )

    [body] => Array
        (
            [msg] => hola
        )

)

Publica un mensaje topic:

php tests/Scripts/topic_client.php test.topic.pokemon "mi mensaje"

En la salida del servidor (donde start_server.php corre) verás algo similar a:

Received message on routing key 'test.topic.pokemon': {"message":"mi mensaje"}

Nota importante: los scripts usan por defecto $host = 'rabbitmq'. Esto funciona cuando ejecutas PHP dentro de los contenedores definidos por docker-compose, ya que rabbitmq es el hostname del servicio. Si ejecutas los scripts desde tu máquina local, cambia el host a localhost o la IP donde esté RabbitMQ.

Ejecutar los ejemplos desde Docker (recomendado si no tienes PHP local)

Ejecuta el servidor dentro del contenedor PHP 8.3:

docker-compose run --rm php-8.3 php tests/Scripts/start_server.php

Ejecuta el cliente RPC dentro del contenedor PHP 8.3:

docker-compose run --rm php-8.3 php tests/Scripts/rpc_client.php test-action "hola"

Ejecuta el cliente topic dentro del contenedor PHP 8.3:

docker-compose run --rm php-8.3 php tests/Scripts/topic_client.php test.topic.apples "mi mensaje"

Al usar docker-compose run, el contenedor tiene visibilidad de la red definida en el compose, por eso el hostname rabbitmq resuelve correctamente.

Extender las clases

`RabbitMQClient`

Debes crear una subclase y definir (al menos) los métodos:

protected function rpcQueue(): ?string;
protected function topicExchangeName(): ?string;

rpc(string $action, array $message = [], array $params = [], int $timeout = 30): array — envía una petición RPC y devuelve la respuesta (decodificada).
topic(string $routing_key, array $message = []): void — publica un mensaje JSON en el exchange topic.

Si rpcQueue() devuelve null, las funcionalidades RPC no estarán disponibles y la llamada a rpc() lanzará RPCQueueNotDefinedException.

`RabbitMQServer`

Debes crear una subclase e implementar:

protected function rpcQueue(): ?string;
protected function topicExchangeName(): ?string;
public function rpcActionMap(): array; // action => HandlerClass
public function topicRoutingKeys(): array; // lista de routing keys
protected function topicCallback(string $routing_key, array $message): void;

rpcActionMap() debe devolver un array con pares action => HandlerClass. HandlerClass debe implementar Beat\RabbitmqTools\Interfaces\RPCActionHandler.
topicRoutingKeys() devuelve los patterns que se bindearán al exchange topic.
listen() crea las colas/bindings y comienza a consumir.

Los handlers RPC deben implementar la interfaz:

interface RPCActionHandler
{
    public function handle(array $params, array $body): string;
}

En los tests hay TestActionHandler como ejemplo — usa RabbitmqToolsUtilsTrait::response() para construir respuestas JSON.

Excepciones y errores comunes

RPCQueueNotDefinedException — cuando llamas a rpc() y la subclase no definió rpcQueue().
TopicExchangeNameNotDefinedException — cuando llamas a topic() y topicExchangeName() no está definida.
ServerHasNoQueuesException — lanzada por RabbitMQServer::listen() si la implementación no define ni RPC ni topic.

Además la librería propaga excepciones de php-amqplib para errores de conexión/tiempo de espera.

Pruebas

El repositorio incluye scripts de ejemplo para pruebas manuales (tests/Scripts/). No hay un suite de PHPUnit incluida por defecto.

Pasos rápidos para probar localmente:

composer install
docker-compose up -d rabbitmq (o docker-compose up -d si quieres los contenedores PHP)
Abrir una terminal y ejecutar:

php tests/Scripts/start_server.php

En otra terminal probar los clientes (RPC y topic) como se muestra arriba.

Si quieres, puedo añadir una suite básica de PHPUnit con 2-3 tests (ej. verificar response() del trait y la serialización/deserialización RPC) y un comando composer para ejecutarlos. Dime si lo quieres y lo implemento.

Depuración y UI

Management UI (si usas docker-compose): http://localhost:15672 (usuario user, contraseña password).
Comprueba que RabbitMQ está corriendo con docker ps o docker-compose ps.
Si obtienes errores de conexión, revisa que los valores de host/port/credenciales coincidan con los scripts y con tu entorno.

Contribuir

Si quieres contribuir: crea un fork, agrega tests para el nuevo comportamiento y abre un pull request.

Licencia

LGPL-3.0-or-later (ver composer.json).

beat / rabbitmq-tools

Maintainers

Details