apex/cluster

Load Balancer / Router for Horizontal Scaling

2.0.3 2023-10-20 08:01 UTC

Requires

• php: >=8.0
• apex/container: >=2.0
• monolog/monolog: ^3.4
• php-amqplib/php-amqplib: ^3.0
• psr/event-dispatcher: ^1.0
• symfony/string: ^6.0
• symfony/yaml: ^6.0

Requires (Dev)

• apex/signer: ^2.0
• phpunit/phpunit: ^9.5

MIT

README

Cluster provides a simple yet intuitive interface to implement horizontal scaling across your application via RabbitMQ or any message broker. With the local message broker, easily develop your software with horizontal scaling fully implemented while running on one server, and split into multiple server instances within minutes when necessary. It supports:

• General round robin and routing of designated messages to specific server instances.
• One-way queued messages, two-way RPC calls, and system wide broadcasts.
• Parameter / header based routing.
• Easy to configure YAML router file.
• Optional centralized redis storage of router configuration for maintainability across server instances.
• Standardized immutable request and response objects for ease-of-use and interopability.
• Front-end handlers for streamlined communication back to front-end servers allowing execution of events to the client side (eg. set template variables, et al).
• Timeout and message preparation handlers, plus concurrency settings.
• Interchangeable with any other message broker including the ability to easily implement your own.
• Includes local message broker, allowing implementation of logic for horizontal scaling while remaining on one server instance.
• Optional auto-routing allowing messages to be automatically routed to correct class and method that correlates to named routing key.

Table of Contents

1. Cluster class / Container Definitions
2. Router Overview
   1. Adding Routes in PHP
   2. Router YAML Configuration File
   3. Auto Routing
   4. Parameter Based Routing
   5. Enable redis Autoloading
3. Message Handling
   1. Listen / Consume Messages
   2. Dispatch Messages
   3. Fetch Messages from Queues
4. Messages
   1. Message Requests
   2. Message Responses
5. Front-End Handlers

Installation

Install via Composer with:

composer require apex/cluster

Basic Usage

Please see the /examples/ directory for more in-depth examples.

Save Math.php Class

namespace App;

class Math {

    public function add(MessageRequestInterface $msg)
    {
        list($x, $y) = $msg->getParams();
        return ($x + $y);
    }
}

Define Listener

use Apex\Cluster\Cluster;
use Apex\Cluster\Listener;
use Apex\Cluster\Brokers\RabbitMQ;


// Start cluster
$cluster = new Cluster('app1');
$cluster->setBroker(new RabbitMQ('localhost', 5672, 'guest', 'guest'));
$cluster->addRoute('basic.math.*', App\Math::class);

// Start listener
$listener = new Listener();
$listener->listen();

Define Dispatcher

use Apex\Cluster\Dispatcher;
use Apex\Cluster\Message\MessageRequest;

// Define message
$msg = new MessageRequest('basic.math.add', 6, 9);

// Dispatch message
$dispatcher = new Dispatcher('web1');
$sum = $dispatcher->dispatch($msg)->getResponse();

// Print result
echo "Sum is: $sum\n";

Follow Apex

Loads of good things coming shortly including new quality open source packages, more advanced articles / tutorials that go over down to earth useful topics, et al. Stay informed by joining the mailing list on our web site, or follow along on Twitter at @mdizak1.