Collection

MMO\core\entities · 1 symbol · generated 5 Oct 2026

class

Collection

Entity container.

class MMO\core\entities\Collection implements MMO\core\interfaces\iCollection use MMO\core\classes\tWithEntities

Namespace: MMO\core\entities
Implements: iCollection
Uses traits: tWithEntities

This class is used to store entities, answer to fetch request (call `registerFetch()`) and commit changed entities -- the constructor already calls `registerCommit()`, so \MMO\commit() saves them; call `registerCommit(false)` to opt out.

$col = new Collection(MyEntity::class, $repository, 'my_entities'); $entity = $col->getById('42'); $matches = $col->find(['status' => 'active']);

Index

	entities
	entityClass
	id
	readonly
	repository
	schema
	add($entities)	Load one or more entities into this collection (`tWithEntities::addEntity`).
	addEntity($entity)	Add an entity, indexed under its own `iEntity::getId()`.
	clear()	Detach every loaded entity from this collection and forget them (doesn't delete anything from the repository).
	count()
	createEntity($data)
	debugName()
	drop($clear)	Delete this whole collection from its repository.
	executeFilter($filter, $sorts, $limit, $offset)	Execute the filter locally (ONLY on the entity loaded in the collection).
	executeQuery($query, $opts)	Execute the query locally (ONLY on the entity loaded in the collection).
	find($filter, $fields, $sort, $limit, $offset, $options)	Run a query (via the repository, if any -- see `Repository::executeQuery`) and return the matching entities, loading each into this collection (or reusing the already-loaded instance for a given…
	findOne($filter, $fields, $sort, $offset, $options)	Same as `find`, limited to (and returning) a single entity, or null if none match.
	getById($id, $find)	Get an entity by id
	getEntities()
	getEntitiesWithFlags($flags)
	getEntity($id)
	getEntityClass()
	getId()
	getName()	Get the name of this collection in the repository.
	getOrCreateEntity($data, $local, $coerce)	Try to find a similar entity from data or create the entity
	getRepository()
	getSchema()
	getSearchProperty($name)
	getSimilarEntity($data, $local, $coerce)	Find an entity using its unique properties (declared with `@unique` in the doc comment of the class)
	has($entity)
	hasChanged($flags)
	hasEntity($entity)
	isRegisterCommit()
	jsonSerialize($opts)
	localFind($filter, $sorts, $limit, $offset)	Find locally (ONLY on the entity loaded in the collection).
	localFindOne($filter, $sorts, $offset)	Find locally (ONLY on the entity loaded in the collection).
	onCommit($request)
	query($filter, $fields, $sort, $limit, $offset, $options)	Build a `Query` against this collection (not executed until iterated -- see `find`/`findOne` for that).
	registerCommit($register)	Start (or, with $register false, stop) listening for `Commit` events, so this collection's own changed entities get added to them automatically (`onCommit`).
	removeEntity($entity)	Remove entity by instance or uid
	setEntityClass($class)
	setId($id)
	setRepository($repo)
	setSchema($schema)	Override the schema used for this collection's entities (`getSchema` normally derives it from `getEntityClass` instead).
	uid()
	__construct($class, $repo, $id)

Properties6

entities

protected $entities = []

entityClass

protected string $entityClass

Type: string

id

protected ?string $id

Type: null | string

readonly

bool $readonly = false

Type: bool

repository

#[MMO\core\attributes\NoDump()] protected ?MMO\core\interfaces\iRepository $repository

Type: null | iRepository

schema

protected ?MMO\core\schemas\Schema $schema

Type: null | Schema

Methods40

add($entities)

Collection.php:234

Load one or more entities into this collection (tWithEntities::addEntity).

function add(MMO\core\interfaces\iEntity ...$entities): void

...$entities	iEntity
returns	void

addEntity($entity)

tWithEntities.php:70

Add an entity, indexed under its own iEntity::getId(). An entity with no id (getId() === '' once cast to string), or whose id already maps to a DIFFERENT entity instance, is appended under a plain numeric index instead -- re-adding the SAME instance under an id it already occupies simply overwrites it in place (no duplicate is created).

function addEntity(MMO\core\interfaces\iEntity $entity): MMO\core\interfaces\iEntity

$entity	iEntity
returns	iEntity	$entity, for chaining

$basket->addEntity($product); // indexed under $product->getId()

clear()

Collection.php:140

Detach every loaded entity from this collection and forget them (doesn't delete anything from the repository).

function clear(): void

returns

void

count()

Collection.php:55

function count(): int

returns int the number of entities currently loaded (NOT the total count in the underlying repository -- see Query::$total for that).

createEntity($data)

Collection.php:176

function createEntity(array $data = []): MMO\core\interfaces\iEntity

$data = []	array
returns	iEntity	a new entity, via the repository's own factory if one is set (letting it assign an id etc), otherwise a plain `new` instance.

debugName()

Collection.php:84

function debugName(): string

returns

string

drop($clear)

Collection.php:152

Delete this whole collection from its repository.

function drop(bool $clear = true): bool

$clear = true	bool	if true (default), also `clear` the loaded entities first.
returns	bool

executeFilter($filter, $sorts, $limit, $offset)

Collection.php:346

Execute the filter locally (ONLY on the entity loaded in the collection).

function executeFilter( MMO\core\interfaces\iFilter $filter, array $sorts = [], ?int $limit = null, int $offset = 0 ): Generator

WARNING: if you have a repository, you SHOULD use the repository to execute the query.

$filter	iFilter
$sorts = []	array
$limit = null	null \| int
$offset = 0	int
returns	Generator

executeQuery($query, $opts)

Collection.php:382

Execute the query locally (ONLY on the entity loaded in the collection).

function executeQuery(MMO\core\entities\Query $query, array $opts = []): Generator

WARNING: if you have a repository, you SHOULD use the repository to execute the query.

$query	Query
$opts = []	array
returns	Generator

find($filter, $fields, $sort, $limit, $offset, $options)

Collection.php:288

Run a query (via the repository, if any -- see Repository::executeQuery) and return the matching entities, loading each into this collection (or reusing the already-loaded instance for a given id).

function find( MMO\core\interfaces\iFilter|array|string $filter, array $fields = [], array $sort = [], ?int $limit = null, ?int $offset = null, array $options = [] ): array

$filter	iFilter \| array \| string
$fields = []	array
$sort = []	array
$limit = null	null \| int
$offset = null	null \| int
$options = []	array
returns	array

findOne($filter, $fields, $sort, $offset, $options)

Collection.php:273

Same as find, limited to (and returning) a single entity, or null if none match.

function findOne( MMO\core\interfaces\iFilter|array|string $filter, array $fields = [], array $sort = [], ?int $offset = null, array $options = [] ): ?MMO\core\interfaces\iEntity

$filter	iFilter \| array \| string
$fields = []	array
$sort = []	array
$offset = null	null \| int
$options = []	array
returns	null \| iEntity

getById($id, $find)

Collection.php:246

Get an entity by id

function getById(string $id, bool $find = true): ?MMO\core\interfaces\iEntity

$id	string	the entity's id
$find = true	bool	if false, won't find the entity in the repository if the entity is not already known
returns	null \| iEntity

getEntities()

tWithEntities.php:25

function getEntities(): array

returns array every entity currently in the collection, keyed by id (or numeric index -- see addEntity)

getEntitiesWithFlags($flags)

tWithEntities.php:34

function getEntitiesWithFlags(int $flags): array

$flags	int	a bitmask of iEntity::FLAG_* constants
returns	array	only the entities whose getFlags() has EVERY bit of $flags set

$basket->getEntitiesWithFlags(iEntity::FLAG_CREATED); // entities created during this request

getEntity($id)

tWithEntities.php:57

function getEntity(string|int $id): ?MMO\core\interfaces\iEntity

$id	string \| int
returns	null \| iEntity	null if no entity is indexed under $id

$basket->getEntity('p1');

getEntityClass()

Collection.php:106

function getEntityClass(): string

returns

string

the entity class this collection holds.

getId()

Collection.php:60

function getId(): ?string

returns

null | string

this collection's id within its repository.

getName()

Collection.php:70

Get the name of this collection in the repository.

function getName(): ?string

It is often the same as the id, but sometimes it is different (ex: file repository use collection's id for filename)

returns

null | string

getOrCreateEntity($data, $local, $coerce)

Collection.php:229

Try to find a similar entity from data or create the entity

function getOrCreateEntity(array $data = [], bool $local = false, bool $coerce = true): MMO\core\interfaces\iEntity

$data = []	array	the data to use to find the entity
$local = false	bool	if true, look for the loaded (local) entities in the collection first
$coerce = true	bool	if true, coerce the data
returns	iEntity

getRepository()

Collection.php:89

function getRepository(): ?MMO\core\interfaces\iRepository

returns

null | iRepository

the repository this collection belongs to.

getSchema()

Collection.php:127

function getSchema(): MMO\core\schemas\Schema

returns Schema an explicitly-set schema (setSchema), or the entity class's own declared schema.

getSearchProperty($name)

Collection.php:121

function getSearchProperty(string $name): MMO\core\attributes\SearchProperty

$name	string
returns	SearchProperty	the entity class's declared search behavior for property $name.

getSimilarEntity($data, $local, $coerce)

Collection.php:187

Find an entity using its unique properties (declared with @unique in the doc comment of the class)

function getSimilarEntity(array $data, bool $local = false, bool $coerce = true): ?MMO\core\interfaces\iEntity

$data	array	the data to use to find the entity
$local = false	bool	if true, look for the loaded (local) entities in the collection first
$coerce = true	bool	if true, coerce the data
returns	null \| iEntity

has($entity)

Collection.php:257

function has(MMO\core\interfaces\iEntity|string $entity): bool

$entity	iEntity \| string	an id, or an entity instance.
returns	bool	whether it's currently loaded in this collection.

hasChanged($flags)

Collection.php:164

function hasChanged(int $flags = 7): bool

$flags = 7	int	which `iEntity::FLAG_*` flags count as "changed" (default: changed, removed, or created).
returns	bool	true if any loaded entity has one of them set.

hasEntity($entity)

tWithEntities.php:48

function hasEntity(MMO\core\interfaces\iEntity|string|int $entity): bool

$entity	iEntity \| string \| int	either an entity instance (checked by identity) or an id (checked by key)
returns	bool

$basket->hasEntity($product); // by instance

$basket->hasEntity($product->getId()); // by id

isRegisterCommit()

Collection.php:402

function isRegisterCommit(): bool

returns bool whether registerCommit's listener is currently active.

jsonSerialize($opts)

Collection.php:135

function jsonSerialize(array $opts = []): array

$opts = []	array
returns	array	every loaded entity, keyed by id.

localFind($filter, $sorts, $limit, $offset)

Collection.php:308

Find locally (ONLY on the entity loaded in the collection).

function localFind( MMO\core\interfaces\iFilter|array|string $filter, array $sorts = [], ?int $limit = null, int $offset = 0 ): array

$filter	iFilter \| array \| string
$sorts = []	array
$limit = null	null \| int
$offset = 0	int
returns	array

localFindOne($filter, $sorts, $offset)

Collection.php:327

Find locally (ONLY on the entity loaded in the collection).

function localFindOne( MMO\core\interfaces\iFilter|array|string $filter, array $sorts = [], int $offset = 0 ): ?MMO\core\interfaces\iEntity

$filter	iFilter \| array \| string
$sorts = []	array
$offset = 0	int
returns	null \| iEntity

onCommit($request)

Collection.php:407

function onCommit(MMO\core\events\Commit $request): void

See: Commit listener: add every changed/removed/created loaded entity to the commit.

$request	Commit
returns	void

query($filter, $fields, $sort, $limit, $offset, $options)

Collection.php:265

Build a Query against this collection (not executed until iterated -- see find/findOne for that).

function query( MMO\core\interfaces\iFilter|array|string $filter = [], array $fields = [], array $sort = [], ?int $limit = null, ?int $offset = null, array $options = [] ): MMO\core\entities\Query

$filter = []	iFilter \| array \| string
$fields = []	array
$sort = []	array
$limit = null	null \| int
$offset = null	null \| int
$options = []	array
returns	Query

registerCommit($register)

Collection.php:393

Start (or, with $register false, stop) listening for Commit events, so this collection's own changed entities get added to them automatically (onCommit). Called once by the constructor.

function registerCommit(bool $register = true): self

$register = true	bool
returns	self

removeEntity($entity)

tWithEntities.php:87

Remove entity by instance or uid

function removeEntity(MMO\core\interfaces\iEntity|string|int $entity): ?MMO\core\interfaces\iEntity

$entity	iEntity \| string \| int	the entity to remove or its id
returns	null \| iEntity	null if it was not found in the collection

$basket->removeEntity($product); // by instance: removes every key it was indexed under

$basket->removeEntity('p1'); // by id

setEntityClass($class)

Collection.php:113

function setEntityClass(string $class): void

$class	string
returns	void

setId($id)

Collection.php:75

function setId(?string $id): void

$id	null \| string
returns	void

setRepository($repo)

Collection.php:94

function setRepository(?MMO\core\interfaces\iRepository $repo): void

$repo	null \| iRepository
returns	void

setSchema($schema)

Collection.php:99

Override the schema used for this collection's entities (getSchema normally derives it from getEntityClass instead). @param ?Schema $schema

function setSchema(?MMO\core\schemas\Schema $schema): void

$schema	null \| Schema
returns	void

uid()

Collection.php:80

function uid(): string

returns

string

a globally-unique reference: the repository's own uid, '/', and this collection's id.

__construct($class, $repo, $id)

Collection.php:46

function __construct( string $class, ?MMO\core\interfaces\iRepository $repo = null, ?string $id = null )

$class	string	the entity class this collection holds (`iEntity`).
$repo = null	null \| iRepository
$id = null	null \| string