Stratified entities and configuration

Entity contract

Every stratified entity must:

1. extend AbstractEntity;
2. implement StratifiedEntityInterface;
3. declare an id field as a primary key;
4. expose a mapped buildStrate field;
5. expose the configured scope-id field;
6. be managed by an AbstractRelationnalManager.

The provided trait supplies buildStrate, accessors and manual primary-key persistence.

<?php

declare(strict_types=1);

namespace App\Entity;

use Small\SwooleEntityManager\Entity\AbstractEntity;
use Small\SwooleEntityManager\Entity\Attribute\Field;
use Small\SwooleEntityManager\Entity\Attribute\OrmEntity;
use Small\SwooleEntityManager\Entity\Attribute\PrimaryKey;
use Small\SwooleEntityManager\Entity\Enum\FieldValueType;
use Small\SwooleEntityManager\Strates\Contract\StratifiedEntityInterface;
use Small\SwooleEntityManager\Strates\Entity\StratifiedEntityTrait;

#[OrmEntity]
final class BookingItemEntity extends AbstractEntity implements StratifiedEntityInterface
{
    use StratifiedEntityTrait;

    #[PrimaryKey]
    private ?string $id = null;

    #[Field(type: FieldValueType::int)]
    private ?int $bookingId = null;

    #[Field(type: FieldValueType::string)]
    private ?string $sku = null;
}

StratifiedEntityTrait includes ManualPrimaryKeyPersistenceTrait. It preserves non-null application-generated keys in insert payloads while keeping null auto-generated keys omitted.

When buildStrate is declared manually, also use ManualPrimaryKeyPersistenceTrait and implement the interface accessors.

Manager

#[Connection(dbTableName: 'booking_item')]
#[Entity(BookingItemEntity::class)]
final class BookingItemManager extends AbstractRelationnalManager
{
}

Configure scopes

use Small\SwooleEntityManager\Strates\Config\StratifiedEntityConfig;
use Small\SwooleEntityManager\Strates\Service\StratifiedPersist;

$stratifiedPersist = new StratifiedPersist(
    $entityManagerFactory,
    [
        new StratifiedEntityConfig(
            managerClass: BookingItemManager::class,
            scope: 'booking',
            scopeIdField: 'bookingId',
            scopeRoot: true,
        ),
    ],
);

Constructor validation checks:

• duplicate manager registration;
• non-empty scope and scope-id field;
• manager inheritance;
• required id, buildStrate and scope-id fields;
• implementation of StratifiedEntityInterface;
• at most one explicit root manager per scope.

When no manager is explicitly marked scopeRoot: true, the first manager registered for the scope remains the root for backward compatibility.

Next chapter: Build, persist, release and query