Imported from ecotoneframework/ecotone-dev (AGENTS.md). Install upstream with npx skills add ecotoneframework/ecotone-dev. Copyright stays with the author.

Ecotone Framework - AI Agent Guidelines

Guidelines for AI agents contributing to or working with the Ecotone framework codebase.

Project Overview

Ecotone is the enterprise architecture layer for Laravel and Symfony. One Composer package adds CQRS, Event Sourcing, Sagas, Projections, Workflows, and Outbox messaging via declarative PHP 8 attributes. Works with Symfony, Laravel, or standalone via Ecotone Lite (any PSR-11 container).

Monorepo Structure

• Core package: packages/Ecotone - foundation for all other packages
• Each package under packages/* is a separate Composer package
• Packages are split to read-only repos during release
• Template for new packages: _PackageTemplate/

Code Conventions

• No comments - prefer meaningful private methods that describe intent
• Use PHP 8.1+ features (attributes, enums, named arguments)
• All public APIs need @param/@return PHPDoc
• Follow existing patterns in the codebase

Architecture Patterns

• Messages first - Commands, Events, Queries are first-class citizens
• Declarative configuration - use PHP attributes, not YAML/XML
• ServiceActivatorBuilder - for registering message handlers
• InterfaceToCall - for reflection and method metadata
• MessageHeaders - for message metadata propagation
• Modules - self-register via ModulePackageList

Testing Guidelines

General Approach

• Write high-level tests from end-user perspective
• Tests use EcotoneLite::bootstrapFlowTesting to bootstrap isolated Ecotone instances
• Prefer inline anonymous classes in tests over separate fixture files
• Run tests for the specific package you modified

Running Tests

# Enter development container
docker compose exec -u root app /bin/bash

# Run package tests
cd packages/PackageName
composer tests:ci

# Run specific test
vendor/bin/phpunit --filter testMethodName tests/Path/To/TestFile.php

Database-Specific Tests

# MySQL for PdoEventSourcing
DATABASE_DSN=mysql://ecotone:secret@database-mysql:3306/ecotone?serverVersion=8.0 \
  vendor/bin/phpunit packages/PdoEventSourcing/tests/

# PostgreSQL (default in container)
vendor/bin/phpunit packages/PdoEventSourcing/tests/

Test Types

• composer tests:phpunit - Unit/integration tests
• composer tests:behat - BDD feature tests
• composer tests:phpstan - Static analysis
• composer tests:ci - All tests for CI

Common Patterns

Command Handler

#[CommandHandler]
public function handle(PlaceOrder $command): void
{
    // Business logic
}

Event Handler

#[EventHandler]
public function when(OrderPlaced $event): void
{
    // React to event
}

Async Handler

#[Asynchronous('orders')]
#[EventHandler]
public function whenAsync(OrderPlaced $event): void
{
    // Processed asynchronously
}

Aggregate

#[Aggregate]
class Order
{
    #[Identifier]
    private string $orderId;
    
    #[CommandHandler]
    public static function place(PlaceOrder $command): self
    {
        return new self($command->orderId);
    }
}

Documentation Resources

• Full Documentation
• Testing Support
• Contributing Guide
• Blog & Examples

Development Environment

# Start all containers
docker compose up -d

# Enter dev container (use root for full access)
docker compose exec -u root app /bin/bash

# Verify lowest/highest dependencies
composer update --prefer-lowest && vendor/bin/phpunit
composer update --prefer-stable && vendor/bin/phpunit