Build, persist, release and query

Create a build

$strate = $stratifiedPersist->createNewVersion(
    [BookingItemManager::class],
    scope: 'booking',
    scopeId: 42,
);

createNewStrate() is an alias of createNewVersion(). The method creates a UUID v7 build row with status building.

Persist snapshot rows

/** @var BookingItemEntity $item */
$item = $entityManagerFactory->get(BookingItemManager::class)->newEntity();
$item
    ->setId($uuid)
    ->setBookingId(42)
    ->setSku('BIKE-001');

$stratifiedPersist->persist($item, $strate);
$stratifiedPersist->persistMany($otherItems, $strate);

The service assigns buildStrate immediately before entity persistence. It does not verify that the entity scope-id value matches the build metadata, so the caller must build a consistent snapshot.

Release

$stratifiedPersist->release('booking', 42, $strate);

Release performs these checks and writes:

1. the scope must be configured;
2. the exact build (scope, scopeId, strate) must exist;
3. status must be building or already released;
4. the release pointer is inserted or updated;
5. the build status becomes released.

Calling release again for the same build is idempotent.

For PDO-backed drivers, pointer and build status are persisted through the normal commit path. With the native PostgreSQL driver in core 2.7.x, the package intentionally uses flush() directly to avoid the connection-pool leak caused by the core commit fallback.

Query the released snapshot

$items = $stratifiedPersist->findReleasedByScopeId('booking', 42);

For additional predicates or ordering:

$query = $stratifiedPersist->createReleasedQueryBuilder(
    scope: 'booking',
    alias: 'item',
    scopeIdValue: 42,
);

$query->addOrderBy('sku', 'item');
$items = $entityManagerFactory
    ->get(BookingItemManager::class)
    ->getResult($query);

The generated query always filters on both the configured scope-id field and the released buildStrate. When no release pointer exists, a sentinel strate is used and the result is empty.

Mark a failed build

try {
    // Write the full snapshot.
    $stratifiedPersist->release('booking', 42, $strate);
} catch (Throwable $exception) {
    $stratifiedPersist->markBuildAsFailed($strate);
    throw $exception;
}

Next chapter: Stratified relation graphs