feat: Message Broker Quickstart Example (#583)

Author: dgafka

quickstart-examples/MessageBroker/README.md

@@ -0,0 +1,128 @@
+# Message Broker with Ecotone - RabbitMQ, Kafka, SQS, Redis
+
+This example demonstrates how incredibly easy it is to set up **asynchronous messaging** with a message broker using [Ecotone Framework](https://ecotone.tech). With just a few lines of code, you can publish and consume messages from **RabbitMQ**, and switch to **Kafka**, **Amazon SQS**, **Redis**, or **Database (DBAL)** with a single line change.
+
+## Quick Start
+
+```bash
+# Install dependencies
+composer install
+
+# Run publisher (sends message to RabbitMQ)
+php publisher.php
+
+# Run consumer (receives and processes message)
+php consumer.php
+```
+
+**Output:**
+```
+Message sent to queue 'orders'
+Starting consumer for queue 'orders'...
+Processing order 123: Milk
+Consumer finished.
+```
+
+## Why Ecotone Makes It Easy
+
+### 1. Single Line Channel Configuration
+
+Setting up a RabbitMQ-backed message channel requires just **one line**:
+
+```php
+AmqpBackedMessageChannelBuilder::create('orders')
+```
+
+That's it. No complex queue bindings, no exchange declarations, no consumer configuration. Ecotone handles everything.
+
+### 2. Switch Message Brokers Instantly
+
+Want to use a different message broker? Just change the channel builder:
+
+| Message Broker | Configuration | Package |
+|----------------|---------------|---------|
+| **RabbitMQ** | `AmqpBackedMessageChannelBuilder::create('orders')` | `ecotone/amqp` |
+| **Amazon SQS** | `SqsBackedMessageChannelBuilder::create('orders')` | `ecotone/sqs` |
+| **Redis** | `RedisBackedMessageChannelBuilder::create('orders')` | `ecotone/redis` |
+| **Kafka** | `KafkaMessageChannelBuilder::create('orders')` | `ecotone/kafka` |
+| **Database** | `DbalBackedMessageChannelBuilder::create('orders')` | `ecotone/dbal` |
+
+Your business logic remains **completely unchanged**. The `#[Asynchronous('orders')]` attribute works with any of these brokers.
+
+### 3. Type-Safe Commands
+
+Use proper PHP classes for your messages instead of raw arrays:
+
+```php
+class PlaceOrder
+{
+    public function __construct(
+        public string $orderId,
+        public string $product
+    ) {}
+}
+
+// Send type-safe command
+$ecotone->getCommandBus()->send(new PlaceOrder('123', 'Milk'));
+```
+
+Ecotone automatically serializes and deserializes your objects.
+
+## How It Works Under the Hood
+
+### Publishing Flow
+
+1. **Send Command** → `CommandBus::send(new PlaceOrder(...))`
+2. **Serialize** → Command is converted to JSON (or other format)
+3. **Publish** → Message is sent to RabbitMQ queue named `orders`
+
+### Consuming Flow
+
+1. **Poll** → Consumer calls `$ecotone->run('orders')`
+2. **Receive** → Message is fetched from RabbitMQ queue
+3. **Deserialize** → JSON is converted back to `PlaceOrder` object
+4. **Invoke Handler** → `OrderHandler::handle(PlaceOrder $command)` is called
+5. **Acknowledge** → Message is removed from queue on success
+
+### The Asynchronous Attribute
+
+```php
+#[Asynchronous('orders')]
+#[CommandHandler(endpointId: 'orderHandler')]
+public function handle(PlaceOrder $command): void
+{
+    // This runs in the consumer process, not the publisher
+}
+```
+
+- `#[Asynchronous('orders')]` - Routes the command to the `orders` message channel
+- `#[CommandHandler]` - Registers this method as a command handler
+- `endpointId` - Unique identifier for this endpoint (required for async handlers)
+
+### Message Channel Architecture
+
+```
+┌──────────────┐     ┌─────────────────┐     ┌──────────────┐
+│  Publisher   │────▶│  Message Broker │────▶│   Consumer   │
+│  (PHP CLI)   │     │   (RabbitMQ)    │     │  (PHP CLI)   │
+└──────────────┘     └─────────────────┘     └──────────────┘
+       │                                              │
+       ▼                                              ▼
+  CommandBus                                    CommandHandler
+  .send(PlaceOrder)                            .handle(PlaceOrder)
+```
+
+## Try It Yourself
+
+1. **Clone this repository** and run the example
+2. **Check RabbitMQ Management UI** at `http://localhost:15672` (guest/guest)
+3. **Modify the handler** to see how messages are processed
+4. **Switch to a different broker** by changing one line
+
+## Learn More
+
+- 📚 [Ecotone Documentation](https://docs.ecotone.tech)
+
+## Keywords
+
+PHP Message Queue, RabbitMQ PHP, Kafka PHP, Amazon SQS PHP, Redis Pub/Sub PHP, Async PHP, PHP Message Broker, PHP Event-Driven Architecture, CQRS PHP, PHP Microservices, Ecotone Framework, PHP Messaging, Asynchronous PHP Processing, PHP Queue System, PHP Event Bus

quickstart-examples/MessageBroker/composer.json

@@ -0,0 +1,33 @@
+{
+    "name": "ecotone/message-broker-quickstart",
+    "license": "MIT",
+    "authors": [
+        {
+            "name": "Dariusz Gafka",
+            "email": "[email protected]"
+        }
+    ],
+    "require": {
+        "ecotone/lite-amqp-starter": "^1.0.1"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^9.6|^10.5|^11.0",
+        "wikimedia/composer-merge-plugin": "^2.1"
+    },
+    "config": {
+        "sort-packages": true,
+        "allow-plugins": {
+            "wikimedia/composer-merge-plugin": true
+        }
+    },
+    "extra": {
+        "merge-plugin": {
+            "include": [
+                "../../packages/local_packages.json"
+            ]
+        }
+    },
+    "minimum-stability": "dev",
+    "prefer-stable": true
+}
+

quickstart-examples/MessageBroker/consumer.php

@@ -0,0 +1,52 @@
+<?php
+
+use Ecotone\Amqp\AmqpBackedMessageChannelBuilder;
+use Ecotone\Lite\EcotoneLite;
+use Ecotone\Messaging\Attribute\Asynchronous;
+use Ecotone\Messaging\Config\ServiceConfiguration;
+use Ecotone\Messaging\Endpoint\ExecutionPollingMetadata;
+use Ecotone\Modelling\Attribute\CommandHandler;
+use Enqueue\AmqpExt\AmqpConnectionFactory;
+
+require __DIR__ . "/vendor/autoload.php";
+
+// Command class - same definition must exist in publisher.php
+class PlaceOrder
+{
+    public function __construct(
+        public string $orderId,
+        public string $product
+    ) {}
+}
+
+// Handler class - same definition must exist in publisher.php
+class OrderHandler
+{
+    #[Asynchronous('orders')]
+    #[CommandHandler(endpointId: 'orderHandler')]
+    public function handle(PlaceOrder $command): void
+    {
+        // This runs when consumer processes the message
+        echo "Processing order {$command->orderId}: {$command->product}\n";
+    }
+}
+
+$channelName = 'orders';
+
+$ecotone = EcotoneLite::bootstrap(
+    classesToResolve: [PlaceOrder::class, OrderHandler::class],
+    containerOrAvailableServices: [
+        new OrderHandler(),
+        AmqpConnectionFactory::class => new AmqpConnectionFactory([
+            'dsn' => getenv('RABBIT_HOST') ?: 'amqp://guest:guest@localhost:5672/%2f'
+        ]),
+    ],
+    configuration: ServiceConfiguration::createWithDefaults()
+        ->withExtensionObjects([
+            AmqpBackedMessageChannelBuilder::create($channelName),
+        ])
+);
+
+echo "Starting consumer for queue '{$channelName}'...\n";
+$ecotone->run($channelName, ExecutionPollingMetadata::createWithDefaults()->withHandledMessageLimit(1));
+echo "Consumer finished.\n";

quickstart-examples/MessageBroker/publisher.php

@@ -0,0 +1,52 @@
+<?php
+
+use Ecotone\Amqp\AmqpBackedMessageChannelBuilder;
+use Ecotone\Lite\EcotoneLite;
+use Ecotone\Messaging\Attribute\Asynchronous;
+use Ecotone\Messaging\Config\ServiceConfiguration;
+use Ecotone\Modelling\Attribute\CommandHandler;
+use Enqueue\AmqpExt\AmqpConnectionFactory;
+use Ramsey\Uuid\Uuid;
+
+require __DIR__ . "/vendor/autoload.php";
+
+// Command class - same definition must exist in consumer.php
+class PlaceOrder
+{
+    public function __construct(
+        public string $orderId,
+        public string $product
+    ) {}
+}
+
+// Handler class - same definition must exist in consumer.php
+class OrderHandler
+{
+    #[Asynchronous('orders')]
+    #[CommandHandler(endpointId: 'orderHandler')]
+    public function handle(PlaceOrder $command): void
+    {
+        // This runs asynchronously when consumer processes the message
+        echo "Processing order {$command->orderId}: {$command->product}\n";
+    }
+}
+
+$channelName = 'orders';
+
+$ecotone = EcotoneLite::bootstrap(
+    classesToResolve: [PlaceOrder::class, OrderHandler::class],
+    containerOrAvailableServices: [
+        new OrderHandler(),
+        AmqpConnectionFactory::class => new AmqpConnectionFactory([
+            'dsn' => getenv('RABBIT_HOST') ?: 'amqp://guest:guest@localhost:5672/%2f'
+        ]),
+    ],
+    configuration: ServiceConfiguration::createWithDefaults()
+        ->withExtensionObjects([
+            AmqpBackedMessageChannelBuilder::create($channelName),
+        ])
+);
+
+$ecotone->getCommandBus()->send(new PlaceOrder(Uuid::uuid4()->toString(), 'Milk'));
+
+echo "Message sent to queue '{$channelName}'\n";

quickstart-examples/composer.json

@@ -33,6 +33,7 @@
             "(cd EventSourcing && composer update && php run_example.php)",
             "(cd EventProjecting/PartitionedProjection && composer update && php run_example.php)",
             "(cd WorkingWithAggregateDirectly && composer update && php run_example.php)",
+            "(cd MessageBroker && composer update && php publisher.php && php consumer.php)",
             "(cd Microservices && composer update && php run_example.php)",
             "(cd MicroservicesAdvanced && composer update && php run_example.php)",
             "(cd Schedule && composer update && php run_example.php)",

quickstart-examples/docker-compose.yml

@@ -10,7 +10,7 @@ services:
     working_dir: "/data/app"
     command: sleep 999999
     environment:
-      RABBIT_HOST: "amqp://rabbitmq:5672"
+      RABBIT_HOST: "amqp://guest:guest@rabbitmq:5672/%2f"
       DATABASE_DSN: pgsql://ecotone:secret@database:5432/ecotone
       SECONDARY_DATABASE_DSN: mysql://ecotone:secret@database-mysql:3306/ecotone
     networks: