Feature Guide

A quick orientation block that answers the essential questions: what this feature does, how it works, why it matters, and the key concepts behind it.

What this does

Two modules can point at the same table and contribute their own columns without one module editing the other module's resource class.

How it works

SchemaCollector groups discovered ORM resources by table name. When another resource maps to the same table, it adds only missing columns and leaves already-defined columns alone.

Why it matters

This removes one of the most painful ownership traps in modular systems: the first module does not permanently own the whole table forever. Later modules stay additive instead of invasive.

Key concepts

Shared table extension: Multiple ORM resources map to one physical table and extend its schema collaboratively.
SchemaCollector: Collects table definitions from resource attributes and merges columns by table name.
Module isolation: A later module can add persistence fields without reopening the source code of the original module.

ORM Kill Feature

One table. Two modules. Zero cross-module edits.

In most stacks, the second module has to reopen the first module's model just to add a few extra columns. Semitexa keeps that additive: both resources point at the same table, and schema collection merges the result.

Why teams hate the usual approach

One module usually becomes the permanent owner of a table, even when another bounded context needs to extend it later.
The follow-up module often has to edit the original model class, creating ownership bleed and merge pressure between teams.
That coupling turns harmless extra columns into a cross-module coordination problem instead of an additive change.

Base resource

Catalog Module

Owns the initial product shape that the storefront and admin tools already depend on.

id tenant_id name description price status

Extension resource

Merchandising Module

Arrives later and adds campaign-only fields without reopening the catalog module.

badge_label merch_priority campaign_code

Merged column	Owned by	Why it stays safe
`id`	Catalog	Base primary key stays untouched.
`tenant_id`	Catalog	Tenant scoping still applies to the shared table.
`name`	Catalog	Core commerce data remains where it started.
`description`	Catalog	Existing product content is unchanged.
`price`	Catalog	Base module continues to own pricing semantics.
`status`	Catalog	Lifecycle state stays with the core domain.
`badge_label`	Merchandising	Added later for campaign UX.
`merch_priority`	Merchandising	Supports merchandising sort logic.
`campaign_code`	Merchandising	Connects rows to external campaign flows.

#[FromTable] #[Column] #[TenantScoped]

Verified against Semitexa Ultimate 2026.09.19.1020

Shared Table Extension

Two ResourceModel classes in different modules can target the same physical table with #[FromTable]. The SchemaCollector merges their column sets into one schema plan.

How it works

The base module defines the core resource with #[FromTable('products')] and declares its columns. A later module creates its own resource, also pointing at #[FromTable('products')], and declares only its additional columns. At sync time, SchemaCollector groups all discovered resources by table name and only adds missing columns — it never redefines existing ones. Neither module needs to open or modify the other's class.

Why this matters

Without shared table extension, a later module either has to edit the original resource class (creating cross-module ownership bleed) or maintain a separate table (creating join complexity). The additive model keeps module boundaries clean and schema evolution safe.

1<?php23declare(strict_types=1);45namespace App\Catalog\Resource;67use Semitexa\Orm\Adapter\MySqlType;8use Semitexa\Orm\Attribute\Column;9use Semitexa\Orm\Attribute\FromTable;10use Semitexa\Orm\Attribute\PrimaryKey;11use Semitexa\Orm\Attribute\TenantScoped;1213#[FromTable(name: 'demo_products')]14#[TenantScoped(strategy: 'same_storage')]15final class CatalogProductResource16{17    #[PrimaryKey(strategy: 'uuid')]18    #[Column(type: MySqlType::Binary, length: 16)]19    public string $id;2021    #[Column(type: MySqlType::Varchar, length: 64)]22    public string $tenant_id;2324    #[Column(type: MySqlType::Varchar, length: 190)]25    public string $name;2627    #[Column(type: MySqlType::Text)]28    public ?string $description = null;2930    #[Column(type: MySqlType::Decimal, precision: 10, scale: 2)]31    public string $price;3233    #[Column(type: MySqlType::Varchar, length: 32)]34    public string $status = 'draft';35}36

<?php

declare(strict_types=1);

namespace App\Catalog\Resource;

use Semitexa\Orm\Adapter\MySqlType;
use Semitexa\Orm\Attribute\Column;
use Semitexa\Orm\Attribute\FromTable;
use Semitexa\Orm\Attribute\PrimaryKey;
use Semitexa\Orm\Attribute\TenantScoped;

#[FromTable(name: 'demo_products')]
#[TenantScoped(strategy: 'same_storage')]
final class CatalogProductResource
{
    #[PrimaryKey(strategy: 'uuid')]
    #[Column(type: MySqlType::Binary, length: 16)]
    public string $id;

    #[Column(type: MySqlType::Varchar, length: 64)]
    public string $tenant_id;

    #[Column(type: MySqlType::Varchar, length: 190)]
    public string $name;

    #[Column(type: MySqlType::Text)]
    public ?string $description = null;

    #[Column(type: MySqlType::Decimal, precision: 10, scale: 2)]
    public string $price;

    #[Column(type: MySqlType::Varchar, length: 32)]
    public string $status = 'draft';
}

1<?php23declare(strict_types=1);45namespace App\Merchandising\Resource;67use Semitexa\Orm\Adapter\MySqlType;8use Semitexa\Orm\Attribute\Column;9use Semitexa\Orm\Attribute\FromTable;1011#[FromTable(name: 'demo_products')]12final class MerchandisingProductExtension13{14    #[Column(type: MySqlType::Varchar, length: 80, nullable: true)]15    public ?string $badge_label = null;1617    #[Column(type: MySqlType::Int, default: 0)]18    public int $merch_priority = 0;1920    #[Column(type: MySqlType::Varchar, length: 48, nullable: true)]21    public ?string $campaign_code = null;22}23

<?php

declare(strict_types=1);

namespace App\Merchandising\Resource;

use Semitexa\Orm\Adapter\MySqlType;
use Semitexa\Orm\Attribute\Column;
use Semitexa\Orm\Attribute\FromTable;

#[FromTable(name: 'demo_products')]
final class MerchandisingProductExtension
{
    #[Column(type: MySqlType::Varchar, length: 80, nullable: true)]
    public ?string $badge_label = null;

    #[Column(type: MySqlType::Int, default: 0)]
    public int $merch_priority = 0;

    #[Column(type: MySqlType::Varchar, length: 48, nullable: true)]
    public ?string $campaign_code = null;
}

1<?php23declare(strict_types=1);45namespace Semitexa\Orm\Application\Service\Schema;67use Semitexa\Orm\Domain\Enum\ForeignKeyAction;8use Semitexa\Orm\Domain\Model\ColumnDefinition;9use Semitexa\Orm\Domain\Model\ForeignKeyDefinition;10use Semitexa\Orm\Domain\Model\IndexDefinition;11use Semitexa\Orm\Domain\Model\TableDefinition;1213use Semitexa\Core\Discovery\ClassDiscovery;14use Semitexa\Orm\Adapter\DatabaseType;15use Semitexa\Orm\Adapter\MySqlType;16use Semitexa\Orm\Adapter\SqliteType;17use Semitexa\Orm\Attribute\Aggregate;18use Semitexa\Orm\Attribute\BelongsTo;19use Semitexa\Orm\Attribute\Column;20use Semitexa\Orm\Attribute\Connection;21use Semitexa\Orm\Attribute\Deprecated;22use Semitexa\Orm\Attribute\Filterable;23use Semitexa\Orm\Attribute\FromTable;24use Semitexa\Orm\Attribute\HasMany;25use Semitexa\Orm\Attribute\Index;26use Semitexa\Orm\Attribute\ManyToMany;27use Semitexa\Orm\Attribute\OneToOne;28use Semitexa\Orm\Attribute\PrimaryKey;29use Semitexa\Orm\Attribute\TenantScoped;3031class SchemaCollector32{33    /** @var string[] */34    private array $errors = [];3536    /** @var string[] */37    private array $warnings = [];3839    /**40     * @param string $driver The database driver ('mysql' or 'sqlite')41     */42    public function __construct(43        private ?ClassDiscovery $classDiscovery = null,44        private readonly string $driver = 'mysql',45        private readonly ?string $connectionNameFilter = null,46    ) {}4748    /**49     * @return array<string, TableDefinition>50     */51    public function collect(): array52    {53        $this->errors = [];54        $this->warnings = [];5556        $classes = $this->classDiscovery()->findClassesWithAttribute(FromTable::class);57        /** @var array<string, TableDefinition> $tables */58        $tables = [];5960        foreach ($classes as $className) {61            if (!$this->matchesConnectionFilter($className)) {62                continue;63            }6465            $this->processClass($className, $tables);66        }6768        $filteredClasses = array_values(array_filter($classes, fn (string $className): bool => $this->matchesConnectionFilter($className)));69        $this->addPivotTables($filteredClasses, $tables);7071        foreach ($tables as $table) {72            $tableErrors = $table->validate();73            foreach ($tableErrors as $error) {74                $this->warnings[] = $error;75            }7677            $primaryKey = $table->getPrimaryKey();78            if ($primaryKey !== null && $primaryKey->nullable) {79                $this->errors[] = "Table '{$table->name}': primary key column '{$primaryKey->name}' cannot be nullable.";80            }81        }8283        $this->resolveForeignKeys($tables);8485        return $tables;86    }8788    private function matchesConnectionFilter(string $className): bool89    {90        if ($this->connectionNameFilter === null) {91            return true;92        }9394        $ref = new \ReflectionClass($className);95        $attrs = $ref->getAttributes(Connection::class);96        $connectionName = $attrs !== [] ? $attrs[0]->newInstance()->name : 'default';9798        return $connectionName === $this->connectionNameFilter;99    }100101    /** @return string[] */102    public function getErrors(): array103    {104        return $this->errors;105    }106107    /** @return string[] */108    public function getWarnings(): array109    {110        return $this->warnings;111    }112113    /**114     * @param array<string, TableDefinition> $tables115     */116    private function processClass(string $className, array &$tables): void117    {118        $ref = new \ReflectionClass($className);119        $fromTableAttrs = $ref->getAttributes(FromTable::class);120121        if (empty($fromTableAttrs)) {122            return;123        }124125        /** @var FromTable $fromTable */126        $fromTable = $fromTableAttrs[0]->newInstance();127        $tableName = $fromTable->name;128129        $this->assertValidIdentifier($tableName, "table name in '{$className}'");130131        if (!isset($tables[$tableName])) {132            $tables[$tableName] = new TableDefinition($tableName);133        }134135        $table = $tables[$tableName];136137        // Collect properties from the class and its traits138        $properties = $this->getAllProperties($ref);139140        foreach ($properties as $property) {141            $this->processProperty($property, $table, $className);142        }143144        // Collect class-level Index attributes145        $indexAttrs = $ref->getAttributes(Index::class);146        foreach ($indexAttrs as $indexAttr) {147            /** @var Index $index */148            $index = $indexAttr->newInstance();149            /** @var array<string> $columns */150            $columns = array_values(array_filter($index->columns, static fn (mixed $column): bool => is_string($column) && $column !== ''));151            if ($columns === [] || count($columns) !== count($index->columns)) {152                $this->errors[] = "Table '{$table->name}': #[Index] columns must be non-empty strings.";153                continue;154            }155156            $table->addIndex(new IndexDefinition(157                columns: $columns,158                unique: $index->unique,159                name: $index->name,160            ));161        }162163        // TenantScoped(same_storage): ensure tenant_id column exists for migrations164        $tenantAttrs = $ref->getAttributes(TenantScoped::class);165        if ($tenantAttrs !== []) {166            /** @var TenantScoped $tenantAttr */167            $tenantAttr = $tenantAttrs[0]->newInstance();168            $tenantColumn = 'tenant_id';169            if ($tenantAttr->strategy === 'same_storage' && $table->getColumn($tenantColumn) === null) {170                $table->addColumn(new ColumnDefinition(171                    name: $tenantColumn,172                    type: $this->resolveDefaultType(),173                    phpType: 'string',174                    nullable: false,175                    length: 64,176                    propertyName: 'tenantId',177                ));178            }179        }180    }181182    /**183     * @return \ReflectionProperty[]184     */185    private function getAllProperties(\ReflectionClass $ref): array186    {187        $properties = $ref->getProperties();188        $seen = [];189        $result = [];190191        foreach ($properties as $prop) {192            if (!isset($seen[$prop->getName()])) {193                $seen[$prop->getName()] = true;194                $result[] = $prop;195            }196        }197198        return $result;199    }200201    private function processProperty(\ReflectionProperty $property, TableDefinition $table, string $className): void202    {203        $columnAttrs = $property->getAttributes(Column::class);204        $pkAttrs = $property->getAttributes(PrimaryKey::class);205        $deprecatedAttrs = $property->getAttributes(Deprecated::class);206207        // Relation attributes208        $this->processRelations($property, $table);209210        // Aggregate — no column processing needed211        if (!empty($property->getAttributes(Aggregate::class))) {212            return;213        }214215        if ($columnAttrs === []) {216            // Skip internal/trait state (e.g. FilterableTrait __filterCriteria)217            if (str_starts_with($property->getName(), '__')) {218                return;219            }220            // Property without #[Column] in a Resource class — error unless it's a relation221            if ($property->getAttributes(BelongsTo::class) === []222                && $property->getAttributes(HasMany::class) === []223                && $property->getAttributes(OneToOne::class) === []224                && $property->getAttributes(ManyToMany::class) === []225                && $property->getAttributes(Aggregate::class) === []226            ) {227                $this->errors[] = "Property '{$property->getName()}' in '{$className}' has no #[Column] attribute.";228            }229            return;230        }231232        /** @var Column $column */233        $column = $columnAttrs[0]->newInstance();234235        $isPrimaryKey = !empty($pkAttrs);236        $pkStrategy = 'auto';237        if ($isPrimaryKey) {238            /** @var PrimaryKey $pk */239            $pk = $pkAttrs[0]->newInstance();240            $pkStrategy = $pk->strategy;241242            // string PK without explicit strategy243            $phpType = $this->resolvePhpType($property);244            if ($phpType === 'string' && $pkStrategy === 'auto') {245                $this->errors[] = "Property '{$property->getName()}' in '{$className}': string primary key requires explicit strategy.";246            }247248            // uuid strategy requires Binary or Varchar column type249            if ($pkStrategy === 'uuid' && $columnAttrs !== []) {250                /** @var Column $colCheck */251                $colCheck = $columnAttrs[0]->newInstance();252                $isBinaryOrVarchar = ($colCheck->type instanceof MySqlType && in_array($colCheck->type, [MySqlType::Binary, MySqlType::Varchar], true))253                    || ($colCheck->type instanceof SqliteType && in_array($colCheck->type, [SqliteType::Binary, SqliteType::Varchar], true));254                if (!$isBinaryOrVarchar) {255                    $this->errors[] = "Property '{$property->getName()}' in '{$className}': uuid strategy requires Binary or Varchar column type.";256                }257            }258        }259260        $isDeprecated = !empty($deprecatedAttrs);261        $phpType = $this->resolvePhpType($property);262263        $propertyName = $property->getName();264        $columnName   = $column->name ?? $propertyName;265266        // Validate PHP type vs MySqlType267        $this->validateTypeMatch($phpType, $column->type, $propertyName, $className);268269        $nullable = $column->nullable || ($property->getType() instanceof \ReflectionNamedType && $property->getType()->allowsNull());270        if ($isPrimaryKey) {271            $nullable = false;272        }273274        $this->assertValidIdentifier($columnName, "column '{$columnName}' in '{$className}'");275276        $colDef = new ColumnDefinition(277            name: $columnName,278            type: $column->type,279            phpType: $phpType,280            nullable: $nullable,281            length: $column->length,282            precision: $column->precision,283            scale: $column->scale,284            default: $column->default,285            isPrimaryKey: $isPrimaryKey,286            pkStrategy: $pkStrategy,287            isDeprecated: $isDeprecated,288            propertyName: $propertyName,289        );290291        // Multiple Resources can map to the same table (e.g. base + projection); merge schema — skip column if already defined292        if ($table->getColumn($columnName) !== null) {293            return;294        }295296        $table->addColumn($colDef);297298        // Auto-index for #[Filterable] columns (single-column, non-unique)299        if (!empty($property->getAttributes(Filterable::class))) {300            $indexName = 'idx_' . $table->name . '_' . $columnName;301            $table->addIndex(new IndexDefinition(302                columns: [$columnName],303                unique: false,304                name: $indexName,305            ));306        }307308        if ($isDeprecated) {309            $this->checkDeprecatedUsage($columnName, $table);310        }311    }312313    private function processRelations(\ReflectionProperty $property, TableDefinition $table): void314    {315        $propName = $property->getName();316317        foreach ($property->getAttributes(BelongsTo::class) as $attr) {318            /** @var BelongsTo $rel */319            $rel = $attr->newInstance();320            $table->addRelation($propName, 'belongs_to', $rel->target, $rel->foreignKey, null, null, $rel->onDelete, $rel->onUpdate);321        }322323        foreach ($property->getAttributes(HasMany::class) as $attr) {324            /** @var HasMany $rel */325            $rel = $attr->newInstance();326            $table->addRelation($propName, 'has_many', $rel->target, $rel->foreignKey, null, null, $rel->onDelete, $rel->onUpdate);327        }328329        foreach ($property->getAttributes(OneToOne::class) as $attr) {330            /** @var OneToOne $rel */331            $rel = $attr->newInstance();332            $table->addRelation($propName, 'one_to_one', $rel->target, $rel->foreignKey, null, null, $rel->onDelete, $rel->onUpdate);333        }334335        foreach ($property->getAttributes(ManyToMany::class) as $attr) {336            /** @var ManyToMany $rel */337            $rel = $attr->newInstance();338            $table->addRelation($propName, 'many_to_many', $rel->target, $rel->foreignKey, $rel->pivotTable, $rel->relatedKey, $rel->onDelete, $rel->onUpdate);339        }340    }341342    private function resolvePhpType(\ReflectionProperty $property): string343    {344        $type = $property->getType();345346        if ($type instanceof \ReflectionNamedType) {347            return $type->getName();348        }349350        if ($type instanceof \ReflectionUnionType) {351            $types = array_map(352                fn(\ReflectionNamedType $t) => $t->getName(),353                array_filter($type->getTypes(), fn($t) => $t instanceof \ReflectionNamedType && $t->getName() !== 'null'),354            );355            return $types[0] ?? 'mixed';356        }357358        return 'mixed';359    }360361    private function validateTypeMatch(string $phpType, DatabaseType $sqlType, string $propName, string $className): void362    {363        // Backed enums: StringBackedEnum → Varchar/Text, IntBackedEnum → Int/Bigint364        if (enum_exists($phpType)) {365            $ref = new \ReflectionEnum($phpType);366            if ($ref->isBacked()) {367                $backingType = (string) $ref->getBackingType();368                $phpType = $backingType;369            } else {370                $this->errors[] = "Property '{$propName}' in '{$className}': non-backed enum '{$phpType}' cannot be mapped to a database column.";371                return;372            }373        }374375        $valid = match (true) {376            $sqlType instanceof MySqlType => $this->validateMySqlTypeMatch($phpType, $sqlType),377            $sqlType instanceof SqliteType => $this->validateSqliteTypeMatch($phpType, $sqlType),378            default => true,379        };380381        if (!$valid) {382            $driverName = $sqlType instanceof MySqlType ? 'MySQL' : 'SQLite';383            $typeName = $sqlType->canonicalName();384            $this->errors[] = "Property '{$propName}' in '{$className}': PHP type '{$phpType}' is incompatible with {$driverName} type '{$typeName}'.";385        }386    }387388    private function validateMySqlTypeMatch(string $phpType, MySqlType $sqlType): bool389    {390        return match ($sqlType) {391            MySqlType::Varchar, MySqlType::Char,392            MySqlType::Text, MySqlType::MediumText,393            MySqlType::LongText, MySqlType::Time        => in_array($phpType, ['string', 'mixed']),394            MySqlType::Json                             => in_array($phpType, ['string', 'array', 'mixed']),395            MySqlType::TinyInt, MySqlType::SmallInt,396            MySqlType::Int, MySqlType::Bigint,397            MySqlType::Year                             => in_array($phpType, ['int', 'mixed']),398            MySqlType::Float, MySqlType::Double         => in_array($phpType, ['float', 'mixed']),399            MySqlType::Decimal                          => in_array($phpType, ['string', 'float', 'mixed']),400            MySqlType::Boolean                          => in_array($phpType, ['bool', 'int', 'mixed']),401            MySqlType::Datetime, MySqlType::Timestamp,402            MySqlType::Date                             => in_array($phpType, ['DateTimeImmutable', 'DateTime', 'string', 'mixed']),403            MySqlType::Blob, MySqlType::Binary          => in_array($phpType, ['string', 'mixed']),404        };405    }406407    private function validateSqliteTypeMatch(string $phpType, SqliteType $sqlType): bool408    {409        return match ($sqlType) {410            SqliteType::Varchar, SqliteType::Char,411            SqliteType::Text, SqliteType::Time       => in_array($phpType, ['string', 'mixed']),412            SqliteType::Datetime, SqliteType::Date   => in_array($phpType, ['DateTimeImmutable', 'DateTime', 'string', 'mixed']),413            SqliteType::Json                          => in_array($phpType, ['string', 'array', 'mixed']),414            SqliteType::TinyInt, SqliteType::SmallInt,415            SqliteType::Int, SqliteType::Bigint       => in_array($phpType, ['int', 'mixed']),416            SqliteType::Float, SqliteType::Double,417            SqliteType::Decimal                       => in_array($phpType, ['float', 'mixed']),418            SqliteType::Boolean                       => in_array($phpType, ['bool', 'int', 'mixed']),419            SqliteType::Blob, SqliteType::Binary      => in_array($phpType, ['string', 'mixed']),420        };421    }422423    /**424     * Validate that a SQL identifier (table or column name) contains only425     * safe characters: letters, digits, and underscores, starting with a426     * letter or underscore. Identifiers come from PHP attributes, not user427     * input, but a typo or malformed name would silently produce broken SQL.428     * Throwing early gives a clear error at schema-collect time.429     */430    private function assertValidIdentifier(string $name, string $context): void431    {432        if (!preg_match('/^[a-zA-Z_][a-zA-Z0-9_]*$/', $name)) {433            throw new \InvalidArgumentException(434                "Invalid SQL identifier for {$context}: '{$name}'. "435                . "Only letters, digits and underscores are allowed, starting with a letter or underscore."436            );437        }438    }439440    /**441     * Add synthetic table definitions for ManyToMany pivot tables so they are created by orm:sync.442     *443     * @param list<string> $classes FromTable class names444     * @param array<string, TableDefinition> $tables445     */446    private function addPivotTables(array $classes, array &$tables): void447    {448        $classToTable = [];449        foreach ($classes as $className) {450            try {451                $ref = new \ReflectionClass($className);452                $attrs = $ref->getAttributes(FromTable::class);453                if (!empty($attrs)) {454                    /** @var FromTable $ft */455                    $ft = $attrs[0]->newInstance();456                    $classToTable[$className] = $ft->name;457                }458            } catch (\ReflectionException) {459                // skip460            }461        }462463        foreach ($tables as $tableName => $table) {464            foreach ($table->getRelations() as $relation) {465                if (($relation['type'] ?? '') !== 'many_to_many') {466                    continue;467                }468                $pivotTable = $relation['pivotTable'] ?? null;469                $foreignKey = $relation['foreignKey'] ?? null;470                $relatedKey = $relation['relatedKey'] ?? null;471                $targetClass = $relation['target'];472                if ($pivotTable === null || $foreignKey === null || $relatedKey === null || $targetClass === '') {473                    continue;474                }475                if (isset($tables[$pivotTable])) {476                    continue; // already added (e.g. same pivot from another side)477                }478                $this->assertValidIdentifier($pivotTable, "pivot table '{$pivotTable}'");479                $targetTable = $classToTable[$targetClass] ?? null;480                if ($targetTable === null) {481                    try {482                        /** @var class-string $targetClass */483                        $ref = new \ReflectionClass($targetClass);484                        $attrs = $ref->getAttributes(FromTable::class);485                        if (!empty($attrs)) {486                            $ft = $attrs[0]->newInstance();487                            $targetTable = $ft->name;488                        }489                    } catch (\ReflectionException) {490                        // skip491                    }492                }493                if ($targetTable === null) {494                    continue;495                }496                $pivot = new TableDefinition($pivotTable);497                $intType = $this->resolveIntType();498                $pivot->addColumn(new ColumnDefinition(499                    name: 'id',500                    type: $intType,501                    phpType: 'int',502                    nullable: false,503                    isPrimaryKey: true,504                    pkStrategy: 'auto',505                ));506                $pivot->addColumn(new ColumnDefinition(507                    name: $foreignKey,508                    type: $intType,509                    phpType: 'int',510                    nullable: false,511                ));512                $pivot->addColumn(new ColumnDefinition(513                    name: $relatedKey,514                    type: $intType,515                    phpType: 'int',516                    nullable: false,517                ));518                $pivot->addIndex(new IndexDefinition(519                    columns: [$foreignKey, $relatedKey],520                    unique: true,521                    name: 'uniq_' . $foreignKey . '_' . $relatedKey,522                ));523                $tables[$pivotTable] = $pivot;524            }525        }526    }527528    /**529     * Post-process step: build ForeignKeyDefinition objects for all relations530     * that carry a FK column on the owning side.531     *532     * BelongsTo — FK lives on THIS table → generate FK from this table → target.533     * HasMany    — FK lives on the CHILD table → generate FK from target table → this table.534     * OneToOne   — FK lives on the CHILD/related table → same as HasMany.535     * ManyToMany — FK lives on the pivot table → add FKs from pivot to parent and target.536     *537     * @param array<string, TableDefinition> $tables538     */539    private function resolveForeignKeys(array $tables): void540    {541        // Build a map: table name → PK column name (for reference resolution)542        $pkMap = [];543        foreach ($tables as $tableName => $table) {544            $pk = $table->getPrimaryKey();545            if ($pk !== null) {546                $pkMap[$tableName] = $pk->name;547            }548        }549550        // Build a map: resource class name → table name551        $classToTable = [];552        foreach ($tables as $tableName => $table) {553            foreach ($table->getRelations() as $relation) {554                $targetClass = $relation['target'];555                if ($targetClass === '') {556                    continue;557                }558                if (!isset($classToTable[$targetClass])) {559                    try {560                        /** @var class-string $targetClass */561                        $ref = new \ReflectionClass($targetClass);562                        $attrs = $ref->getAttributes(FromTable::class);563                        if (!empty($attrs)) {564                            /** @var \Semitexa\Orm\Attribute\FromTable $ft */565                            $ft = $attrs[0]->newInstance();566                            $classToTable[$targetClass] = $ft->name;567                        }568                    } catch (\ReflectionException) {569                        // skip570                    }571                }572            }573        }574575        foreach ($tables as $tableName => $table) {576            foreach ($table->getRelations() as $relation) {577                $type       = $relation['type'];578                $targetClass = $relation['target'];579                $foreignKey = $relation['foreignKey'];580                $onDelete   = $relation['onDelete'] ?? null;581                $onUpdate   = $relation['onUpdate'] ?? null;582583                /** @var string|null $onDelete */584                /** @var string|null $onUpdate */585                $targetTable = $classToTable[$targetClass] ?? null;586                if ($targetTable === null) {587                    continue;588                }589                if (!isset($tables[$targetTable]) && $type !== 'belongs_to') {590                    continue;591                }592                if ($type === 'belongs_to' && !isset($tables[$targetTable])) {593                    continue;594                }595596                if ($type === 'belongs_to') {597                    // FK is on THIS table — references the target's PK598                    $referencedPk = $pkMap[$targetTable] ?? 'id';599                    $fkCol = $table->getColumn($foreignKey);600                    $nullable = $fkCol !== null && $fkCol->nullable;601                    $resolvedOnDelete = $onDelete ?? ($nullable ? ForeignKeyAction::SetNull : ForeignKeyAction::Restrict);602                    $resolvedOnUpdate = $onUpdate ?? ($nullable ? ForeignKeyAction::SetNull : ForeignKeyAction::Restrict);603604                    $table->addForeignKey(new ForeignKeyDefinition(605                        table: $tableName,606                        column: $foreignKey,607                        referencedTable: $targetTable,608                        referencedColumn: $referencedPk,609                        onDelete: $resolvedOnDelete,610                        onUpdate: $resolvedOnUpdate,611                    ));612                } elseif ($type === 'has_many' || $type === 'one_to_one') {613                    // FK is on the TARGET table — references THIS table's PK614                    $referencedPk = $pkMap[$tableName] ?? 'id';615                    $targetTableDef = $tables[$targetTable] ?? null;616                    if ($targetTableDef === null) {617                        continue;618                    }619                    $fkCol = $targetTableDef->getColumn($foreignKey);620                    $nullable = $fkCol !== null && $fkCol->nullable;621                    $resolvedOnDelete = $onDelete ?? ($nullable ? ForeignKeyAction::SetNull : ForeignKeyAction::Restrict);622                    $resolvedOnUpdate = $onUpdate ?? ($nullable ? ForeignKeyAction::SetNull : ForeignKeyAction::Restrict);623624                    $targetTableDef->addForeignKey(new ForeignKeyDefinition(625                        table: $targetTable,626                        column: $foreignKey,627                        referencedTable: $tableName,628                        referencedColumn: $referencedPk,629                        onDelete: $resolvedOnDelete,630                        onUpdate: $resolvedOnUpdate,631                    ));632                } elseif ($type === 'many_to_many') {633                    // FK is on the pivot table: pivot.foreignKey -> this table, pivot.relatedKey -> target table634                    $pivotTable = $relation['pivotTable'] ?? null;635                    $relatedKey = $relation['relatedKey'] ?? null;636                    if ($pivotTable === null || $relatedKey === null) {637                        continue;638                    }639                    $pivotDef = $tables[$pivotTable] ?? null;640                    if ($pivotDef === null) {641                        continue;642                    }643                    $parentPk = $pkMap[$tableName] ?? 'id';644                    $targetPk = $pkMap[$targetTable] ?? 'id';645                    $restrict = ForeignKeyAction::Restrict;646                    $pivotDef->addForeignKey(new ForeignKeyDefinition(647                        table: $pivotTable,648                        column: $foreignKey,649                        referencedTable: $tableName,650                        referencedColumn: $parentPk,651                        onDelete: $onDelete ?? $restrict,652                        onUpdate: $onUpdate ?? $restrict,653                    ));654                    $pivotDef->addForeignKey(new ForeignKeyDefinition(655                        table: $pivotTable,656                        column: $relatedKey,657                        referencedTable: $targetTable,658                        referencedColumn: $targetPk,659                        onDelete: $onDelete ?? $restrict,660                        onUpdate: $onUpdate ?? $restrict,661                    ));662                }663            }664        }665    }666667    private function checkDeprecatedUsage(string $columnName, TableDefinition $table): void668    {669        foreach ($table->getIndexes() as $index) {670            if (in_array($columnName, $index->columns, true)) {671                $this->warnings[] = "Deprecated column '{$columnName}' in table '{$table->name}' is used in an index.";672            }673        }674675        foreach ($table->getRelations() as $relation) {676            if ($relation['foreignKey'] === $columnName) {677                $this->warnings[] = "Deprecated column '{$columnName}' in table '{$table->name}' is used in a relation.";678            }679        }680    }681682    private function classDiscovery(): ClassDiscovery683    {684        return $this->classDiscovery ??= new ClassDiscovery();685    }686687    /**688     * Resolve the default Varchar type for the current driver.689     */690    private function resolveDefaultType(): DatabaseType691    {692        return $this->driver === 'sqlite' ? SqliteType::Varchar : MySqlType::Varchar;693    }694695    /**696     * Resolve the Integer type for the current driver.697     */698    private function resolveIntType(): DatabaseType699    {700        return $this->driver === 'sqlite' ? SqliteType::Int : MySqlType::Int;701    }702703}704

<?php

declare(strict_types=1);

namespace Semitexa\Orm\Application\Service\Schema;

use Semitexa\Orm\Domain\Enum\ForeignKeyAction;
use Semitexa\Orm\Domain\Model\ColumnDefinition;
use Semitexa\Orm\Domain\Model\ForeignKeyDefinition;
use Semitexa\Orm\Domain\Model\IndexDefinition;
use Semitexa\Orm\Domain\Model\TableDefinition;

use Semitexa\Core\Discovery\ClassDiscovery;
use Semitexa\Orm\Adapter\DatabaseType;
use Semitexa\Orm\Adapter\MySqlType;
use Semitexa\Orm\Adapter\SqliteType;
use Semitexa\Orm\Attribute\Aggregate;
use Semitexa\Orm\Attribute\BelongsTo;
use Semitexa\Orm\Attribute\Column;
use Semitexa\Orm\Attribute\Connection;
use Semitexa\Orm\Attribute\Deprecated;
use Semitexa\Orm\Attribute\Filterable;
use Semitexa\Orm\Attribute\FromTable;
use Semitexa\Orm\Attribute\HasMany;
use Semitexa\Orm\Attribute\Index;
use Semitexa\Orm\Attribute\ManyToMany;
use Semitexa\Orm\Attribute\OneToOne;
use Semitexa\Orm\Attribute\PrimaryKey;
use Semitexa\Orm\Attribute\TenantScoped;

class SchemaCollector
{
    /** @var string[] */
    private array $errors = [];

    /** @var string[] */
    private array $warnings = [];

    /**
     * @param string $driver The database driver ('mysql' or 'sqlite')
     */
    public function __construct(
        private ?ClassDiscovery $classDiscovery = null,
        private readonly string $driver = 'mysql',
        private readonly ?string $connectionNameFilter = null,
    ) {}

    /**
     * @return array<string, TableDefinition>
     */
    public function collect(): array
    {
        $this->errors = [];
        $this->warnings = [];

        $classes = $this->classDiscovery()->findClassesWithAttribute(FromTable::class);
        /** @var array<string, TableDefinition> $tables */
        $tables = [];

        foreach ($classes as $className) {
            if (!$this->matchesConnectionFilter($className)) {
                continue;
            }

            $this->processClass($className, $tables);
        }

        $filteredClasses = array_values(array_filter($classes, fn (string $className): bool => $this->matchesConnectionFilter($className)));
        $this->addPivotTables($filteredClasses, $tables);

        foreach ($tables as $table) {
            $tableErrors = $table->validate();
            foreach ($tableErrors as $error) {
                $this->warnings[] = $error;
            }

            $primaryKey = $table->getPrimaryKey();
            if ($primaryKey !== null && $primaryKey->nullable) {
                $this->errors[] = "Table '{$table->name}': primary key column '{$primaryKey->name}' cannot be nullable.";
            }
        }

        $this->resolveForeignKeys($tables);

        return $tables;
    }

    private function matchesConnectionFilter(string $className): bool
    {
        if ($this->connectionNameFilter === null) {
            return true;
        }

        $ref = new \ReflectionClass($className);
        $attrs = $ref->getAttributes(Connection::class);
        $connectionName = $attrs !== [] ? $attrs[0]->newInstance()->name : 'default';

        return $connectionName === $this->connectionNameFilter;
    }

    /** @return string[] */
    public function getErrors(): array
    {
        return $this->errors;
    }

    /** @return string[] */
    public function getWarnings(): array
    {
        return $this->warnings;
    }

    /**
     * @param array<string, TableDefinition> $tables
     */
    private function processClass(string $className, array &$tables): void
    {
        $ref = new \ReflectionClass($className);
        $fromTableAttrs = $ref->getAttributes(FromTable::class);

        if (empty($fromTableAttrs)) {
            return;
        }

        /** @var FromTable $fromTable */
        $fromTable = $fromTableAttrs[0]->newInstance();
        $tableName = $fromTable->name;

        $this->assertValidIdentifier($tableName, "table name in '{$className}'");

        if (!isset($tables[$tableName])) {
            $tables[$tableName] = new TableDefinition($tableName);
        }

        $table = $tables[$tableName];

        // Collect properties from the class and its traits
        $properties = $this->getAllProperties($ref);

        foreach ($properties as $property) {
            $this->processProperty($property, $table, $className);
        }

        // Collect class-level Index attributes
        $indexAttrs = $ref->getAttributes(Index::class);
        foreach ($indexAttrs as $indexAttr) {
            /** @var Index $index */
            $index = $indexAttr->newInstance();
            /** @var array<string> $columns */
            $columns = array_values(array_filter($index->columns, static fn (mixed $column): bool => is_string($column) && $column !== ''));
            if ($columns === [] || count($columns) !== count($index->columns)) {
                $this->errors[] = "Table '{$table->name}': #[Index] columns must be non-empty strings.";
                continue;
            }

            $table->addIndex(new IndexDefinition(
                columns: $columns,
                unique: $index->unique,
                name: $index->name,
            ));
        }

        // TenantScoped(same_storage): ensure tenant_id column exists for migrations
        $tenantAttrs = $ref->getAttributes(TenantScoped::class);
        if ($tenantAttrs !== []) {
            /** @var TenantScoped $tenantAttr */
            $tenantAttr = $tenantAttrs[0]->newInstance();
            $tenantColumn = 'tenant_id';
            if ($tenantAttr->strategy === 'same_storage' && $table->getColumn($tenantColumn) === null) {
                $table->addColumn(new ColumnDefinition(
                    name: $tenantColumn,
                    type: $this->resolveDefaultType(),
                    phpType: 'string',
                    nullable: false,
                    length: 64,
                    propertyName: 'tenantId',
                ));
            }
        }
    }

    /**
     * @return \ReflectionProperty[]
     */
    private function getAllProperties(\ReflectionClass $ref): array
    {
        $properties = $ref->getProperties();
        $seen = [];
        $result = [];

        foreach ($properties as $prop) {
            if (!isset($seen[$prop->getName()])) {
                $seen[$prop->getName()] = true;
                $result[] = $prop;
            }
        }

        return $result;
    }

    private function processProperty(\ReflectionProperty $property, TableDefinition $table, string $className): void
    {
        $columnAttrs = $property->getAttributes(Column::class);
        $pkAttrs = $property->getAttributes(PrimaryKey::class);
        $deprecatedAttrs = $property->getAttributes(Deprecated::class);

        // Relation attributes
        $this->processRelations($property, $table);

        // Aggregate — no column processing needed
        if (!empty($property->getAttributes(Aggregate::class))) {
            return;
        }

        if ($columnAttrs === []) {
            // Skip internal/trait state (e.g. FilterableTrait __filterCriteria)
            if (str_starts_with($property->getName(), '__')) {
                return;
            }
            // Property without #[Column] in a Resource class — error unless it's a relation
            if ($property->getAttributes(BelongsTo::class) === []
                && $property->getAttributes(HasMany::class) === []
                && $property->getAttributes(OneToOne::class) === []
                && $property->getAttributes(ManyToMany::class) === []
                && $property->getAttributes(Aggregate::class) === []
            ) {
                $this->errors[] = "Property '{$property->getName()}' in '{$className}' has no #[Column] attribute.";
            }
            return;
        }

        /** @var Column $column */
        $column = $columnAttrs[0]->newInstance();

        $isPrimaryKey = !empty($pkAttrs);
        $pkStrategy = 'auto';
        if ($isPrimaryKey) {
            /** @var PrimaryKey $pk */
            $pk = $pkAttrs[0]->newInstance();
            $pkStrategy = $pk->strategy;

            // string PK without explicit strategy
            $phpType = $this->resolvePhpType($property);
            if ($phpType === 'string' && $pkStrategy === 'auto') {
                $this->errors[] = "Property '{$property->getName()}' in '{$className}': string primary key requires explicit strategy.";
            }

            // uuid strategy requires Binary or Varchar column type
            if ($pkStrategy === 'uuid' && $columnAttrs !== []) {
                /** @var Column $colCheck */
                $colCheck = $columnAttrs[0]->newInstance();
                $isBinaryOrVarchar = ($colCheck->type instanceof MySqlType && in_array($colCheck->type, [MySqlType::Binary, MySqlType::Varchar], true))
                    || ($colCheck->type instanceof SqliteType && in_array($colCheck->type, [SqliteType::Binary, SqliteType::Varchar], true));
                if (!$isBinaryOrVarchar) {
                    $this->errors[] = "Property '{$property->getName()}' in '{$className}': uuid strategy requires Binary or Varchar column type.";
                }
            }
        }

        $isDeprecated = !empty($deprecatedAttrs);
        $phpType = $this->resolvePhpType($property);

        $propertyName = $property->getName();
        $columnName   = $column->name ?? $propertyName;

        // Validate PHP type vs MySqlType
        $this->validateTypeMatch($phpType, $column->type, $propertyName, $className);

        $nullable = $column->nullable || ($property->getType() instanceof \ReflectionNamedType && $property->getType()->allowsNull());
        if ($isPrimaryKey) {
            $nullable = false;
        }

        $this->assertValidIdentifier($columnName, "column '{$columnName}' in '{$className}'");

        $colDef = new ColumnDefinition(
            name: $columnName,
            type: $column->type,
            phpType: $phpType,
            nullable: $nullable,
            length: $column->length,
            precision: $column->precision,
            scale: $column->scale,
            default: $column->default,
            isPrimaryKey: $isPrimaryKey,
            pkStrategy: $pkStrategy,
            isDeprecated: $isDeprecated,
            propertyName: $propertyName,
        );

        // Multiple Resources can map to the same table (e.g. base + projection); merge schema — skip column if already defined
        if ($table->getColumn($columnName) !== null) {
            return;
        }

        $table->addColumn($colDef);

        // Auto-index for #[Filterable] columns (single-column, non-unique)
        if (!empty($property->getAttributes(Filterable::class))) {
            $indexName = 'idx_' . $table->name . '_' . $columnName;
            $table->addIndex(new IndexDefinition(
                columns: [$columnName],
                unique: false,
                name: $indexName,
            ));
        }

        if ($isDeprecated) {
            $this->checkDeprecatedUsage($columnName, $table);
        }
    }

    private function processRelations(\ReflectionProperty $property, TableDefinition $table): void
    {
        $propName = $property->getName();

        foreach ($property->getAttributes(BelongsTo::class) as $attr) {
            /** @var BelongsTo $rel */
            $rel = $attr->newInstance();
            $table->addRelation($propName, 'belongs_to', $rel->target, $rel->foreignKey, null, null, $rel->onDelete, $rel->onUpdate);
        }

        foreach ($property->getAttributes(HasMany::class) as $attr) {
            /** @var HasMany $rel */
            $rel = $attr->newInstance();
            $table->addRelation($propName, 'has_many', $rel->target, $rel->foreignKey, null, null, $rel->onDelete, $rel->onUpdate);
        }

        foreach ($property->getAttributes(OneToOne::class) as $attr) {
            /** @var OneToOne $rel */
            $rel = $attr->newInstance();
            $table->addRelation($propName, 'one_to_one', $rel->target, $rel->foreignKey, null, null, $rel->onDelete, $rel->onUpdate);
        }

        foreach ($property->getAttributes(ManyToMany::class) as $attr) {
            /** @var ManyToMany $rel */
            $rel = $attr->newInstance();
            $table->addRelation($propName, 'many_to_many', $rel->target, $rel->foreignKey, $rel->pivotTable, $rel->relatedKey, $rel->onDelete, $rel->onUpdate);
        }
    }

    private function resolvePhpType(\ReflectionProperty $property): string
    {
        $type = $property->getType();

        if ($type instanceof \ReflectionNamedType) {
            return $type->getName();
        }

        if ($type instanceof \ReflectionUnionType) {
            $types = array_map(
                fn(\ReflectionNamedType $t) => $t->getName(),
                array_filter($type->getTypes(), fn($t) => $t instanceof \ReflectionNamedType && $t->getName() !== 'null'),
            );
            return $types[0] ?? 'mixed';
        }

        return 'mixed';
    }

    private function validateTypeMatch(string $phpType, DatabaseType $sqlType, string $propName, string $className): void
    {
        // Backed enums: StringBackedEnum → Varchar/Text, IntBackedEnum → Int/Bigint
        if (enum_exists($phpType)) {
            $ref = new \ReflectionEnum($phpType);
            if ($ref->isBacked()) {
                $backingType = (string) $ref->getBackingType();
                $phpType = $backingType;
            } else {
                $this->errors[] = "Property '{$propName}' in '{$className}': non-backed enum '{$phpType}' cannot be mapped to a database column.";
                return;
            }
        }

        $valid = match (true) {
            $sqlType instanceof MySqlType => $this->validateMySqlTypeMatch($phpType, $sqlType),
            $sqlType instanceof SqliteType => $this->validateSqliteTypeMatch($phpType, $sqlType),
            default => true,
        };

        if (!$valid) {
            $driverName = $sqlType instanceof MySqlType ? 'MySQL' : 'SQLite';
            $typeName = $sqlType->canonicalName();
            $this->errors[] = "Property '{$propName}' in '{$className}': PHP type '{$phpType}' is incompatible with {$driverName} type '{$typeName}'.";
        }
    }

    private function validateMySqlTypeMatch(string $phpType, MySqlType $sqlType): bool
    {
        return match ($sqlType) {
            MySqlType::Varchar, MySqlType::Char,
            MySqlType::Text, MySqlType::MediumText,
            MySqlType::LongText, MySqlType::Time        => in_array($phpType, ['string', 'mixed']),
            MySqlType::Json                             => in_array($phpType, ['string', 'array', 'mixed']),
            MySqlType::TinyInt, MySqlType::SmallInt,
            MySqlType::Int, MySqlType::Bigint,
            MySqlType::Year                             => in_array($phpType, ['int', 'mixed']),
            MySqlType::Float, MySqlType::Double         => in_array($phpType, ['float', 'mixed']),
            MySqlType::Decimal                          => in_array($phpType, ['string', 'float', 'mixed']),
            MySqlType::Boolean                          => in_array($phpType, ['bool', 'int', 'mixed']),
            MySqlType::Datetime, MySqlType::Timestamp,
            MySqlType::Date                             => in_array($phpType, ['DateTimeImmutable', 'DateTime', 'string', 'mixed']),
            MySqlType::Blob, MySqlType::Binary          => in_array($phpType, ['string', 'mixed']),
        };
    }

    private function validateSqliteTypeMatch(string $phpType, SqliteType $sqlType): bool
    {
        return match ($sqlType) {
            SqliteType::Varchar, SqliteType::Char,
            SqliteType::Text, SqliteType::Time       => in_array($phpType, ['string', 'mixed']),
            SqliteType::Datetime, SqliteType::Date   => in_array($phpType, ['DateTimeImmutable', 'DateTime', 'string', 'mixed']),
            SqliteType::Json                          => in_array($phpType, ['string', 'array', 'mixed']),
            SqliteType::TinyInt, SqliteType::SmallInt,
            SqliteType::Int, SqliteType::Bigint       => in_array($phpType, ['int', 'mixed']),
            SqliteType::Float, SqliteType::Double,
            SqliteType::Decimal                       => in_array($phpType, ['float', 'mixed']),
            SqliteType::Boolean                       => in_array($phpType, ['bool', 'int', 'mixed']),
            SqliteType::Blob, SqliteType::Binary      => in_array($phpType, ['string', 'mixed']),
        };
    }

    /**
     * Validate that a SQL identifier (table or column name) contains only
     * safe characters: letters, digits, and underscores, starting with a
     * letter or underscore. Identifiers come from PHP attributes, not user
     * input, but a typo or malformed name would silently produce broken SQL.
     * Throwing early gives a clear error at schema-collect time.
     */
    private function assertValidIdentifier(string $name, string $context): void
    {
        if (!preg_match('/^[a-zA-Z_][a-zA-Z0-9_]*$/', $name)) {
            throw new \InvalidArgumentException(
                "Invalid SQL identifier for {$context}: '{$name}'. "
                . "Only letters, digits and underscores are allowed, starting with a letter or underscore."
            );
        }
    }

    /**
     * Add synthetic table definitions for ManyToMany pivot tables so they are created by orm:sync.
     *
     * @param list<string> $classes FromTable class names
     * @param array<string, TableDefinition> $tables
     */
    private function addPivotTables(array $classes, array &$tables): void
    {
        $classToTable = [];
        foreach ($classes as $className) {
            try {
                $ref = new \ReflectionClass($className);
                $attrs = $ref->getAttributes(FromTable::class);
                if (!empty($attrs)) {
                    /** @var FromTable $ft */
                    $ft = $attrs[0]->newInstance();
                    $classToTable[$className] = $ft->name;
                }
            } catch (\ReflectionException) {
                // skip
            }
        }

        foreach ($tables as $tableName => $table) {
            foreach ($table->getRelations() as $relation) {
                if (($relation['type'] ?? '') !== 'many_to_many') {
                    continue;
                }
                $pivotTable = $relation['pivotTable'] ?? null;
                $foreignKey = $relation['foreignKey'] ?? null;
                $relatedKey = $relation['relatedKey'] ?? null;
                $targetClass = $relation['target'];
                if ($pivotTable === null || $foreignKey === null || $relatedKey === null || $targetClass === '') {
                    continue;
                }
                if (isset($tables[$pivotTable])) {
                    continue; // already added (e.g. same pivot from another side)
                }
                $this->assertValidIdentifier($pivotTable, "pivot table '{$pivotTable}'");
                $targetTable = $classToTable[$targetClass] ?? null;
                if ($targetTable === null) {
                    try {
                        /** @var class-string $targetClass */
                        $ref = new \ReflectionClass($targetClass);
                        $attrs = $ref->getAttributes(FromTable::class);
                        if (!empty($attrs)) {
                            $ft = $attrs[0]->newInstance();
                            $targetTable = $ft->name;
                        }
                    } catch (\ReflectionException) {
                        // skip
                    }
                }
                if ($targetTable === null) {
                    continue;
                }
                $pivot = new TableDefinition($pivotTable);
                $intType = $this->resolveIntType();
                $pivot->addColumn(new ColumnDefinition(
                    name: 'id',
                    type: $intType,
                    phpType: 'int',
                    nullable: false,
                    isPrimaryKey: true,
                    pkStrategy: 'auto',
                ));
                $pivot->addColumn(new ColumnDefinition(
                    name: $foreignKey,
                    type: $intType,
                    phpType: 'int',
                    nullable: false,
                ));
                $pivot->addColumn(new ColumnDefinition(
                    name: $relatedKey,
                    type: $intType,
                    phpType: 'int',
                    nullable: false,
                ));
                $pivot->addIndex(new IndexDefinition(
                    columns: [$foreignKey, $relatedKey],
                    unique: true,
                    name: 'uniq_' . $foreignKey . '_' . $relatedKey,
                ));
                $tables[$pivotTable] = $pivot;
            }
        }
    }

    /**
     * Post-process step: build ForeignKeyDefinition objects for all relations
     * that carry a FK column on the owning side.
     *
     * BelongsTo — FK lives on THIS table → generate FK from this table → target.
     * HasMany    — FK lives on the CHILD table → generate FK from target table → this table.
     * OneToOne   — FK lives on the CHILD/related table → same as HasMany.
     * ManyToMany — FK lives on the pivot table → add FKs from pivot to parent and target.
     *
     * @param array<string, TableDefinition> $tables
     */
    private function resolveForeignKeys(array $tables): void
    {
        // Build a map: table name → PK column name (for reference resolution)
        $pkMap = [];
        foreach ($tables as $tableName => $table) {
            $pk = $table->getPrimaryKey();
            if ($pk !== null) {
                $pkMap[$tableName] = $pk->name;
            }
        }

        // Build a map: resource class name → table name
        $classToTable = [];
        foreach ($tables as $tableName => $table) {
            foreach ($table->getRelations() as $relation) {
                $targetClass = $relation['target'];
                if ($targetClass === '') {
                    continue;
                }
                if (!isset($classToTable[$targetClass])) {
                    try {
                        /** @var class-string $targetClass */
                        $ref = new \ReflectionClass($targetClass);
                        $attrs = $ref->getAttributes(FromTable::class);
                        if (!empty($attrs)) {
                            /** @var \Semitexa\Orm\Attribute\FromTable $ft */
                            $ft = $attrs[0]->newInstance();
                            $classToTable[$targetClass] = $ft->name;
                        }
                    } catch (\ReflectionException) {
                        // skip
                    }
                }
            }
        }

        foreach ($tables as $tableName => $table) {
            foreach ($table->getRelations() as $relation) {
                $type       = $relation['type'];
                $targetClass = $relation['target'];
                $foreignKey = $relation['foreignKey'];
                $onDelete   = $relation['onDelete'] ?? null;
                $onUpdate   = $relation['onUpdate'] ?? null;

                /** @var string|null $onDelete */
                /** @var string|null $onUpdate */
                $targetTable = $classToTable[$targetClass] ?? null;
                if ($targetTable === null) {
                    continue;
                }
                if (!isset($tables[$targetTable]) && $type !== 'belongs_to') {
                    continue;
                }
                if ($type === 'belongs_to' && !isset($tables[$targetTable])) {
                    continue;
                }

                if ($type === 'belongs_to') {
                    // FK is on THIS table — references the target's PK
                    $referencedPk = $pkMap[$targetTable] ?? 'id';
                    $fkCol = $table->getColumn($foreignKey);
                    $nullable = $fkCol !== null && $fkCol->nullable;
                    $resolvedOnDelete = $onDelete ?? ($nullable ? ForeignKeyAction::SetNull : ForeignKeyAction::Restrict);
                    $resolvedOnUpdate = $onUpdate ?? ($nullable ? ForeignKeyAction::SetNull : ForeignKeyAction::Restrict);

                    $table->addForeignKey(new ForeignKeyDefinition(
                        table: $tableName,
                        column: $foreignKey,
                        referencedTable: $targetTable,
                        referencedColumn: $referencedPk,
                        onDelete: $resolvedOnDelete,
                        onUpdate: $resolvedOnUpdate,
                    ));
                } elseif ($type === 'has_many' || $type === 'one_to_one') {
                    // FK is on the TARGET table — references THIS table's PK
                    $referencedPk = $pkMap[$tableName] ?? 'id';
                    $targetTableDef = $tables[$targetTable] ?? null;
                    if ($targetTableDef === null) {
                        continue;
                    }
                    $fkCol = $targetTableDef->getColumn($foreignKey);
                    $nullable = $fkCol !== null && $fkCol->nullable;
                    $resolvedOnDelete = $onDelete ?? ($nullable ? ForeignKeyAction::SetNull : ForeignKeyAction::Restrict);
                    $resolvedOnUpdate = $onUpdate ?? ($nullable ? ForeignKeyAction::SetNull : ForeignKeyAction::Restrict);

                    $targetTableDef->addForeignKey(new ForeignKeyDefinition(
                        table: $targetTable,
                        column: $foreignKey,
                        referencedTable: $tableName,
                        referencedColumn: $referencedPk,
                        onDelete: $resolvedOnDelete,
                        onUpdate: $resolvedOnUpdate,
                    ));
                } elseif ($type === 'many_to_many') {
                    // FK is on the pivot table: pivot.foreignKey -> this table, pivot.relatedKey -> target table
                    $pivotTable = $relation['pivotTable'] ?? null;
                    $relatedKey = $relation['relatedKey'] ?? null;
                    if ($pivotTable === null || $relatedKey === null) {
                        continue;
                    }
                    $pivotDef = $tables[$pivotTable] ?? null;
                    if ($pivotDef === null) {
                        continue;
                    }
                    $parentPk = $pkMap[$tableName] ?? 'id';
                    $targetPk = $pkMap[$targetTable] ?? 'id';
                    $restrict = ForeignKeyAction::Restrict;
                    $pivotDef->addForeignKey(new ForeignKeyDefinition(
                        table: $pivotTable,
                        column: $foreignKey,
                        referencedTable: $tableName,
                        referencedColumn: $parentPk,
                        onDelete: $onDelete ?? $restrict,
                        onUpdate: $onUpdate ?? $restrict,
                    ));
                    $pivotDef->addForeignKey(new ForeignKeyDefinition(
                        table: $pivotTable,
                        column: $relatedKey,
                        referencedTable: $targetTable,
                        referencedColumn: $targetPk,
                        onDelete: $onDelete ?? $restrict,
                        onUpdate: $onUpdate ?? $restrict,
                    ));
                }
            }
        }
    }

    private function checkDeprecatedUsage(string $columnName, TableDefinition $table): void
    {
        foreach ($table->getIndexes() as $index) {
            if (in_array($columnName, $index->columns, true)) {
                $this->warnings[] = "Deprecated column '{$columnName}' in table '{$table->name}' is used in an index.";
            }
        }

        foreach ($table->getRelations() as $relation) {
            if ($relation['foreignKey'] === $columnName) {
                $this->warnings[] = "Deprecated column '{$columnName}' in table '{$table->name}' is used in a relation.";
            }
        }
    }

    private function classDiscovery(): ClassDiscovery
    {
        return $this->classDiscovery ??= new ClassDiscovery();
    }

    /**
     * Resolve the default Varchar type for the current driver.
     */
    private function resolveDefaultType(): DatabaseType
    {
        return $this->driver === 'sqlite' ? SqliteType::Varchar : MySqlType::Varchar;
    }

    /**
     * Resolve the Integer type for the current driver.
     */
    private function resolveIntType(): DatabaseType
    {
        return $this->driver === 'sqlite' ? SqliteType::Int : MySqlType::Int;
    }

}

1<?php23declare(strict_types=1);45namespace App\Application\Handler\Data;67use App\Application\Payload\Data\MerchandisingCatalogPayload;8use App\Application\Resource\Page\MerchandisingCatalogResource;9use App\Domain\Catalog\MerchandisingCatalogRepositoryInterface;10use Semitexa\Core\Attribute\AsPayloadHandler;11use Semitexa\Core\Attribute\InjectAsReadonly;12use Semitexa\Core\Contract\TypedHandlerInterface;1314#[AsPayloadHandler(payload: MerchandisingCatalogPayload::class, resource: MerchandisingCatalogResource::class)]15final class SharedTableExtensionHandler implements TypedHandlerInterface16{17    #[InjectAsReadonly]18    protected MerchandisingCatalogRepositoryInterface $repository;1920    public function handle(MerchandisingCatalogPayload $payload, MerchandisingCatalogResource $resource): MerchandisingCatalogResource21    {22        return $resource->fromProducts($this->repository->listCampaignProducts());23    }24}25

<?php

declare(strict_types=1);

namespace App\Application\Handler\Data;

use App\Application\Payload\Data\MerchandisingCatalogPayload;
use App\Application\Resource\Page\MerchandisingCatalogResource;
use App\Domain\Catalog\MerchandisingCatalogRepositoryInterface;
use Semitexa\Core\Attribute\AsPayloadHandler;
use Semitexa\Core\Attribute\InjectAsReadonly;
use Semitexa\Core\Contract\TypedHandlerInterface;

#[AsPayloadHandler(payload: MerchandisingCatalogPayload::class, resource: MerchandisingCatalogResource::class)]
final class SharedTableExtensionHandler implements TypedHandlerInterface
{
    #[InjectAsReadonly]
    protected MerchandisingCatalogRepositoryInterface $repository;

    public function handle(MerchandisingCatalogPayload $payload, MerchandisingCatalogResource $resource): MerchandisingCatalogResource
    {
        return $resource->fromProducts($this->repository->listCampaignProducts());
    }
}

Design Rules

Why this works without hidden magic

Both modules point to the same physical table name via #[FromTable].

SchemaCollector groups discovered resources by table and only adds missing columns.

The extension module contributes new columns without redefining the catalog columns.

No module needs to reopen the other module's class just to add campaign-specific state.

How it works

SchemaCollector groups discovered ORM resources by table name. When another resource maps to the same table, it adds only missing columns and leaves already-defined columns alone.

Why it matters

This removes one of the most painful ownership traps in modular systems: the first module does not permanently own the whole table forever. Later modules stay additive instead of invasive.

Key concepts

Shared table extension: Multiple ORM resources map to one physical table and extend its schema collaboratively.
SchemaCollector: Collects table definitions from resource attributes and merges columns by table name.
Module isolation: A later module can add persistence fields without reopening the source code of the original module.