Ecotone

https://docs.ecotone.tech
Admin
Ecotone is a PHP framework that brings focus back to message-driven communication and application...
Tokens:198,313
Snippets:1,841
Trust Score:6
Update:9 months ago
Show doc for...
Tokens:
Raw
### Ecotone Quickstart Example - Laravel

Source: https://docs.ecotone.tech/tutorial-php-ddd-cqrs-event-sourcing/php-messaging-architecture

This snippet points to the Ecotone quickstart example file within a Laravel project. It guides the user to the specific file location ('app/EcotoneQuickstart.php') for the Laravel integration.

```php
Go to "app/EcotoneQuickstart.php"


```

--------------------------------

### Run Ecotone Quickstart Example

Source: https://docs.ecotone.tech/tutorial-php-ddd-cqrs-event-sourcing/php-asynchronous-processing

This command-line instruction shows how to execute the Ecotone quickstart example with verbose output. It's used to verify the successful running of a scenario and view its output, such as a price and a success message.

```bash
bin/console ecotone:quickstart -vvv
```

--------------------------------

### Ecotone Command Bus Quickstart Execution

Source: https://docs.ecotone.tech/tutorial-php-ddd-cqrs-event-sourcing/php-interceptors-middlewares

This example demonstrates the output of running an Ecotone quickstart command after the transaction interceptor has been configured. It shows the sequence of transaction start, commit, and the final success message, indicating that the commands were processed within transactional boundaries.

```bash
bin/console ecotone:quickstart
Start transaction
Product with id 1 was registered!
Commit transaction
Start transaction
Commit transaction
110
Good job, scenario ran with success!
```

--------------------------------

### Ecotone Quickstart Example - Symfony

Source: https://docs.ecotone.tech/tutorial-php-ddd-cqrs-event-sourcing/php-messaging-architecture

This snippet indicates the location of the Ecotone quickstart example within a Symfony project. It notes that the EcotoneQuickstart.php class is auto-registered via Symfony's autowiring feature, simplifying integration within the framework.

```php
Go to "src/EcotoneQuickstart.php"

# This class is autoregistered using Symfony Autowire
```

--------------------------------

### Execute Quickstart Command

Source: https://docs.ecotone.tech/tutorial-php-ddd-cqrs-event-sourcing/php-metadata-method-invocation

This command executes the Ecotone quickstart script, which runs the example scenarios defined in the lesson. It's used to verify the implementation of metadata and method invocation, including permission checks.

```bash
bin/console ecotone:quickstart
```

--------------------------------

### Run Ecotone Quickstart Command

Source: https://docs.ecotone.tech/tutorial-php-ddd-cqrs-event-sourcing/php-domain-driven-design

Executes the Ecotone quickstart console command to run tests and examples. This command verifies the setup and demonstrates successful execution.

```bash
bin/console ecotone:quickstart
Running example...
100
Good job, scenario ran with success!
```

--------------------------------

### Ecotone Quickstart Command Output

Source: https://docs.ecotone.tech/tutorial-php-ddd-cqrs-event-sourcing/php-messaging-architecture

Demonstrates the output of the 'bin/console ecotone:quickstart' command, showing a successful execution with a 'Hello World' message. This serves as a verification step for the initial setup and confirms that the Ecotone environment is ready for use.

```bash
bin/console ecotone:quickstart
"Running example...
Hello World
Good job, scenario ran with success!"
```

--------------------------------

### Run Ecotone Quickstart Command After Event Publishing Setup

Source: https://docs.ecotone.tech/tutorial-php-ddd-cqrs-event-sourcing/php-domain-driven-design

Re-runs the Ecotone quickstart command after implementing event publishing. This execution confirms that the `ProductWasRegisteredEvent` is now correctly published and processed.

```bash
bin/console ecotone:quickstart
Running example...
Product with id 1 was registered!
100
Good job, scenario ran with success!
```

--------------------------------

### Install Ecotone Lite using Composer

Source: https://docs.ecotone.tech/install-php-service-bus

Installs the core Ecotone Lite package for use in projects without a specific framework integration or with custom frameworks. Requires Composer and a PSR-4 or PSR-0 autoload setup.

```bash
composer require ecotone/ecotone
```

--------------------------------

### Install Ecotone Lite Application using Composer

Source: https://docs.ecotone.tech/install-php-service-bus

Installs the Ecotone Lite Application package, which provides a pre-configured dependency injection container. This simplifies bootstrapping Ecotone in standalone projects.

```bash
composer require ecotone/lite-application
```

--------------------------------

### Bootstrap Ecotone Lite Application

Source: https://docs.ecotone.tech/install-php-service-bus

Initializes the Ecotone Lite Application, which automatically sets up the dependency container and Ecotone. This provides convenient access to the command and query buses.

```php
$ecotoneLite = EcotoneLiteApplication::bootstrap();

$commandBus = $ecotoneLite->getCommandBus();
$queryBus = $ecotoneLite->getQueryBus();
```

--------------------------------

### Install Ecotone Symfony Bundle using Composer

Source: https://docs.ecotone.tech/install-php-service-bus

Installs the Ecotone Symfony Bundle using Composer. This is the first step for integrating Ecotone with a Symfony project. Ensure Composer is installed and your project uses PSR-4 autoloading.

```bash
composer require [ecotone/](https://packagist.org/packages/ecotone/)symfony-bundle
```

--------------------------------

### Basic Kafka Consumer Setup

Source: https://docs.ecotone.tech/modules/kafka-support/kafka-consumer

Demonstrates the basic setup for a Kafka Consumer by marking a method with the KafkaConsumer attribute. This enables asynchronous consumption of messages from specified topics. It requires the endpointId and topics to be defined.

```php
#[KafkaConsumer(
    endpointId: 'orderConsumers',
    topics: ['orders']
)]
public function handle(string $payload, array $metadata): void
{
    // do something
}
```

--------------------------------

### Verify Ecotone Symfony Installation

Source: https://docs.ecotone.tech/install-php-service-bus

Runs a console command to verify that Ecotone is correctly installed and configured within a Symfony project. This command helps confirm the integration is successful.

```bash
php bin/console ecotone:list
```

--------------------------------

### Bootstrap Ecotone Lite without Dependency Container

Source: https://docs.ecotone.tech/install-php-service-bus

Initializes Ecotone Lite by resolving specified classes and providing a list of available service instances directly. This approach is useful for simpler applications or testing scenarios.

```php
$ecotoneLite = EcotoneLite::bootstrap(
    classesToResolve: [User::class, UserRepository::class, UserService::class],
    containerOrAvailableServices: [new UserRepository(), new UserService()]
);
```

--------------------------------

### Bootstrap Ecotone Lite with Custom Container

Source: https://docs.ecotone.tech/install-php-service-bus

Initializes Ecotone Lite by resolving specified classes and providing an existing dependency injection container. This is for scenarios where you manage your own container.

```php
$ecotoneLite = EcotoneLite::bootstrap(
    classesToResolve: [User::class, UserRepository::class, UserService::class],
    containerOrAvailableServices: $container
);
```

--------------------------------

### Start Local Development Environment with Docker

Source: https://docs.ecotone.tech/messaging/contributing-to-ecotone

This snippet shows how to initialize and manage the Ecotone development environment using Docker Compose. It covers starting, stopping, and rebuilding containers, as well as running tests within the development environment.

```bash
docker-compose up -d
docker-compose down
```

--------------------------------

### Running Ecotone Kafka Message Consumers

Source: https://docs.ecotone.tech/modules/kafka-support/message-partitioning

These commands show how to run the Ecotone message consumer process for a Kafka channel named 'users'. Examples are provided for Symfony, Laravel, and a generic 'Lite' setup, all using the '-vvv' flag for verbose output.

```bash
# Symfony
bin/console ecotone:run users -vvv
```

```bash
# Laravel
artisan ecotone:run users -vvv
```

```php
// Lite
$messagingSystem->run("users");
```

--------------------------------

### Bootstrap Ecotone Lite with Custom Container and Namespaces

Source: https://docs.ecotone.tech/install-php-service-bus

Configures Ecotone Lite to bootstrap with a custom container and explicitly define namespaces to scan for attributes. This provides more control over where Ecotone looks for service definitions.

```php
$ecotoneLite = EcotoneLite::bootstrap(
    classesToResolve: [User::class, UserRepository::class, UserService::class],
    containerOrAvailableServices: $container,
    configuration: ServiceConfiguration::createWithDefaults()->withNamespaces(['App'])
);
```

--------------------------------

### Install Doctrine DBAL for Persistence

Source: https://docs.ecotone.tech/tutorial-php-ddd-cqrs-event-sourcing/php-interceptors-middlewares

This command installs the doctrine/dbal library, which is used to abstract database operations and provides a convenient way to interact with SQLite.

```bash
composer require doctrine/dbal
```

--------------------------------

### Install Ecotone SQS Package

Source: https://docs.ecotone.tech/modules/amazon-sqs-support

This command installs the Ecotone SQS support package using Composer. It's the first step to enable SQS integration within your Ecotone application.

```php
composer require ecotone/sqs
```

--------------------------------

### Get SQL Statements for Ecotone Tech Database Setup

Source: https://docs.ecotone.tech/modelling/migrations-storage

Retrieves the raw SQL statements for setting up Ecotone Tech database tables. This is useful for integrating with existing database migration tools. SQL can be generated for all used features or for specific features.

```bash
# Get SQL for all used features (Symfony)
bin/console ecotone:migration:database:setup --sql=true

# Get SQL for specific features (Symfony)
bin/console ecotone:migration:database:setup --feature=dead_letter --sql=true
```

```bash
# Get SQL for all used features (Laravel)
php artisan ecotone:migration:database:setup --sql=true

# Get SQL for specific features (Laravel)
php artisan ecotone:migration:database:setup --feature=dead_letter --sql=true
```

```php
// Get SQL for all used features (Lite)
$result = $messagingSystem->runConsoleCommand('ecotone:migration:database:setup', ['sql' => true]);

// Get SQL for specific features (Lite)
$result = $messagingSystem->runConsoleCommand('ecotone:migration:database:setup', [
    'feature' => ['dead_letter'],
    'sql' => true
]);
```

--------------------------------

### Doctrine ORM Example Repository Implementation

Source: https://docs.ecotone.tech/modelling/command-handling/repository/configure-repository

Provides an example implementation of the `StandardRepository` interface using Doctrine ORM. This `EcotoneTicketRepository` demonstrates how to integrate with Doctrine's `EntityManagerInterface` to handle `Ticket` aggregates, including checking if it can handle the class, finding by identifiers, and saving the aggregate.

```php
final class EcotoneTicketRepository implements StandardRepository
{
    public function __construct(private readonly EntityManagerInterface $entityManager)
    {
    }

    public function canHandle(string $aggregateClassName): bool
    {
        return $aggregateClassName === Ticket::class;
    }

    public function findBy(string $aggregateClassName, array $identifiers): ?object
    {
        return $this->entityManager->getRepository(Ticket::class)
                    // Array of identifiers for given Aggregate
                    ->find($identifiers['ticketId']);
    }

    public function save(array $identifiers, object $aggregate, array $metadata, ?int $versionBeforeHandling): void
    {
        $this->entityManager->persist($aggregate);
    }
}
```

--------------------------------

### Register ProductService in Bootstrap

Source: https://docs.ecotone.tech/tutorial-php-ddd-cqrs-event-sourcing/php-domain-driven-design

Registers the InMemoryProductRepository as a singleton instance within the application's service container. This setup is typically done in a Service Provider class.

```php
namespace Bootstrap;

use App\Domain\Product\InMemoryProductRepository;
use Illuminate\Support\ServiceProvider;

class QuickStartProvider extends ServiceProvider
{
    public function register()
    {
        $this->app->singleton(InMemoryProductRepository::class, function(){
            return new InMemoryProductRepository();
        });
    }
}
```

--------------------------------

### Execute Console Command with Options

Source: https://docs.ecotone.tech/messaging/console-commands

Examples of executing the 'sendEmail' console command with an option '--type'. This shows how to pass named parameters to your console commands.

```bash
bin/console sendEmail "test@example.com" --type="welcome"
```

```bash
php artisan sendEmail "test@example.com" --type="welcome"
```

```php
$messagingSystem->runConsoleCommand(
   'sendEmail',
   [
      "email" => "test@example.com",
       "type" => "welcome"
   ]
)
```

--------------------------------

### Verify Ecotone Laravel Installation

Source: https://docs.ecotone.tech/install-php-service-bus

Executes an Artisan command to confirm that Ecotone has been successfully installed and integrated into the Laravel application. This command is crucial for validating the setup.

```bash
php artisan ecotone:list
```

--------------------------------

### Ecotone Quickstart Test Class

Source: https://docs.ecotone.tech/tutorial-php-ddd-cqrs-event-sourcing/php-asynchronous-processing

Demonstrates how to use the CommandBus and QueryBus to register products and place an order, then retrieve the total price. This class serves as a basic integration test for the order placement functionality.

```php
use Ecotone\Messaging\Config\InMemoryChannelConfiguration;
use Ecotone\Messaging\Handler\CommandBus;
use Ecotone\Messaging\Handler\InMemoryMessageConverter;
use Ecotone\Messaging\Handler\QueryBus;
use Ecotone\Messaging\MediaType;
use Ecotone\SymfonyFiber\EcotoneSetup;

class EcotoneQuickstart
{
    private CommandBus $commandBus;
    private QueryBus $queryBus;

    public function __construct(CommandBus $commandBus, QueryBus $queryBus)
    {
        $this->commandBus = $commandBus;
        $this->queryBus = $queryBus;
    }

    public function run() : void
    {
        $this->commandBus->sendWithRouting(
            "product.register",
            ["productId" => 1, "cost" => 100]
        );
        $this->commandBus->sendWithRouting(
            "product.register",
            ["productId" => 2, "cost" => 300]
        );

        $orderId = 100;
        $this->commandBus->sendWithRouting(
            "order.place",
            ["orderId" => $orderId, "productIds" => [1,2]]
        );

        echo $this->queryBus->convertAndSend("order.getTotalPrice", MediaType::APPLICATION_X_PHP_ARRAY, ["orderId" => $orderId]);
    }
}
```

--------------------------------

### Install Ecotone Laravel Package using Composer

Source: https://docs.ecotone.tech/install-php-service-bus

Installs the Ecotone Laravel package using Composer. This is the initial step for integrating Ecotone with a Laravel project. Composer must be installed, and PSR-4 autoloading should be configured.

```bash
composer require [ecotone/](https://packagist.org/packages/ecotone/)laravel
```

--------------------------------

### Initialize and Delete Ecotone Channels with PHP

Source: https://docs.ecotone.tech/modelling/migrations-storage

Demonstrates how to use Ecotone Lite to run channel migration commands for setup and deletion. This involves bootstrapping Ecotone Lite with necessary configurations, executing console commands to initialize or delete database and channel migrations, and then running tests. Cleanup is handled by deleting resources.

```php
use Ecotone\Lite\EcotoneLite;
use Ecotone\Dbal\Configuration\DbalConfiguration;
use Ecotone\Messaging\Channel\Manager\ChannelInitializationConfiguration;

$ecotone = EcotoneLite::bootstrapFlowTesting(
    containerOrAvailableServices: [
        DbalConnectionFactory::class => $connectionFactory,
    ],
    configuration: ServiceConfiguration::createWithDefaults()
        ->withExtensionObjects([
            DbalConfiguration::createWithDefaults()
                ->withAutomaticTableInitialization(false),
            ChannelInitializationConfiguration::createWithDefaults()
                ->withAutomaticChannelInitialization(false),
        ])
);

// Initialize storage in test setup
$ecotone->runConsoleCommand('ecotone:migration:database:setup', ['initialize' => true]);
$ecotone->runConsoleCommand('ecotone:migration:channel:setup', ['initialize' => true]);

// Run your tests...

// Clean up in teardown
$ecotone->runConsoleCommand('ecotone:migration:database:delete', ['force' => true]);
$ecotone->runConsoleCommand('ecotone:migration:channel:delete', ['force' => true]);
```

--------------------------------

### Configure AmqpConnectionFactory (Lite - Docker)

Source: https://docs.ecotone.tech/tutorial-php-ddd-cqrs-event-sourcing/php-asynchronous-processing

This 'Lite' approach example configures the AmqpConnectionFactory for a Dockerized environment, connecting to a RabbitMQ instance identified as 'rabbitmq'. The configuration is done directly within the bin/console.php.

```php
# Add AmqpConnectionFactory in bin/console.php

// add additional service in container
public function __construct()
{
   $this->container = new Container();
   $this->container->set(Enqueue\AmqpExt\AmqpConnectionFactory::class, new Enqueue\AmqpExt\AmqpConnectionFactory("amqp+lib://guest:guest@rabbitmq:5672//"));
}

```

--------------------------------

### Install Ecotone Event Sourcing Support (PHP)

Source: https://docs.ecotone.tech/modelling/event-sourcing/installation

Installs the Ecotone PDO Event Sourcing module via composer. This module provides components for setting up Event Sourcing and supports PostgreSQL, MySQL, and MariaDB.

```php
composer require ecotone/pdo-event-sourcing
```

--------------------------------

### Testing Command Bus Interactions (PHP)

Source: https://docs.ecotone.tech/tutorial-php-ddd-cqrs-event-sourcing/php-metadata-method-invocation

Illustrates how to interact with Ecotone's command and query buses to send commands and queries. This example demonstrates sending a 'product.register' command, a 'product.changePrice' command, and a 'product.getCost' query, simulating a user workflow with necessary metadata.

```php
public function run() : void
{
    $this->commandBus->sendWithRouting(
        "product.register",
        \json_encode(["productId" => 1, "cost" => 100]),
        "application/json",
        [
            "userId" => 1
        ]
    );

    $this->commandBus->sendWithRouting(
        "product.changePrice",
        \json_encode(["productId" => 1, "cost" => 110]),
        "application/json",
        [
            "userId" => 1
        ]
    );

    echo $this->queryBus->sendWithRouting("product.getCost", \json_encode(["productId" => 1]), "application/json");
}
```

--------------------------------

### Install Ecotone JMS Converter Support (PHP)

Source: https://docs.ecotone.tech/modelling/event-sourcing/installation

Installs the Ecotone JMS converter module via composer, enabling automatic serialization and deserialization of Events. This simplifies focusing on business logic by handling the conversion process.

```php
composer require ecotone/jms-converter
```

--------------------------------

### Execute Testing Commands with CommandBus

Source: https://docs.ecotone.tech/tutorial-php-ddd-cqrs-event-sourcing/php-asynchronous-processing

This PHP code demonstrates the usage of `CommandBus` to send commands for registering products and placing an order. It also shows how to query for the total order price. This is typically used in testing scenarios.

```php
public function run() : void
{
    $this->commandBus->sendWithRouting(
        "product.register",
        ["productId" => 1, "cost" => 100]
    );
    $this->commandBus->sendWithRouting(
        "product.register",
        ["productId" => 2, "cost" => 300]
    );

    $orderId = 990;
    $this->commandBus->sendWithRouting(
        "order.place",
        ["orderId" => $orderId, "productIds" => [1,2]]
    );

    echo $this->queryBus->sendWithRouting("order.getTotalPrice", ["orderId" => $orderId]);
}
```

--------------------------------

### Bootstrap Ecotone Lite with Logger Service

Source: https://docs.ecotone.tech/modules/ecotone-lite/logging

Demonstrates how to initialize Ecotone Lite and inject a PSR compatible Logger service. The logger should be provided under the 'logger' reference, either directly or through a dependency container.

```php
$ecotoneLite = EcotoneLite::bootstrap(
    [OrderService::class],
    containerOrAvailableServices: [
        // pass your Logger here
        'logger' => $loggerService,
    ]
)
```

--------------------------------

### Configure Service Mapping for Commands and Events (PHP)

Source: https://docs.ecotone.tech/modelling/microservices-php/distributed-bus/distributed-bus-with-service-map

This snippet demonstrates how to initialize a DistributedServiceMap and define mappings for commands and events to specific services and channels. It requires the `#[ServiceContext]` attribute and uses methods like `withCommandMapping` and `withEventMapping`. The output is a configured `DistributedServiceMap` object.

```php
<?php

use Ecotone\Attribute\ServiceContext;
use Ecotone\DistributedBus\DistributedServiceMap;

#[ServiceContext]
public function serviceMap(): DistributedServiceMap
{
    return DistributedServiceMap::initialize()
              // Map commands to specific service
              ->withCommandMapping(
                        targetServiceName: "ticketService",
                        channelName: "distributed_ticket_service"
              )
              // Subscribe to events from other services
              ->withEventMapping(
                        channelName: "distributed_ticket_service",
                        subscriptionKeys: ["user.*", "order.created"],
              );
}

```

--------------------------------

### Query Business Methods - Get Person IDs

Source: https://docs.ecotone.tech/modelling/command-handling/business-interface/working-with-database

Example of a DbalQueryBusinessMethod using FetchMode::FIRST_COLUMN to retrieve only the 'person_id' column.

```APIDOC
## GET /api/persons/ids

### Description
Fetches a list of person IDs from the 'persons' table, ordered by ID, with pagination.

### Method
GET

### Endpoint
/api/persons/ids

### Parameters
#### Query Parameters
- **limit** (int) - Optional - The maximum number of IDs to return. Defaults to a system-defined value.
- **offset** (int) - Optional - The number of IDs to skip. Defaults to 0.

### Response
#### Success Response (200)
- **ids** (array) - An array of person IDs (integers).

#### Response Example
```json
{
  "ids": [
    1,
    2,
    3
  ]
}
```
```

--------------------------------

### Install Ecotone and Enqueue SQS Packages

Source: https://docs.ecotone.tech/messaging/contributing-to-ecotone/demo-integration-with-sqs/preparation

This bash command installs the necessary composer packages for integrating Ecotone with Amazon SQS via the enqueue/sqs library. It first requires the 'enqueue/sqs' package and then the 'ecotone/enqueue' package, enabling Ecotone's messaging capabilities with SQS.

```bash
composer require enqueue/sqs && composer require ecotone/enqueue
```

--------------------------------

### Bootstrap Ecotone Lite with Dependencies (PHP)

Source: https://docs.ecotone.tech/modelling/testing-support/testing-messaging

Demonstrates how to bootstrap Ecotone Lite for testing by explicitly providing necessary services to the dependency injection container. This resolves 'Service not found' errors.

```php
$ecotoneLite = EcotoneLite::bootstrapFlowTesting(
    [UserService::class],
    [
        UserRepository::class => new InMemoryUserRepository(),
        EmailService::class => new MockEmailService(),
        // Add all services your handlers depend on
    ]
);
```

--------------------------------

### Query Business Methods - Count Persons

Source: https://docs.ecotone.tech/modelling/command-handling/business-interface/working-with-database

Example of a DbalQueryBusinessMethod using FetchMode::FIRST_COLUMN_OF_FIRST_ROW to get a single aggregate value (count).

```APIDOC
## GET /api/persons/count

### Description
Retrieves the total count of persons in the 'persons' table.

### Method
GET

### Endpoint
/api/persons/count

### Response
#### Success Response (200)
- **count** (int) - The total number of persons.

#### Response Example
```json
{
  "count": 150
}
```
```

--------------------------------

### Configure AmqpConnectionFactory (Lite - Local)

Source: https://docs.ecotone.tech/tutorial-php-ddd-cqrs-event-sourcing/php-asynchronous-processing

This 'Lite' approach configures the AmqpConnectionFactory directly within the bin/console.php file for local development. It manually sets the factory as a singleton in a custom container.

```php
# Add AmqpConnectionFactory in bin/console.php

// add additional service in container
public function __construct()
{
   $this->container = new Container();
   $this->container->set(Enqueue\AmqpExt\AmqpConnectionFactory::class, new Enqueue\AmqpExt\AmqpConnectionFactory("amqp+lib://guest:guest@localhost:5672//"));
}



```

--------------------------------

### Ecotone Lite Saga Test Setup

Source: https://docs.ecotone.tech/modelling/business-workflows/sagas

Shows how to set up Ecotone Lite for testing sagas. This involves bootstrapping the testing environment with the relevant saga class and preparing it to handle events and queries for state verification.

```php
use EcotoneLiteEcotoneLite;
use PHPUnit\Framework\TestCase;

class OrderProcessSagaTest extends TestCase
{
    private EcotoneLite $ecotoneLite;

    protected function setUp(): void
    {
        $this->ecotoneLite = EcotoneLite::bootstrapFlowTesting(
            [OrderProcess::class],
            [],
        );
    }

    public function test_saga_initialization(): void
    {
        // Act - Trigger saga creation
        $event = new OrderWasPlaced('order-123');
        $this->ecotoneLite->publishEvent($event);

        // Assert - Verify saga was created and can be queried
        $status = $this->ecotoneLite->sendQueryWithRouting(
            'order.getStatus',
            metadata: ['aggregate.id' => 'order-123']
        );

        $this->assertEquals('order-123', $status['orderId']);
        $this->assertEquals('PLACED', $status['status']);
        $this->assertFalse($status['isPaid']);
        $this->assertFalse($status['isShipped']);
    }
}
```

--------------------------------

### Query Business Methods - Get Person Name List

Source: https://docs.ecotone.tech/modelling/command-handling/business-interface/working-with-database

Example of a DbalQueryBusinessMethod to fetch a list of names from the 'persons' table with pagination.

```APIDOC
## GET /api/persons

### Description
Fetches a list of persons from the 'persons' table with support for pagination.

### Method
GET

### Endpoint
/api/persons

### Parameters
#### Query Parameters
- **limit** (int) - Optional - The maximum number of persons to return. Defaults to a system-defined value.
- **offset** (int) - Optional - The number of persons to skip. Defaults to 0.

### Response
#### Success Response (200)
- **persons** (array) - An array of person objects, where each object contains 'person_id' and 'name'.

#### Response Example
```json
{
  "persons": [
    {
      "person_id": 1,
      "name": "John Doe"
    },
    {
      "person_id": 2,
      "name": "Jane Smith"
    }
  ]
}
```
```

--------------------------------

### Send Commands with Metadata (Symfony/Laravel & Lite)

Source: https://docs.ecotone.tech/modelling/command-handling/external-command-handlers

Demonstrates sending commands with metadata (executorId) using the Command Bus in both Symfony/Laravel and a 'Lite' PHP setup. This allows for passing contextual information that doesn't belong in the command itself.

```php
class TicketController
{
   public function __construct(private CommandBus $commandBus) {}
   
   public function closeTicketAction(Request $request, Security $security) : Response
   {
      $this->commandBus->send(
         new CloseTicketCommand($request->get("ticketId")),
         ["executorId" => $security->getUser()->getId()]
      );
   }
}
```

```php
$messagingSystem->getCommandBus()->send(
   new CloseTicketCommand($ticketId),
   ["executorId" => $executorId]
);
```

--------------------------------

### Send Message with Tenant Context in PHP

Source: https://docs.ecotone.tech/messaging/multi-tenancy-support/getting-started/any-framework-configuration

This PHP example illustrates how to send a command with tenant context using message headers. The 'tenant' header is used to specify which tenant the command should be executed for, leveraging the previously configured mapping.

```php
final readonly class CustomerController extends Controller
{
    public function __construct(private CommandBus $commandBus) {}
    
    public function placeOrder(Request $request): Response
    {
        $this->commandBus->send(
            new RegisterCustomer($request->get('name')),
            metadata: [
                // This is the Message Header that will be used for mapping tenant
                'tenant' => 'tenant_a'
            ]  
        );
        
        return new Response(200);        
    }
}
```

--------------------------------

### Query Business Methods - Get Person Name DTO

Source: https://docs.ecotone.tech/modelling/command-handling/business-interface/working-with-database

Example of a DbalQueryBusinessMethod using FetchMode::FIRST_ROW to fetch a single row as an associative array.

```APIDOC
## GET /api/persons/{personId}

### Description
Fetches a single person's details (ID and name) from the 'persons' table by their ID.

### Method
GET

### Endpoint
/api/persons/{personId}

### Parameters
#### Path Parameters
- **personId** (int) - Required - The ID of the person to retrieve.

### Response
#### Success Response (200)
- **person** (object) - An object containing 'person_id' and 'name'.

#### Response Example
```json
{
  "person": {
    "person_id": 1,
    "name": "John Doe"
  }
}
```
```

--------------------------------

### Register Product Command Handler in PHP

Source: https://docs.ecotone.tech/tutorial-php-ddd-cqrs-event-sourcing/php-serialization-deserialization

Handles the registration of a product by creating a new instance with the provided product ID and cost. It takes a RegisterProductCommand object as input and returns an instance of the current class.

```php
public static function register(RegisterProductCommand $command) : self
    {
        return new self($command->getProductId(), $command->getCost());
    }
```

--------------------------------

### Set RabbitMQ Stream Consumer Start Position - PHP

Source: https://docs.ecotone.tech/modules/amqp-support-rabbitmq/message-channel

These PHP snippets illustrate how to configure the `startPosition` for an AmqpStreamChannelBuilder. The first example sets it to 'first' to replay all events, while the second sets it to 'last' to only consume new events. Both examples specify the channel name, queue name, and a unique message group ID.

```php
// Start from the beginning (replay all events)
AmqpStreamChannelBuilder::create(
    channelName: "events",
    startPosition: "first",
    queueName: "events_stream",
    messageGroupId: "replay-consumer"
)

// Start from the end (only new events)
AmqpStreamChannelBuilder::create(
    channelName: "events",
    startPosition: "last",
    queueName: "events_stream",
    messageGroupId: "new-events-consumer"
)
```

--------------------------------

### Register Ecotone Symfony Bundle Manually

Source: https://docs.ecotone.tech/install-php-service-bus

Manually registers the Ecotone Symfony Bundle in `config/bundles.php` if Symfony Flex auto-configuration does not work. This ensures the bundle is recognized by the Symfony application.

```php
Ecotone\SymfonyBundle\EcotoneSymfonyBundle::class => ['all' => true]
```

--------------------------------

### Create and Configure AMQP Queues in PHP

Source: https://docs.ecotone.tech/modules/amqp-support-rabbitmq/message-publisher

Illustrates the creation and configuration of AMQP queues. Options include setting durability, exclusivity, auto-deletion, and linking to a dead-letter exchange.

```php
$amqpQueue = AmqpQueue::createDirectExchange
                ->withDurability(true) // the queue will survive a broker restart
                ->withExclusivity() // used by only one connection and the queue will be deleted when that connection closes
                ->withAutoDeletion() // queue that has had at least one consumer is deleted when last consumer unsubscribes
                ->withDeadLetterExchangeTarget($amqpExchange);
```

--------------------------------

### Query Business Methods - Get Person IDs Iterator

Source: https://docs.ecotone.tech/modelling/command-handling/business-interface/working-with-database

Example of using FetchMode::ITERATE to return an iterator for fetching large result sets efficiently.

```APIDOC
## GET /api/persons/iterator

### Description
Fetches person IDs as an iterator, suitable for processing large datasets without high memory consumption.

### Method
GET

### Endpoint
/api/persons/iterator

### Response
#### Success Response (200)
- **iterator** (iterable) - An iterable that yields person IDs one by one.

#### Response Example
```json
// The response would be streamed or processed iteratively,
// not a static JSON object representing the entire dataset.
// Example of processing the iterator:
// foreach ($response->getBody()->iterate() as $personId) {
//   echo $personId . "\n";
// }
```
```

--------------------------------

### Command Definition Example (PHP)

Source: https://docs.ecotone.tech/tutorial-php-ddd-cqrs-event-sourcing/php-messaging-architecture

Defines a 'RegisterProductCommand' class in PHP, intended for use with Ecotone. This class encapsulates data for registering a product, including productId and cost. Type hinting is used for clarity and potential automatic conversion.

```php
<?php

namespace App\Domain\Product;

class RegisterProductCommand
{
    private int $productId;

    private int $cost;

    public function __construct(int $productId, int $cost)
    {
        $this->productId = $productId;
        $this->cost = $cost;
    }

    public function getProductId() : int
    {
        return $this->productId;
    }

    public function getCost() : int
    {
        return $this->cost;
    }
}
```

--------------------------------

### Query Business Methods - Get Person Name DTO Or Null

Source: https://docs.ecotone.tech/modelling/command-handling/business-interface/working-with-database

Example demonstrating nullable return type with FetchMode::FIRST_ROW, returning null if no record is found.

```APIDOC
## GET /api/persons/{personId}/nullable

### Description
Fetches a single person's details or returns null if the person with the specified ID is not found.

### Method
GET

### Endpoint
/api/persons/{personId}/nullable

### Parameters
#### Path Parameters
- **personId** (int) - Required - The ID of the person to retrieve.

### Response
#### Success Response (200)
- **person** (object|null) - An object containing 'person_id' and 'name', or null if the person is not found.

#### Response Example
```json
{
  "person": {
    "person_id": 1,
    "name": "John Doe"
  }
}
```

#### Success Response (200) - Not Found Example
```json
{
  "person": null
}
```
```

--------------------------------

### Register Ecotone Laravel Provider Manually

Source: https://docs.ecotone.tech/install-php-service-bus

Manually adds the Ecotone Laravel service provider to `config/app.php` if automatic package discovery fails. This ensures Laravel recognizes and bootstraps the Ecotone components.

```php
'providers' => [
    \Ecotone\Laravel\EcotoneProvider::class
],
```

--------------------------------

### Test User Registration Command Handler in PHP

Source: https://docs.ecotone.tech/modelling/testing-support/testing-messaging

Demonstrates testing a user registration command handler. It involves setting up an in-memory repository, bootstrapping Ecotone Lite with the handler and repository, verifying the initial state, sending the command, and asserting the final state.

```php
class UserService
{
    #[CommandHandler]
    public function register(RegisterUser $command, UserRepository $userRepository)
    {
        $userRepository->save(User::create($command->name));
    }
}

// 1. Create an in-memory repository for testing
$userRepository = new InMemoryUserRepository;

$ecotoneLite = EcotoneLite::bootstrapFlowTesting(
    // 2. Tell Ecotone which classes contain handlers to test
    [UserService::class],
    // 3. Provide the repository instance our handler needs
    [UserRepository::class => $userRepository]
);

// 4. Verify repository is empty before we start
$this->assertEmpty($userRepository->getAll());

// 5. Send the command through Ecotone's command bus
$ecotoneLite->sendCommand(new RegisterUser(
    Uuid::uuid4(),
    "johny",
    Email::create("test@wp.pl"),
    PhoneNumber::create("148518518518")
));

// 6. Verify the command handler did its job
$this->assertNotEmpty($userRepository->getAll());
```

--------------------------------

### Configure AMQP Message Channel Options (PHP)

Source: https://docs.ecotone.tech/modules/amqp-support-rabbitmq/message-channel

This example shows advanced configuration for an AMQP backed message channel. It demonstrates disabling auto-declaration of the queue, setting a default message time-to-live (TTL), defining a default delivery delay, and specifying a final failure strategy.

```php
<?php

use Ecotone\Amqp\Builder\AmqpBackedMessageChannelBuilder;
use Ecotone\Amqp\Enum\FinalFailureStrategy;

AmqpBackedMessageChannelBuilder::create("orders")
    ->withAutoDeclare(false) // do not auto declare queue
    ->withDefaultTimeToLive(1000) // limit TTL of messages
    ->withDefaultDeliveryDelay(1000) // delay messages by default
    ->withFinalFailureStrategy(FinalFailureStrategy::RESEND); // final failure strategy

```

--------------------------------

### Configure AmqpConnectionFactory in bin/console.php

Source: https://docs.ecotone.tech/tutorial-php-ddd-cqrs-event-sourcing/php-asynchronous-processing

This snippet shows how to configure and register the AmqpConnectionFactory in the container for AMQP communication. It sets up a connection to a RabbitMQ instance.

```php
public function __construct()
{
   $this->container = new Container();
   $this->container->set(Enqueue\AmqpExt\AmqpConnectionFactory::class, new Enqueue\AmqpExt\AmqpConnectionFactory("amqp+lib://guest:guest@rabbitmq:5672//"));
}
```

--------------------------------

### Configure Default DBAL Connection in Symfony (YAML)

Source: https://docs.ecotone.tech/modules/symfony/symfony-database-connection-dbal-module

Example of configuring a default DBAL connection in Symfony's doctrine.yaml file. This setup is recommended for reusing existing application database connections with Ecotone.

```yaml
doctrine:
  dbal:
    # If this configuration is not present, then "default" is implicit config
    connections:
      default:
        url: '%env(resolve:DATABASE_DSN)%'
```

--------------------------------

### Configure Multiple Distributed Bus Service Maps (PHP)

Source: https://docs.ecotone.tech/modelling/microservices-php/distributed-bus/distributed-bus-with-service-map/custom-features

This example shows how to set up multiple, distinct Distributed Bus instances within the same application. Each Service Map can be configured with specific command and event mappings, allowing for the separation of concerns, such as internal versus cross-team integrations.

```php
#[ServiceContext]
public function serviceMap(): DistributedServiceMap
{
    return [
        DistributedServiceMap::initialize(referenceName: 'internalDistributedBus')
           ->withCommandMapping(
                        targetServiceName: "ticketService",
                        channelName: "distributed_ticket_service"
           )
           ->withEventMapping(
                        channelName: "distributed_ticket_service",
                        subscriptionKeys: ["internal.*"],
           ),
        DistributedServiceMap::initialize(referenceName: 'externalDistributedBus')
            ->withCommandMapping(
                        targetServiceName: "orderService",
                        channelName: "distributed_order_service"
            )
            ->withEventMapping(
                        channelName: "distributed_order_service",
                        subscriptionKeys: ["external.*"],
            )
    ];
}
```

--------------------------------

### Query Person List using DbalQuery - PHP

Source: https://docs.ecotone.tech/modelling/command-handling/business-interface/working-with-database

This example shows how to query data from the 'persons' table using the DbalQuery attribute. It returns results as an associative array by default. Ensure the Dbal Module is installed.

```php
interface PersonApi
{
    #[DbalQueryMethod('SELECT person_id, name FROM persons LIMIT :limit OFFSET :offset')]
    public function getNameList(int $limit, int $offset): array;
}

```

--------------------------------

### Show Details of a Specific Error Message (Lite)

Source: https://docs.ecotone.tech/modelling/recovering-tracing-and-monitoring/resiliency/error-channel-and-dead-letter/dbal-dead-letter

This code example shows how to get detailed information for a specific dead-lettered error message using its ID via EcotoneLite's console command runner.

```php
$details = $messagingSystem->runConsoleCommand("ecotone:deadletter:show", ["messageId" => $messageId]);
```

--------------------------------

### Typical Aggregate Flow with PHP Repository

Source: https://docs.ecotone.tech/modelling/command-handling/repository

Demonstrates the manual orchestration required to fetch, modify, and save an aggregate using a repository. This involves explicitly calling repository methods before and after invoking the aggregate's action method.

```php
class AssignWorkerHandler
{
    private TicketRepository $ticketRepository;

    #[CommandHandler]
    public function handle(AssignWorkerCommand $command) : void
    {
       // fetch the aggregate from repository
       $ticket = $this->ticketRepository->findBy($command->getTicketId());
       // call action method
       $ticket->assignWorker($command);
       // store the aggregate in repository
       $this->ticketRepository->save($ticket);    
    }
}

```

```php
$this->commandBus->send(
   new AssignWorkerCommand(
      $ticketId, $workerId,
   )
);

```

--------------------------------

### Automatic Message Conversion with RabbitConsumer

Source: https://docs.ecotone.tech/modules/amqp-support-rabbitmq/rabbit-consumer

This example shows how to leverage automatic message conversion when consuming from a queue. If a custom converter or the JMS module is installed, the payload can be automatically converted to a specific domain object (e.g., Order).

```php
<?php

use Ecotone\RabbitMQ\Attribute\RabbitConsumer;
use App\Domain\Order; // Assuming Order is your domain object

// ...

#[RabbitConsumer(
    endpointId: 'orders_consumer',
    queueName: 'orders'
)]
public function handle(Order $payload): void
{
    // handle the converted Order object
}
```

--------------------------------

### Publish and Consume Asynchronous Messages in PHP

Source: https://docs.ecotone.tech/quick-start-php-ddd-cqrs-event-sourcing/asynchronous-php

Provides example PHP code for publishing an asynchronous event and running the asynchronous consumer. The `$eventBus->publish()` method sends the `OrderWasPlaced` event, and `$messagingSystem->run()` starts the consumer process for the 'asynchronous_messages' channel.

```php
$eventBus->publish(new OrderWasPlaced(1, "Milk"));

# Running asynchronous consumer
$messagingSystem->run("asynchronous_messages");

```
Tokens:
Raw