Class Atk4\Data\Model

`implements`	`IteratorAggregate<static>`
`uses`	`CollectionTrait, ContainerTrait, DiContainerTrait, DynamicMethodTrait, HintableModelTrait, HookTrait, InitializerTrait, JoinsTrait, ReferencesTrait, UserActionsTrait, ReadableCaptionTrait`

Located at data/src/Model.php

Methods


					
	public

__construct(Persistence $persistence = null, array<string, mixed> $defaults = [])

Creation of the new model can be done in two ways:.

$m = new Model($db); or $m = new Model(); $m->setPersistence($db);

The second use actually calls add() but is preferred usage because:

it's shorter
type hinting will work;
you can specify string for a table

Overriden by


					
	public

isEntity(): bool


					
	public

assertIsModel(self $expectedModelInstance = null): void


					
	public

assertIsEntity(self $expectedModelInstance = null): void


					
	public

getModel(bool $allowOnModel = false): static


					
	public

__clone()


					
	protected

getModelOnlyProperties(): array<string, true>


					
	public

createEntity(): static


					
	protected

init(): void

Extend this method to define fields of your choice.

Overriden by

Atk4\Ui\Table\Column\FilterModel::init()


					
	public

assertIsInitialized(): void


					
	private

initEntityIdAndAssertUnchanged(): void


					
	private

initEntityIdHooks(): void


					
	public

add(Field|Reference|Join $obj, array<string, mixed> $defaults = []): void


					
	public

_addIntoCollection(string $name, object $item, string $collection): object


					
	public
					
					&

getDataRef(): array<string, mixed>


					
	public
					
					&

getDirtyRef(): array<string, mixed>


					
	public

validate(string $intent = null): array<string, string>

Perform validation on a currently loaded values, must return Array in format: ['field' => 'must be 4 digits exactly']…

Perform validation on a currently loaded values, must return Array in format: ['field' => 'must be 4 digits exactly'] or empty array if no errors were present.

You may also use format: ['field' => ['must not have character [ch]', 'ch' => $badCharacter]] for better localization of error message.

Always use return array_merge(parent::validate($intent), $errors);

Parameters

$intent

by default only 'save' is used (from beforeSave) but you can use other intents yourself

Returns

[field => err_spec]


					
	protected

fieldFactory(array<mixed> $seed = []): Field

Given a field seed, return a field object.


					
	public

addField(string $name, array<mixed>|object $seed = []): Field

Adds new field into model.

Overriden by

Atk4\Data\Model\AggregateModel::addField()


					
	public

addFields(array<string, array<mixed>|object>|array<int, string> $fields, array<mixed> $seed = []): $this

Adds multiple fields into model.


					
	public

removeField(string $name): $this

Remove field that was added previously.


					
	public

hasField(string $name): bool


					
	public

getField(string $name): Field


					
	public

setOnlyFields(array<int, string>|null $fields): $this

Sets which fields we will select.


					
	private

assertOnlyField(string $field): void


					
	public

isDirty(string $field): bool

Will return true if specified field is dirty.


					
	public

getFields(string|array<int, string>|null $filter = null): array<string, Field>


					
	public

set(string $field, mixed $value): $this

Set field value.


					
	public

setNull(string $field): $this

Unset field value even if null value is not allowed.


					
	public

setMulti(array<string, mixed> $fields): $this

Helper method to call self::set() for each input array element.

This method does not revert the data when an exception is thrown.


					
	public

get(string $field = null): ($field is null ? array<string, mixed> : mixed)

Returns field value. If no field is passed, then returns array of all field values.


					
	private

assertHasIdField(): void


					
	public

getId(): mixed


					
	public

setId(mixed $value, bool $allowNull = true): $this


					
	public

getModelCaption(): string

Return (possibly localized) $model->caption. If caption is not set, then generate it from model class name.


					
	public

getTitle(): mixed

Return value of $model->get($model->titleField). If not set, returns id value.


					
	public

getTitles(): array<int|string, mixed>

Returns array of model record titles [id => title].


					
	public

compare(string $name, mixed $value): bool


					
	public

_isset(string $name): bool

Does field exist?


					
	public

_unset(string $name): $this

Remove current field value and use default.


					
	public

scope(): RootScope

Get the scope object of the Model.


					
	public

addCondition(
	AbstractScope|array<int, AbstractScope|Expressionable|array{(string|Expressionable), 1?: mixed, 2?: mixed}>|string|Expressionable $field,
	($field is string|Expressionable ? ($value is null ? mixed : string) : never) $operator = null,
	($operator is string ? mixed : never) $value = null,
): $this

Narrow down data-set of the current model by applying additional condition. There is no way to remove condition once…

Narrow down data-set of the current model by applying additional condition. There is no way to remove condition once added, so if you need - clone model.

This is the most basic for defining condition: ->addCondition('my_field', $value);

This condition will work across all persistence drivers universally.

In some cases a more complex logic can be used: ->addCondition('my_field', '>', $value); ->addCondition('my_field', '!=', $value); ->addCondition('my_field', 'in', [$value1, $value2]);

Second argument could be '=', '>', '<', '>=', '<=', '!=', 'in', 'like' or 'regexp'. Those conditions are still supported by most of persistence drivers.

There are also vendor-specific expression support: ->addCondition('my_field', $expr); ->addCondition($expr);

Conditions on referenced models are also supported: $contact->addCondition('company/country', 'US'); where 'company' is the name of the reference This will limit scope of $contact model to contacts whose company country is set to 'US'

Using # in conditions on referenced model will apply the condition on the number of records: $contact->addCondition('tickets/#', '>', 5); This will limit scope of $contact model to contacts that have more than 5 tickets

To use those, you should consult with documentation of your persistence driver.


					
	public

addCteModel(string $name, self $model, bool $recursive = false): $this

Adds WITH/CTE model.


					
	public

setOrder(
	string|array<int, string|array{string, 1?: ('asc'|'desc')}>|array<string, 'asc'|'desc'> $field,
	($field is array ? never : 'asc'|'desc') $direction = 'asc',
): $this

Set order for model records. Multiple calls are allowed.


					
	public

setLimit(int $count = null, int $offset = 0): $this

Set limit of DataSet.


					
	public

issetPersistence(): bool


					
	public

getPersistence(): Persistence

Overriden by

Atk4\Data\Model\AggregateModel::getPersistence()


					
	public

setPersistence(Persistence $persistence): $this


					
	public

assertHasPersistence(string $methodName = null): void


					
	public

isLoaded(): bool

Is entity loaded?


					
	public

assertIsLoaded(): void


					
	public

unload(): $this


					
	private

remapIdLoadToPersistence(mixed $id): mixed


					
	private

_load(
	($fromTryLoad is true ? false : bool) $fromReload,
	bool $fromTryLoad,
	mixed $id,
): ($fromTryLoad is true ? static|null : static)


					
	public

tryLoad(mixed $id): static|null

Try to load record. Will not throw an exception if record does not exist.


					
	public

load(mixed $id): static

Load one record by an ID.


					
	public

tryLoadOne(): static|null

Try to load one record. Will throw if more than one record exists, but not if there is no record.


					
	public

loadOne(): static

Load one record. Will throw if more than one record exists.


					
	public

tryLoadAny(): static|null

Try to load any record. Will not throw an exception if record does not exist.

If only one record should match, use checked "tryLoadOne" method.


					
	public

loadAny(): static

Load any record.

If only one record should match, use checked "loadOne" method.


					
	public

reload(): $this

Reload model by taking its current ID.


					
	public

duplicate(): static

Keeps the model data, but wipes out the ID so when you save it next time, it ends up as a new record in the database.


					
	public

saveAndUnload(array<string, mixed> $data = []): $this

Store the data into database, but will never attempt to reload the data. Additionally any data will be unloaded. Use…

Store the data into database, but will never attempt to reload the data. Additionally any data will be unloaded. Use this instead of save() if you want to squeeze a little more performance out.


					
	public

withPersistence(Persistence $persistence): static

Create new model from the same base class as $this.

See https://github.com/atk4/data/issues/111 for use-case examples.


					
	private

temporaryMutateScopeFieldsBackup(): array<string, array{bool, mixed}>

TODO https://github.com/atk4/data/issues/662.


					
	private

temporaryMutateScopeFieldsRestore(array<string, array{bool, mixed}> $backup): void


					
	private

_loadBy(
	bool $fromTryLoad,
	AbstractScope|array<int, AbstractScope|Expressionable|array{(string|Expressionable), 1?: mixed, 2?: mixed}>|string|Expressionable $field,
	($field is string|Expressionable ? ($value is null ? mixed : string) : never) $operator = null,
	($operator is string ? mixed : never) $value = null,
): ($fromTryLoad is true ? static|null : static)


					
	public

loadBy(
	AbstractScope|array<int, AbstractScope|Expressionable|array{(string|Expressionable), 1?: mixed, 2?: mixed}>|string|Expressionable $field,
	($field is string|Expressionable ? ($value is null ? mixed : string) : never) $operator = null,
	($operator is string ? mixed : never) $value = null,
): static

Load one record by additional condition. Will throw if more than one record exists.


					
	public

tryLoadBy(
	AbstractScope|array<int, AbstractScope|Expressionable|array{(string|Expressionable), 1?: mixed, 2?: mixed}>|string|Expressionable $field,
	($field is string|Expressionable ? ($value is null ? mixed : string) : never) $operator = null,
	($operator is string ? mixed : never) $value = null,
): static|null

Try to load one record by additional condition. Will throw if more than one record exists, but not if there is no…

Try to load one record by additional condition. Will throw if more than one record exists, but not if there is no record.


					
	protected

validateEntityScope(): void


					
	private

assertIsWriteable(): void


					
	public

save(array<string, mixed> $data = []): $this

Save record.


					
	protected

_insert(array<string, mixed> $row): void


					
	public

insert(array<string, mixed> $row): mixed


					
	public

import(array<int, array<string, mixed>> $rows): $this


					
	public

export(
	array<int, string>|null $fields = null,
	string $keyField = null,
	bool $typecast = true,
): ($keyField is string ? array<mixed, array<string, mixed>> : array<int, array<string, mixed>>)

Export DataSet as array of hashes.

Parameters

`$fields`	Names of fields to export
`$keyField`	Optional name of field which value we will use as array key
`$typecast`	Should we typecast exported data


					final
	public

getIterator(): Traversable<static>

Create iterator (yield values).

You can return false in afterLoad hook to prevent to yield this data row, example: $model->onHook(self::HOOK_AFTER_LOAD, static function (Model $m) { if ($m->get('date') < $m->dateFrom) { $m->breakHook(false); } })

You can also use breakHook() with specific object which will then be returned as a next iterator value.

Implements

IteratorAggregate::getIterator()


					
	public

createIteratorBy(
	AbstractScope|array<int, AbstractScope|Expressionable|array{(string|Expressionable), 1?: mixed, 2?: mixed}>|string|Expressionable $field,
	($field is string|Expressionable ? ($value is null ? mixed : string) : never) $operator = null,
	($operator is string ? mixed : never) $value = null,
): Traversable<static>

Create iterator (yield values) by additional condition.


					
	public

delete(mixed $id = null): static

Delete record with a specified id. If no ID is specified then current record is deleted.


					
	public

atomic<T>(Closure(): T $fx): T

Atomic executes operations within one begin/end transaction, so if the code inside callback will fail, then all of the…

Atomic executes operations within one begin/end transaction, so if the code inside callback will fail, then all of the transaction will be also rolled back.


					
	public

action(string $mode, array<mixed> $args = []): Query

Create persistence action.

TODO Rename this method to stress this method should not be used for anything else then reading records as insert/update/delete hooks will not be called.

Overriden by

Atk4\Data\Model\AggregateModel::action()


					
	public

executeCountQuery(): int


					
	public

addExpression(string $name, array{expr: mixed} $seed): CallbackField|SqlExpressionField

Add expression field.


					
	public

addCalculatedField<T is self>(string $name, array{expr: (Closure(T): mixed)} $seed): CallbackField

Add expression field which will calculate its value by using callback.


					
	public

__isset(string $name): bool


					
	public
					
					&

__get(string $name): mixed


					
	public

__set(string $name, mixed $value): void


					
	public

__unset(string $name): void


					
	public

__debugInfo(): array<string, mixed>

Overriden by

Atk4\Data\Model\AggregateModel::__debugInfo()

Methods used from Atk4\Core\CollectionTrait
`_removeFromCollection(), _cloneCollection(), _hasInCollection(), _getFromCollection(), _shortenMl()`

Methods used from Atk4\Core\ContainerTrait
`_uniqueElementName(), _addContainer(), removeElement(), _shorten(), getElement(), hasElement()`

Methods used from Atk4\Core\DiContainerTrait
`setDefaults(), setMissingProperty(), assertInstanceOf(), _fromSeedPrecheck(), fromSeed(), fromSeedUnsafe()`

Methods used from Atk4\Core\DynamicMethodTrait
`__call(), buildMethodHookName(), addMethod(), hasMethod(), removeMethod()`

Methods used from Atk4\Core\HookTrait
`_rebindHookFxToFakeInstance(), _unbindHookFxIfBoundToThis(), _rebindHooksIfCloned(), onHook(), onHookShort(), _makeHookDynamicFx(), onHookDynamic(), onHookDynamicShort(), hookHasCallbacks(), removeHook(), hook(), breakHook()`

Methods used from Atk4\Core\InitializerTrait
`isInitialized(), invokeInit()`

Methods used from Atk4\Data\Model\JoinsTrait
`join(), leftJoin(), hasJoin(), getJoin(), getJoins()`

Methods used from Atk4\Data\Model\ReferencesTrait
`_addReference(), addReference(), hasOne(), hasMany(), containsOne(), containsMany(), hasReference(), getReference(), getReferences(), ref(), refModel(), refLink()`

Methods used from Atk4\Data\Model\UserActionsTrait
`addUserAction(), hasUserAction(), addUserActionFromModel(), getUserActions(), getUserAction(), removeUserAction(), executeUserAction(), initUserActions()`

Methods used from Atk4\Core\ReadableCaptionTrait
`readableCaption()`

Constants
`public`	`HOOK_BEFORE_LOAD = self::class . '@beforeLoad'`	#
`public`	`HOOK_AFTER_LOAD = self::class . '@afterLoad'`	#
`public`	`HOOK_BEFORE_UNLOAD = self::class . '@beforeUnload'`	#
`public`	`HOOK_AFTER_UNLOAD = self::class . '@afterUnload'`	#
`public`	`HOOK_BEFORE_INSERT = self::class . '@beforeInsert'`	#
`public`	`HOOK_AFTER_INSERT = self::class . '@afterInsert'`	#
`public`	`HOOK_BEFORE_UPDATE = self::class . '@beforeUpdate'`	#
`public`	`HOOK_AFTER_UPDATE = self::class . '@afterUpdate'`	#
`public`	`HOOK_BEFORE_DELETE = self::class . '@beforeDelete'`	#
`public`	`HOOK_AFTER_DELETE = self::class . '@afterDelete'`	#
`public`	`HOOK_BEFORE_SAVE = self::class . '@beforeSave'`	#
`public`	`HOOK_AFTER_SAVE = self::class . '@afterSave'`	#
`public`	`HOOK_ROLLBACK = self::class . '@rollback'` Executed when execution of self::atomic() failed. Executed when execution of self::atomic() failed.	#
`public`	`HOOK_NORMALIZE = self::class . '@normalize'` Executed for every field set using self::set() method. Executed for every field set using self::set() method.	#
`public`	`HOOK_VALIDATE = self::class . '@validate'` Executed when self::validate() method is called. Executed when self::validate() method is called.	#
`public`	`HOOK_ONLY_FIELDS = self::class . '@onlyFields'` Executed when self::setOnlyFields() method is called. Executed when self::setOnlyFields() method is called.	#
`protected`	`ID_LOAD_ONE = self::class . '@idLoadOne-h7axmDNBB3qVXjVv'`	#
`protected`	`ID_LOAD_ANY = self::class . '@idLoadAny-h7axmDNBB3qVXjVv'`	#

Properties
`private`	`static\|null`	`$_model = null` not-null if and only if this instance is an entity not-null if and only if this instance is an entity	#
`private`	`mixed`	`$_entityId` once set, loading a different ID will result in an error once set, loading a different ID will result in an error	#
`private static`	`array<string, true>`	`$_modelOnlyProperties`	#
`protected`	`array<mixed>`	`$_defaultSeedAddField = [Field::class]` The seed used by addField() method. The seed used by addField() method.	#
`protected`	`array<mixed>`	`$_defaultSeedAddExpression = [CallbackField::class]` The seed used by addExpression() method. The seed used by addExpression() method.	#
`protected`	`array<string, Field>`	`$fields = []`	#
`public`	`string\|self\|false`	`$table`	#
`public`	`string\|null`	`$tableAlias`	#
`private`	`Persistence\|null`	`$_persistence`	#
`public`	`array<string, mixed>\|null`	`$persistenceData = null` Persistence store some custom information in here that may be useful for them. Persistence store some custom information in here that may be useful for them.	#
`private`	`RootScope`	`$scope`	#
`public`	`array{(int\|null), int}`	`$limit = [null, 0]`	#
`public`	`array<int, array{(string\|Expressionable), ('asc'\|'desc')}>`	`$order = []`	#
`public`	`array<string, array{model: Model, recursive: bool}>`	`$cteModels = []`	#
`private`	`array<string, mixed>`	`$data = []`	#
`private`	`array<string, mixed>`	`$dirty = []`	#
`public`	`bool`	`$readOnly = false` Setting model as readOnly will protect you from accidentally updating the model. This property is intended for UI and… Setting model as readOnly will protect you from accidentally updating the model. This property is intended for UI and other code detecting read-only models and acting accordingly.	#
`public`	`string\|false`	`$idField = 'id'`	#
`public`	`?string`	`$titleField = 'name'` Title field is used typically by UI components for a simple human readable row title/description. Title field is used typically by UI components for a simple human readable row title/description.	#
`public`	`string\|null`	`$caption`	#
`public`	`array<int, string>\|null`	`$onlyFields = null`	#
`public`	`bool`	`$reloadAfterSave = true` Models that contain expressions will automatically reload after save. This is to ensure that any SQL-based calculation… Models that contain expressions will automatically reload after save. This is to ensure that any SQL-based calculation are executed and updated correctly after you have performed any modifications to the fields.	#
`public`	`?self`	`$containedInEntity = null` If this model is "contained into" another entity by using ContainsOne or ContainsMany reference, then this property… If this model is "contained into" another entity by using ContainsOne or ContainsMany reference, then this property will contain reference to owning entity.	#
`public`	`?Reference`	`$ownerReference = null` Only for Reference class Only for Reference class	#
`protected`	`array<string, array<mixed>>`	`$fieldSeedByType = []`	#
`public`	`int`	`$id` @Atk4\Field() Contains ID of the current record. If the… @Atk4\Field() Contains ID of the current record. If the value is null then the record is considered to be new.	#
`public`	`array<string, Field\|Reference\|Join>`	`$elements`	#

Properties used from Atk4\Core\ContainerTrait
`$_elementNameCounts`

Properties used from Atk4\Core\HookTrait
`$hooks, $_hookIndexCounter, $_hookOrigThis`

Properties used from Atk4\Core\InitializerTrait
`$_initialized`

Properties used from Atk4\Data\Model\JoinsTrait
`$_defaultSeedJoin`

Properties used from Atk4\Data\Model\ReferencesTrait
`$_defaultSeedAddReference, $_defaultSeedHasOne, $_defaultSeedHasMany, $_defaultSeedContainsOne, $_defaultSeedContainsMany`

Properties used from Atk4\Data\Model\UserActionsTrait
`$_defaultSeedUserAction, $userActions`

Namespaces

Classes

Exceptions

Class Atk4\Data\Model

Overriden by

Overriden by

Parameters

Returns

Overriden by

Overriden by

Parameters

Implements

Overriden by

Overriden by