Commit

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

class

Commit

Dispatched (via \MMO\commit()) to persist a batch of entity changes -- each listening iRepository (aRepository::onCommit) picks out and stores the entities that belong to it.

class MMO\core\events\Commit extends MMO\core\events\Event implements MMO\core\interfaces\iStoppableEvent, Countable use MMO\core\classes\tStoppableEvent, MMO\core\classes\tWithOptions, MMO\core\classes\tWithEntities

Namespace: MMO\core\events
Extends: Event
Implements: iStoppableEvent, Countable
Uses traits: tStoppableEvent, tWithOptions, tWithEntities

$commit = new Commit($this); $commit->addEntity($person); $commit->dispatch();

Index

	entities
	opts
	stopped
	addEntity($entity)	Add an entity, indexed under its own `iEntity::getId()`.
	addOptions($opts, $appendList)	Merge $opts into the existing options (through `merge`), rather than replacing them wholesale like `setOptions`.
	clearOptions()	Empty the options bag.
	count()	\Countable::count -- number of entities in this commit
	getEntities()
	getEntitiesWithFlags($flags)
	getEntity($id)
	getOption($key, $default)
	getOptions()
	hasEntity($entity)
	isDryRun()
	isPropagationStopped()
	removeEntity($entity)	Remove entity by instance or uid
	setOption($key, $value)	Set (or, with a null $value, remove) a single option.
	setOptions($opts)	Replace the whole options bag.
	sortEntities()	Sort entities so entity without id are stored before any others.
	stopPropagation()	Prevent any remaining listener in the current dispatch chain from being called.
	__clone()	A cloned event starts fresh: propagation is never considered stopped on the clone, even if it was on the original instance.
	__construct($origin, $options)

Properties3

entities

protected $entities = []

opts

protected array $opts = []

Type: array

stopped

protected $stopped = false

Methods19

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()

addOptions($opts, $appendList)

tWithOptions.php:65

Merge $opts into the existing options (through merge), rather than replacing them wholesale like setOptions.

function addOptions(array $opts, bool $appendList = false): void

$opts	array	the options to merge in
$appendList = false	bool	if true, a list-valued option is appended to (rather than replaced by) the corresponding list in $opts -- see \MMO\core\arrays\merge for the exact semantics
returns	void

$t->setOptions(['a' => 1, 'tags' => ['x']]); $t->addOptions(['b' => 2, 'tags' => ['y']]); $t->getOptions(); // ['a' => 1, 'tags' => ['y'], 'b' => 2] -- 'tags' is replaced, not appended ($appendList=false)

clearOptions()

tWithOptions.php:39

Empty the options bag.

function clearOptions(): void

returns

void

$t->clearOptions(); // getOptions() === []

count()

Commit.php:27

\Countable::count -- number of entities in this commit

function count(): int

returns

int

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');

getOption($key, $default)

tWithOptions.php:49

function getOption(string $key, mixed $default = null): mixed

$key	string
$default = null	mixed	returned if $key is not set
returns	mixed

$t->getOption('a', 'fallback'); // the current value of 'a', or 'fallback' if not set

getOptions()

tWithOptions.php:20

function getOptions(): array

returns

array

every option currently set

$t->getOptions(); // ['a' => 1, 'tags' => ['x']]

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

isDryRun()

Commit.php:32

function isDryRun(): bool

returns

bool

true if the 'dryRun' option is set: repositories should validate but not actually persist

isPropagationStopped()

tStoppableEvent.php:21

function isPropagationStopped(): bool

returns bool true once stopPropagation has been called on this instance

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

setOption($key, $value)

tWithOptions.php:77

Set (or, with a null $value, remove) a single option.

function setOption(string $key, mixed $value): void

$key	string
$value	mixed	if null, the option is unset entirely rather than being set to null
returns	void

$t->setOption('a', 1);

$t->setOption('a', null); // removes 'a' from getOptions()

setOptions($opts)

tWithOptions.php:30

Replace the whole options bag.

function setOptions(array $opts): void

$opts	array
returns	void

$t->setOptions(['a' => 1]);

sortEntities()

Commit.php:46

Sort entities so entity without id are stored before any others.

function sortEntities()

NOTE: among two entities that both lack an id, this was meant to further order them so that one referenced by the other commits first (avoiding a dangling reference) -- but the method it called for that, iEntity::hasReference(), does not exist anywhere in the codebase, so this always crashed with "Call to undefined method" as soon as a commit actually contained two new (unsaved) entities. Since correctly detecting one entity's outbound reference to another isn't something this trait can safely reconstruct, the tie-break degrades to "equal" (0) instead of crashing -- the primary id-based ordering still works.

returns

stopPropagation()

tStoppableEvent.php:29

Prevent any remaining listener in the current dispatch chain from being called.

function stopPropagation()

returns

__clone()

tStoppableEvent.php:38

A cloned event starts fresh: propagation is never considered stopped on the clone, even if it was on the original instance.

function __clone()

returns

__construct($origin, $options)

Commit.php:21

function __construct(object|string $origin, array $options = [])

$origin	object \| string
$options = []	array	e.g. ['dryRun' => true] (see `isDryRun`)

Inherited members (12)

	Properties	Declared by	Description
	`Listeners`	Event
	`origin`	Event

Methods	Declared by	Description
`AddListener($handler, $order)`	Event	Register a listener directly (as opposed to `ConnectListeners`'s attribute-based discovery).
`ConnectListeners($obj)`	Event	Scan $obj's methods for #[Listen(EventClass::class)] attributes and register each one as a listener on the matching event class.
`DisconnectListeners($obj)`	Event	Undo a previous `ConnectListeners`: removes every listener that `connect` had registered for $obj on this event class.
`dispatch()`	Event	Invoke every `GetListeners` listener with $this.
`GetListeners()`	Event	Collect every listener for this class, including those registered on its parent classes (so a subclass event is also caught by listeners of its parent event), sorted by ascending $order (ties keep …
`getOrigin()`	Event
`HasListener($handler)`	Event
`RemoveListener($handler)`	Event	Remove the last added handler from the listeners.
`Send($args)`	Event	Construct a new instance of this class with $args, then `dispatch` it to every listener.
`SetListenerOrder($handler, $order)`	Event	Change the order of an already-registered listener, whether added directly via `AddListener` or indirectly via `ConnectListeners` (which also stores its `[$obj, $methodName]` callables here).