CoolCMS API

CustomAssetLibraryTrait

Api operations of the custom code library (a library of code snippets without scope).

  • saveCustomAsset() upserts one snippet (without page links),
  • syncPageCustomAssets() replaces the snippet set of one page,
  • attachCustomAssetToAllPages() links a snippet to every page,
  • detachCustomAssetFromAllPages() removes all links of a snippet (the snippet stays).

Each operation normalizes the payload before the transaction (an invalid payload never touches it), then runs in one DB transaction; a failed Result or an exception inside rolls back. Existence reads run inside the transaction with FOR UPDATE, otherwise a concurrent call could work with a row deleted in the meantime.

IMPORTANT: removing a link never deletes the snippet. A snippet without any page is shown in the library as unassigned instead of disappearing.

The seams are separated so the logic can be tested without DB, DI or network (CustomAssetLibraryTraitTest).

Table of Contents

Methods

attachCustomAssetToAllPages()  : Result
Links the snippet to every page as a one-time action (not a state). Idempotent (`INSERT IGNORE`).
detachCustomAssetFromAllPages()  : Result
Deletes all page links of the snippet; the snippet itself stays.
saveCustomAsset()  : Result
Saves one snippet (new or existing); page links are left untouched, see {@see syncPageCustomAssets()}/{@see attachCustomAssetToAllPages()}/{@see detachCustomAssetFromAllPages()}.
syncPageCustomAssets()  : Result
Replaces the whole snippet set of one page: removes links missing from `$assetIds` and adds the missing ones. Links of other pages are left alone.
attachCustomAssetsToPage()  : void
Links snippets `$assetIds` to page `$pageId` (`INSERT IGNORE`).
attachCustomAssetToAllPagesRows()  : int
Links the snippet to every page (`INSERT IGNORE`) and returns the number of new links.
customAssetExists()  : bool
Whether snippet `$assetId` exists; `FOR UPDATE` locks the row until the transaction ends.
detachCustomAssetFromAllPagesRows()  : int
Deletes all links of the snippet (the snippet stays) and returns the number deleted.
detachCustomAssetsFromPage()  : void
Removes links of snippets `$assetIds` from page `$pageId`; the snippets are never deleted.
fetchExistingCustomAssetIds()  : array<int, int>
Returns which of `$assetIds` exist in the snippet table.
fetchPageCustomAssetIds()  : array<int, int>
Returns ids of snippets linked to page `$pageId`; `FOR UPDATE`.
inCustomAssetLibraryTransaction()  : Result
Wraps the operation in a transaction. Implementations must roll back on a failed `Result` or an exception, must not open a transaction when one is already running, and bump the `CustomAsset` class cache after success.
pageExists()  : bool
Whether page `$pageId` exists; `FOR UPDATE`.
upsertCustomAssetRow()  : int
Upserts a snippet row and returns its id (new or existing).

Methods

attachCustomAssetToAllPages()

Links the snippet to every page as a one-time action (not a state). Idempotent (`INSERT IGNORE`).

public attachCustomAssetToAllPages(int $assetId) : Result
Parameters
$assetId : int
Return values
Result

detachCustomAssetFromAllPages()

Deletes all page links of the snippet; the snippet itself stays.

public detachCustomAssetFromAllPages(int $assetId) : Result
Parameters
$assetId : int
Return values
Result

saveCustomAsset()

Saves one snippet (new or existing); page links are left untouched, see {@see syncPageCustomAssets()}/{@see attachCustomAssetToAllPages()}/{@see detachCustomAssetFromAllPages()}.

public saveCustomAsset(array<int|string, mixed> $row) : Result
Parameters
$row : array<int|string, mixed>
Return values
Result

syncPageCustomAssets()

Replaces the whole snippet set of one page: removes links missing from `$assetIds` and adds the missing ones. Links of other pages are left alone.

public syncPageCustomAssets(int $pageId, array<int|string, mixed> $assetIds) : Result
Parameters
$pageId : int
$assetIds : array<int|string, mixed>
Return values
Result

attachCustomAssetsToPage()

Links snippets `$assetIds` to page `$pageId` (`INSERT IGNORE`).

protected abstract attachCustomAssetsToPage(int $pageId, array<int, int> $assetIds) : void
Parameters
$pageId : int
$assetIds : array<int, int>

attachCustomAssetToAllPagesRows()

Links the snippet to every page (`INSERT IGNORE`) and returns the number of new links.

protected abstract attachCustomAssetToAllPagesRows(int $assetId) : int
Parameters
$assetId : int
Return values
int

customAssetExists()

Whether snippet `$assetId` exists; `FOR UPDATE` locks the row until the transaction ends.

protected abstract customAssetExists(int $assetId) : bool
Parameters
$assetId : int
Return values
bool

detachCustomAssetFromAllPagesRows()

Deletes all links of the snippet (the snippet stays) and returns the number deleted.

protected abstract detachCustomAssetFromAllPagesRows(int $assetId) : int
Parameters
$assetId : int
Return values
int

detachCustomAssetsFromPage()

Removes links of snippets `$assetIds` from page `$pageId`; the snippets are never deleted.

protected abstract detachCustomAssetsFromPage(int $pageId, array<int, int> $assetIds) : void
Parameters
$pageId : int
$assetIds : array<int, int>

fetchExistingCustomAssetIds()

Returns which of `$assetIds` exist in the snippet table.

protected abstract fetchExistingCustomAssetIds(array<int, int> $assetIds) : array<int, int>
Parameters
$assetIds : array<int, int>
Return values
array<int, int>

fetchPageCustomAssetIds()

Returns ids of snippets linked to page `$pageId`; `FOR UPDATE`.

protected abstract fetchPageCustomAssetIds(int $pageId) : array<int, int>
Parameters
$pageId : int
Return values
array<int, int>

inCustomAssetLibraryTransaction()

Wraps the operation in a transaction. Implementations must roll back on a failed `Result` or an exception, must not open a transaction when one is already running, and bump the `CustomAsset` class cache after success.

protected abstract inCustomAssetLibraryTransaction(callable(): Result $work) : Result
Parameters
$work : callable(): Result
Return values
Result

pageExists()

Whether page `$pageId` exists; `FOR UPDATE`.

protected abstract pageExists(int $pageId) : bool
Parameters
$pageId : int
Return values
bool

upsertCustomAssetRow()

Upserts a snippet row and returns its id (new or existing).

protected abstract upsertCustomAssetRow(array{id: int|null, name: string, type: string, placement: string, cookieCategory: string, code: string, active: bool, sort: int, addToNewPages: bool} $asset) : int
Parameters
$asset : array{id: int|null, name: string, type: string, placement: string, cookieCategory: string, code: string, active: bool, sort: int, addToNewPages: bool}
Return values
int
On this page

Search results