CoolCMS API

MessageMapper extends Mapper
in package

Application

implements TreeMapperInterface uses TreeTrait

FinalYes

Base Api mapper over a Doctrine repository.

Every concrete mapper declares protected readonly XRepository $repository (a concrete subclass of OrmRepository); the base cannot declare it because PHP property types are invariant and a child could not narrow the type.

The repository returns the generic BaseEntity; narrowing to the service entity is done by the service.

Interfaces

TreeMapperInterface: Mapper of a nested-set tree entity.

Properties

$em : EntityManagerInterface
$repository : MessageRepository

Methods

__construct() : mixed
beginTransaction() : void
closeTreeGap() : Result: Closes the gap in `lft`/`rgt` left by a deleted subtree.
commit() : void
delete() : Result
find() : BaseEntity|null
findAll() : array<string|int, mixed>
findBy() : BaseEntity|null
findDeleteDependents() : array{messageIds: list, commentThreadIds: list, ratingThreadIds: list, assetIds: list}
findRelatedIds() : array<int, int>|null: Returns ids of target entities linked to the parent through the relation collection `$property`.
getTransactionLevel() : int
getTreeSubtree() : Result: Returns ids of the whole subtree of a node plus its `lft`/`rgt` bounds (the basis for deleting the subtree and closing the gap afterwards).
insertTreeNode() : Result: Computes `lft`/`rgt`/`level` of a newly inserted node (after it is saved with `parent_id`); resolves columns via metadata and hands over to the repository ({@see \App\Core\Traits\Api\Models\Repositories\TreeTrait::insertTreeNode()}).
inTreeLock() : Result: Runs the operation under the tree lock of the given `TreeConfig` (table plus scope).
isInTransaction() : bool
moveSubtree() : Result: Moves a whole subtree under another parent; resolves columns via metadata and hands over to the repository ({@see \App\Core\Traits\Api\Models\Repositories\TreeTrait::moveSubtree()}).
moveTreeNode() : Result
recomputeFirstParentIds() : int
reorderTreeChildren() : Result: Reorders the direct children of a parent into the given order (whole subtrees); resolves columns and hands over to the repository ({@see \App\Core\Traits\Api\Models\Repositories\TreeTrait::reorderTreeChildren()}).
resolveThreadRootId() : int|null
rollback() : void
save() : Result
setupEntityManager() : void
updateAllRelations() : Result: Updates all relations of parent entity with given scalar values.
updateColumns() : Result: Updates columns of the given rows and fully replaces to-many relations, all in one transaction.
updateRelations() : Result: Updates existing relation entities in a join/relation table.
resolveRelations() : void
bridgeScalarFkToAssociation() : void: Fills a ManyToOne association from the value of the scalar foreign key that shares the same join column (typically `$menuId` and `menu`, `$pageId` and `page`). Does nothing when the association is not mapped in this entity variant or the scalar is missing or empty (null/0).
doUpdateRelations() : Result
insertRelations() : Result: Inserts relation entities into a join/relation table.
linkOwnedCollections() : void: Links the owning side of owned collections (cascade persist OneToMany, for example translations): sets the back-reference to the parent (`mappedBy`) on every child so that Doctrine writes the FK on flush. Without it newly hydrated children would be saved with a null foreign key (or the insert would fail).
resolveFkIdentifierField() : string|null: Finds the name of the identifier field of the target entity whose database column equals the join column of the back association (`mappedBy`), that is an identifier which is also a foreign key to the parent. Returns null when there is none.
resolveTreeColumn() : string|null: Maps a property to a database column via metadata (scalar field or to-one association join column). Returns null when the property does not exist.
resolveTreeStructure() : TreeStructure|Result: Resolves a `TreeConfig` to table, columns and scope columns via Doctrine metadata.
rollBackOwnedLevel() : Throwable|null: Rolls back the transaction levels opened by this mapper (level above the entry level), never foreign ones.
updateColumnsUnguarded() : Result

$em


        protected
            EntityManagerInterface
    $em

$repository read-only


        protected
            MessageRepository
    $repository

__construct()


    public
                    __construct(MessageRepository $repository) : mixed

Parameters

$repository : MessageRepository

beginTransaction()


    public
                    beginTransaction() : void

closeTreeGap()

Closes the gap in `lft`/`rgt` left by a deleted subtree.


    public
                    closeTreeGap(int $lft, int $rgt, TreeConfig $config) : Result

Parameters

$lft : int
$rgt : int
$config : TreeConfig

Return values

Result

commit()


    public
                    commit() : void

delete()


    public
                    delete(BaseEntity $entity) : Result

Parameters

$entity : BaseEntity

Return values

Result

find()


    public
                    find(int $id[, string|array<string|int, mixed> $includes = [] ]) : BaseEntity|null

Parameters

$id : int
$includes : string|array<string|int, mixed> = []

Return values

BaseEntity|null

findAll()


    public
                    findAll([array<string|int, mixed>|null $filters = [] ][, array<string|int, mixed>|null $orderBys = null ][, int|null $offset = null ][, int|null $limit = null ][, array<string|int, mixed>|null $columns = null ][, bool $computeTotalCount = false ][, string|array<string|int, mixed>|null $includes = [] ]) : array<string|int, mixed>

Parameters

$filters : array<string|int, mixed>|null = []
$orderBys : array<string|int, mixed>|null = null
$offset : int|null = null
$limit : int|null = null
$columns : array<string|int, mixed>|null = null
$computeTotalCount : bool = false
$includes : string|array<string|int, mixed>|null = []

Return values

array<string|int, mixed>

findBy()


    public
                    findBy([array<string|int, mixed>|null $filters = [] ][, string|array<string|int, mixed> $includes = [] ]) : BaseEntity|null

Parameters

$filters : array<string|int, mixed>|null = []
$includes : string|array<string|int, mixed> = []

Return values

BaseEntity|null

findDeleteDependents()


    public
                    findDeleteDependents(array<int, int> $messageIds) : array{messageIds: list, commentThreadIds: list, ratingThreadIds: list, assetIds: list}

Parameters

$messageIds : array<int, int>

Return values

array{messageIds: list, commentThreadIds: list, ratingThreadIds: list, assetIds: list}

findRelatedIds()

Returns ids of target entities linked to the parent through the relation collection `$property`.


    public
                    findRelatedIds(int $parentId, string $property, string $targetAssociation) : array<int, int>|null

For example ('assetRels', 'asset') returns the asset ids of a record gallery. Table and columns come from Doctrine metadata (same as self::updateAllRelations()).

Parameters

$parentId : int
$property : string
$targetAssociation : string

Return values

array<int, int>|null —

null when metadata or the database failed

getTransactionLevel()


    public
                    getTransactionLevel() : int

Return values

int

getTreeSubtree()

Returns ids of the whole subtree of a node plus its `lft`/`rgt` bounds (the basis for deleting the subtree and closing the gap afterwards).


    public
                    getTreeSubtree(int $id, TreeConfig $config) : Result

Parameters

$id : int
$config : TreeConfig

Return values

Result

insertTreeNode()

Computes `lft`/`rgt`/`level` of a newly inserted node (after it is saved with `parent_id`); resolves columns via metadata and hands over to the repository ({@see \App\Core\Traits\Api\Models\Repositories\TreeTrait::insertTreeNode()}).


    public
                    insertTreeNode(int $id, TreeConfig $config) : Result

Parameters

$id : int
$config : TreeConfig

Return values

Result

inTreeLock()

Runs the operation under the tree lock of the given `TreeConfig` (table plus scope).


    public
                    inTreeLock(TreeConfig $config, callable(): Result $operation) : Result

Parameters

$config : TreeConfig
$operation : callable(): Result

Return values

Result

isInTransaction()


    public
                    isInTransaction() : bool

Return values

bool

moveSubtree()

Moves a whole subtree under another parent; resolves columns via metadata and hands over to the repository ({@see \App\Core\Traits\Api\Models\Repositories\TreeTrait::moveSubtree()}).


    public
                    moveSubtree(int $id, int|null $newParentId, TreeConfig $config[, int|null $afterSiblingId = null ][, TreeMoveExpectation|null $expectation = null ]) : Result

Parameters

$id : int
$newParentId : int|null: null moves to the root level
$config : TreeConfig
$afterSiblingId : int|null = null: null = last child, 0 = first child, >0 = after that sibling
$expectation : TreeMoveExpectation|null = null: client contract verified under the lock, null skips the check

Return values

Result

moveTreeNode()


    public
                    moveTreeNode(int $id, int $direction, TreeConfig $config) : Result

Parameters

$id : int
$direction : int
$config : TreeConfig

Return values

Result

recomputeFirstParentIds()


    public
                    recomputeFirstParentIds(int $id) : int

Parameters

$id : int

Return values

int

reorderTreeChildren()

Reorders the direct children of a parent into the given order (whole subtrees); resolves columns and hands over to the repository ({@see \App\Core\Traits\Api\Models\Repositories\TreeTrait::reorderTreeChildren()}).


    public
                    reorderTreeChildren(int|null $parentId, array<int, int> $orderedIds, TreeConfig $config) : Result

Parameters

$parentId : int|null: null is the root level
$orderedIds : array<int, int>: child ids in the new order
$config : TreeConfig

Return values

Result

resolveThreadRootId()


    public
                    resolveThreadRootId(int $parentId) : int|null

Parameters

$parentId : int

Return values

int|null

rollback()


    public
                    rollback() : void

save()


    public
                    save(TEntity $entity[, array<int, string> $skipFields = [] ]) : Result

Parameters

$entity : TEntity
$skipFields : array<int, string> = []

Return values

Result

setupEntityManager()


    public
                    setupEntityManager(EntityManagerInterface $entityManager) : void

Parameters

$entityManager : EntityManagerInterface

updateAllRelations()

Updates all relations of parent entity with given scalar values.


    public
                    updateAllRelations(array<string|int, mixed> $parentEntityIds, string $property, array<string, mixed> $values) : Result

Sets values on every row matching the parent FK.

Parameters

$parentEntityIds : array<string|int, mixed>: Parent entity IDs (scalar or composite-id arrays)
$property : string
$values : array<string, mixed>: relation property name => value

Return values

Result

updateColumns()

Updates columns of the given rows and fully replaces to-many relations, all in one transaction.


    public
                    updateColumns(array<string|int, mixed> $entityIds, array<string, mixed> $values) : Result

A collection (one-to-many) is written as a full replace: delete of all parent rows plus per-row inserts. A failure halfway would leave the parent with part of its history or none (price snapshots of product sets), so a failed Result or an exception rolls everything back. A nested call inside a foreign transaction is handled by DBAL with a savepoint.

IMPORTANT: the mapper owns only the transaction level it opened itself. DBAL lowers the level in finally even after a failed commit or savepoint release, so a blind rollback in catch would throw NoActiveTransaction and hide the original error, or inside a foreign transaction it would roll back the caller's level. Rollback therefore runs only while the level is above the entry level; its own failure is logged and never replaces the primary error or Result (a failed Result with a failed rollback becomes DB_ERROR). An ambiguous commit is not retried.

Parameters

$entityIds : array<string|int, mixed>: ids or composite-id arrays ([prop => value])
$values : array<string, mixed>: property name => new value

Return values

Result

updateRelations()

Updates existing relation entities in a join/relation table.


    public
                    updateRelations(array<string|int, mixed> $parentEntityIds, string $property, array<string|int, object> $relationEntities) : Result

Parameters

$parentEntityIds : array<string|int, mixed>: Parent entity IDs (scalar or composite-id arrays)
$property : string: Association property name on parent entity
$relationEntities : array<string|int, object>: Relation entities with updated values

Return values

Result

resolveRelations()


    protected
                    resolveRelations(object $entity) : void

Parameters

$entity : object

bridgeScalarFkToAssociation()

Fills a ManyToOne association from the value of the scalar foreign key that shares the same join column (typically `$menuId` and `menu`, `$pageId` and `page`). Does nothing when the association is not mapped in this entity variant or the scalar is missing or empty (null/0).


    private
                    bridgeScalarFkToAssociation(object $entity, string $associationName) : void

Parameters

$entity : object
$associationName : string

doUpdateRelations()


    private
                    doUpdateRelations(array<string|int, mixed> $parentEntityIds, AssociationMapping $mapping, array<string|int, object> $relationEntities) : Result

Parameters

$parentEntityIds : array<string|int, mixed>: Parent entity IDs (scalar or composite-id arrays)
$mapping : AssociationMapping: OneToMany/ManyToMany association mapping
$relationEntities : array<string|int, object>: Relation entities with updated values

Return values

Result

insertRelations()

Inserts relation entities into a join/relation table.


    private
                    insertRelations(array<string|int, mixed> $parentEntityIds, AssociationMapping $mapping, array<int, object> $relationEntities) : Result

Parameters

$parentEntityIds : array<string|int, mixed>: Parent entity IDs (scalar or composite-id arrays)
$mapping : AssociationMapping: OneToMany/ManyToMany association mapping
$relationEntities : array<int, object>: relation entities (validated in updateColumnsUnguarded())

Return values

Result

linkOwnedCollections()

Links the owning side of owned collections (cascade persist OneToMany, for example translations): sets the back-reference to the parent (`mappedBy`) on every child so that Doctrine writes the FK on flush. Without it newly hydrated children would be saved with a null foreign key (or the insert would fail).


    private
                    linkOwnedCollections(object $entity) : void

For children whose identifier is itself a foreign key to the parent (typically translations: PK = page_id + language_id, where page_id is also the FK), the scalar identifier is filled from the parent id. Doctrine does not derive it from the association (it is not a derived identity through #[Id] on the association), so it would fail with EntityMissingAssignedId. Works for an existing parent (the id is known); a brand-new parent (the id appears only on flush) needs a two-phase write.

Parameters

$entity : object

resolveFkIdentifierField()

Finds the name of the identifier field of the target entity whose database column equals the join column of the back association (`mappedBy`), that is an identifier which is also a foreign key to the parent. Returns null when there is none.


    private
                    resolveFkIdentifierField(class-string $targetEntity, string $mappedBy) : string|null

Parameters

$targetEntity : class-string
$mappedBy : string

Return values

string|null

resolveTreeColumn()

Maps a property to a database column via metadata (scalar field or to-one association join column). Returns null when the property does not exist.


    private
                    resolveTreeColumn(ClassMetadata<string|int, object> $meta, string $property) : string|null

Parameters

$meta : ClassMetadata<string|int, object>
$property : string

Return values

string|null

resolveTreeStructure()

Resolves a `TreeConfig` to table, columns and scope columns via Doctrine metadata.


    private
                    resolveTreeStructure(TreeConfig $config) : TreeStructure|Result

Returns a failed Result when a property cannot be mapped to a column.

Parameters

$config : TreeConfig

Return values

TreeStructure|Result

rollBackOwnedLevel()

Rolls back the transaction levels opened by this mapper (level above the entry level), never foreign ones.


    private
                    rollBackOwnedLevel(Connection $connection, int $entryLevel, Throwable|null $primary) : Throwable|null

Returns the rollback exception (logged together with $primary), or null on success.

Parameters

$connection : Connection
$entryLevel : int
$primary : Throwable|null

Return values

Throwable|null

updateColumnsUnguarded()


    private
                    updateColumnsUnguarded(array<string|int, mixed> $entityIds, array<string, mixed> $values) : Result

Parameters

$entityIds : array<string|int, mixed>: ids or composite-id arrays ([prop => value])
$values : array<string, mixed>: property name => new value

Return values

Result

MessageMapper extends Mapper in package Application implements TreeMapperInterface uses TreeTrait

Table of Contents

Interfaces

Properties

Methods

Properties

$em

$repository read-only

Methods

__construct()

Parameters

beginTransaction()

closeTreeGap()

Parameters

Return values

commit()

delete()

Parameters

Return values

find()

Parameters

Return values

findAll()

Parameters

Return values

findBy()

Parameters

Return values

findDeleteDependents()

Parameters

Return values

findRelatedIds()

Parameters

Return values

getTransactionLevel()

Return values

getTreeSubtree()

Parameters

Return values

insertTreeNode()

Parameters

Return values

inTreeLock()

Parameters

Tags

Return values

isInTransaction()

Return values

moveSubtree()

Parameters

Return values

moveTreeNode()

Parameters

Return values

recomputeFirstParentIds()

Parameters

Return values

reorderTreeChildren()

Parameters

Return values

resolveThreadRootId()

Parameters

Return values

rollback()

save()

Parameters

Return values

setupEntityManager()

Parameters

updateAllRelations()

Parameters

Return values

updateColumns()

Parameters

Return values

updateRelations()

Parameters

Return values

resolveRelations()

Parameters

MessageMapper extends Mapper
in package

Application

implements TreeMapperInterface uses TreeTrait