ecotoneframework/ecotone-business-interface

Ecotone Business Interfaces

Overview

Business interfaces let you declare PHP interfaces that Ecotone auto-implements at runtime. They cover database queries (DBAL), type converters, messaging gateways (BusinessMethod), and repository abstractions. Use this skill when you need to create any of these interface-driven patterns.

1. DBAL Query Interface

use Ecotone\Dbal\Attribute\DbalQueryBusinessMethod;
use Ecotone\Dbal\Attribute\DbalWriteBusinessMethod;
use Ecotone\Dbal\DbaBusinessMethod\FetchMode;

interface OrderRepository
{
    #[DbalQueryBusinessMethod('SELECT * FROM orders WHERE order_id = :orderId')]
    public function findById(string $orderId): ?array;

    #[DbalQueryBusinessMethod(
        'SELECT * FROM orders WHERE status = :status',
        fetchMode: FetchMode::ASSOCIATIVE
    )]
    public function findByStatus(string $status): array;

    #[DbalWriteBusinessMethod('INSERT INTO orders (order_id, product, status) VALUES (:orderId, :product, :status)')]
    public function save(string $orderId, string $product, string $status): void;
}

2. Media Type Converter

use Ecotone\Messaging\Attribute\Converter;

class OrderConverter
{
    #[Converter]
    public function fromArray(array $data): OrderDTO
    {
        return new OrderDTO(
            orderId: $data['order_id'],
            product: $data['product'],
            status: $data['status'],
        );
    }

    #[Converter]
    public function toArray(OrderDTO $order): array
    {
        return [
            'order_id' => $order->orderId,
            'product' => $order->product,
            'status' => $order->status,
        ];
    }
}

The framework auto-discovers converters and uses them for type conversion in message handling.

3. BusinessMethod Gateway

BusinessMethod is an interface-only attribute -- Ecotone auto-generates an implementation that sends messages through the messaging system. The requestChannel routes to the matching handler's routing key.

use Ecotone\Messaging\Attribute\BusinessMethod;

interface NotificationGateway
{
    #[BusinessMethod('notification.send')]
    public function send(string $message, string $recipient): void;
}

use Ecotone\Messaging\Attribute\ServiceActivator;

class NotificationHandler
{
    #[ServiceActivator('notification.send')]
    public function handle(string $message): void
    {
        // Process notification
    }
}

4. BusinessMethod Injection into Handlers

BusinessMethod interfaces can be injected as parameters into CommandHandler methods for cross-aggregate communication:

use Ecotone\Messaging\Attribute\BusinessMethod;
use Ecotone\Modelling\Attribute\Identifier;

interface ProductService
{
    #[BusinessMethod('product.getPrice')]
    public function getPrice(#[Identifier] string $productId): int;
}

#[EventSourcingAggregate]
class Basket
{
    #[CommandHandler]
    public static function addToNewBasket(
        AddProductToBasket $command,
        ProductService $productService
    ): array {
        return [new ProductWasAddedToBasket(
            $command->userId,
            $command->productId,
            $productService->getPrice($command->productId)
        )];
    }
}

Use #[Reference] for explicit service container injection when it is not the first service parameter.

5. Expression Language

Ecotone attributes support expressions for dynamic behavior:

use Ecotone\Modelling\Attribute\CommandHandler;

class OrderService
{
    #[CommandHandler(routingKey: "payload.type")]
    public function handle(array $payload): void { }
}

Available variables: payload (message payload), headers (message headers).

6. Repository Pattern

Ecotone auto-generates repositories for aggregates. For custom repositories:

use Ecotone\Modelling\Attribute\Repository;

#[Repository]
interface CustomOrderRepository
{
    public function findOrder(string $orderId): ?Order;
    public function saveOrder(Order $order): void;
}

Key Rules

• DBAL interfaces use method parameters as SQL bind parameters (:paramName)
• #[Converter] methods are auto-discovered -- no manual registration needed
• Converters work bidirectionally if you define both directions
• FetchMode determines the shape of query results
• When injecting BusinessMethod into handlers, first parameter after command is matched by type automatically; use #[Reference] for non-first service parameters

Additional resources

• API reference -- Attribute constructor signatures and parameter lists for DbalQueryBusinessMethod, DbalWriteBusinessMethod, DbalParameter, BusinessMethod/MessageGateway, FetchMode constants, and MediaType constants. Load when you need exact constructor parameters, types, or defaults.

• Usage examples -- Complete, runnable code examples for all business interface patterns: advanced DBAL queries with parameter type conversion and expressions, write operations, JSON converters, BusinessMethod with headers and routing, cross-aggregate injection with #[Reference], custom connection references. Load when you need full class implementations or advanced variations beyond the basic patterns above.

• Testing patterns -- How to test business interfaces with EcotoneLite::bootstrapFlowTesting(), including gateway retrieval via getGateway(), DBAL interface testing setup, and converter testing patterns. Load when writing tests for business interfaces.