objects

Collection

Every item of one collection field - data with no URL of its own, like comments, likes or tags - in a SQLite database at data/collections/{field}.db.

A collection is never part of history, and an item has no files of its own: a file field on one points at a page's file. An item's page is its `parent` (the page's uuid, always set), and the item is open to a visitor exactly when that page is. The query DSL is the registry's, over the same field columns, field_items and search_index tables.
$collection Phlat\Data\Collection 13 methods
Properties (2)
$collection->path string readonly The folder of every collection's database.
$collection->field string readonly
Show
  • atomic Runs $fn as one transaction on this collection: every write in it lands together or none does, and pays for the disk once - the way for a script to write many items.
  • count How many items $query matches, ignoring limit and offset.
  • create Adds an item to the page $parent, whose uuid is required: an item is always added from a page.
  • database The database file.
  • delete Removes the items $query matches (the find() DSL, so `sort=` and `limit=` pick which) and returns how many.
  • find The items $query matches (the registry's query DSL), as Items.
  • get The item with this uuid, if the visitor may open its page.
  • parents How many items each page has, as [page uuid => count] - including pages that no longer exist.
  • reindex Rebuilds the field columns, field_items and search_index from the stored items, for when a field's search or fields options changed, first dropping the columns of fields it no longer declares. $onProgress, when given, is called with how many items are done after each chunk.
  • reparent Moves items to other pages after those pages' uuids changed: [old page uuid => new page uuid].
  • save Merges $data into the item; a locked item accepts nothing but a change to `locked` itself.
  • sum The sum of a number field over the items $query matches.
  • unscoped The same collection without the visitor scope - for a collection field with `scoped: false`.

Methods

atomic

$collection->atomic(callable $fn): mixed

Runs $fn as one transaction on this collection: every write in it lands together or none does, and pays for the disk once - the way for a script to write many items.

Returns what $fn returns.
Parameters (1)
$fn callable

Returns mixed

phlat/src/Data/Collection.php:184

count

$collection->count(string $query = ''): int

How many items $query matches, ignoring limit and offset.

Parameters (1)
$query string = ''

Returns int

phlat/src/Data/Collection.php:120

create

$collection->create(string $parent, array $data = [], string $uuid = '', ?int $created = null, ?int $updated = null): Item

Adds an item to the page $parent, whose uuid is required: an item is always added from a page.

A uuid is minted when none is given; one already in use is a ConflictException. $created and $updated keep the stamps of an item brought from elsewhere.
Parameters (5)
$parent string
$data array = []
$uuid string = ''
$created ?int = null
$updated ?int = null

Returns Item

phlat/src/Data/Collection.php:146

database

$collection->database(): string

The database file.

Returns string

phlat/src/Data/Collection.php:75

delete

$collection->delete(string $query, bool $force = false): int

Removes the items $query matches (the find() DSL, so `sort=` and `limit=` pick which) and returns how many.

The query cannot be empty, so no call empties the collection by accident. A locked item refuses the whole call before any goes, and each item fires `item.delete:before` and `item.delete:after`. `force` is for a page that is going: locked items go too and no events fire. Not narrowed to what the visitor may open, which is the caller's to decide.
Parameters (2)
$query string
$force bool = false

Returns int

phlat/src/Data/Collection.php:229

find

$collection->find(string $query = ''): RecordCollection

The items $query matches (the registry's query DSL), as Items.

Pass a limit for a big collection.
Parameters (1)
$query string = ''

Returns RecordCollection

phlat/src/Data/Collection.php:106

get

$collection->get(string $uuid): ?Item

The item with this uuid, if the visitor may open its page.

Parameters (1)
$uuid string

Returns ?Item

phlat/src/Data/Collection.php:90

parents

$collection->parents(): array

How many items each page has, as [page uuid => count] - including pages that no longer exist.

Returns array

phlat/src/Data/Collection.php:266

reindex

$collection->reindex(?callable $onProgress = null): int

Rebuilds the field columns, field_items and search_index from the stored items, for when a field's search or fields options changed, first dropping the columns of fields it no longer declares. $onProgress, when given, is called with how many items are done after each chunk.

Returns how many items.
Parameters (1)
$onProgress ?callable = null

Returns int

phlat/src/Data/Collection.php:295

reparent

$collection->reparent(array $uuids): int

Moves items to other pages after those pages' uuids changed: [old page uuid => new page uuid].

Returns how many items moved. The items themselves are untouched.
Parameters (1)
$uuids array

Returns int

phlat/src/Data/Collection.php:279

save

$collection->save(string $uuid, array $data): Item

Merges $data into the item; a locked item accepts nothing but a change to `locked` itself.

Parameters (2)
$uuid string
$data array

Returns Item

phlat/src/Data/Collection.php:192

sum

$collection->sum(string $field, string $query = ''): float

The sum of a number field over the items $query matches.

Parameters (2)
$field string
$query string = ''

Returns float

phlat/src/Data/Collection.php:131

unscoped

$collection->unscoped(): static

The same collection without the visitor scope - for a collection field with `scoped: false`.

Returns static

phlat/src/Data/Collection.php:81