Data

Class Data

This class represents a Data object. It extends the DataAbstract class and implements the DataInterface.

• Full name: \PhalconKit\Models\Data
• Parent class: \PhalconKit\Models\Abstracts\DataAbstract
• This class implements: \PhalconKit\Models\Interfaces\DataInterface

Methods

initialize

public initialize(): void

validation

public validation(): bool

Inherited methods

getAllowEmptyOption

protected getAllowEmptyOption(bool $allowEmpty = true): bool|array

Parameters:

shouldSkipOptionalValidation

protected shouldSkipOptionalValidation(array|string $field, bool $allowEmpty): bool

Parameters:

isOptionalEmptyValue

protected isOptionalEmptyValue(mixed $value): bool

Parameters:

genericValidation

Apply generic validation to a validator object.

public genericValidation(\PhalconKit\Filter\Validation|null $validator = null): \PhalconKit\Filter\Validation

Parameters:

Return Value:

The validator object with the generic validation rules applied.

addNotEmptyValidation

Add validation to ensure that a field is not empty

public addNotEmptyValidation(\PhalconKit\Filter\Validation $validator, array|string $field, bool $allowEmpty = false): \PhalconKit\Filter\Validation

Parameters:

Return Value:

The updated validation object

addPresenceValidation

Add presence validation to a field in a validator object

public addPresenceValidation(\PhalconKit\Filter\Validation $validator, array|string $field, bool $allowEmpty = true): \PhalconKit\Filter\Validation

Parameters:

Return Value:

The modified validator object after adding the validation

addUnsignedIntValidation

Add validations for an unsigned integer field

public addUnsignedIntValidation(\PhalconKit\Filter\Validation $validator, array|string $field = 'id', bool $allowEmpty = true): \PhalconKit\Filter\Validation

Parameters:

Return Value:

The updated validation object with the added rules

addUnsignedBigIntValidation

Add basic validations for the specified field to ensure it is an unsigned big integer

public addUnsignedBigIntValidation(\PhalconKit\Filter\Validation $validator, array|string $field = 'id', bool $allowEmpty = true): \PhalconKit\Filter\Validation

Parameters:

Return Value:

The updated validation object

addNumberValidation

Add number validations for a given field

public addNumberValidation(\PhalconKit\Filter\Validation $validator, array|string $field, int $min, int $max, bool $allowEmpty = true): \PhalconKit\Filter\Validation

Parameters:

Return Value:

The modified validation object with the number validations added

addStringLengthValidation

Add string length validations for a field

public addStringLengthValidation(\PhalconKit\Filter\Validation $validator, array|string $field, int $minChar = 0, int $maxChar = 255, bool $allowEmpty = true): \PhalconKit\Filter\Validation

Parameters:

Return Value:

The validation object with the added validations

addInclusionInValidation

Add inclusion validation for a field

public addInclusionInValidation(\PhalconKit\Filter\Validation $validator, array|string $field, array $domainList = [], bool $allowEmpty = true): \PhalconKit\Filter\Validation

Parameters:

Return Value:

The updated validation object with the inclusion validation added

addBooleanValidation

Add basic validations for a boolean field - Must not be empty - Must be a boolean value (1, 0, true, false)

public addBooleanValidation(\PhalconKit\Filter\Validation $validator, array|string $field, bool $allowEmpty = true): \PhalconKit\Filter\Validation

Parameters:

Return Value:

The updated validation object

addInclusionValidation

Add inclusion validation for a specified field

public addInclusionValidation(\PhalconKit\Filter\Validation $validator, array|string $field, array $domain = [], bool $allowEmpty = true, bool $strict = true): \PhalconKit\Filter\Validation

This method adds an inclusion validation rule to the given validator object for the specified field. The inclusion rule checks if the value of the field is included in the specified domain.

Parameters:

Return Value:

The updated validator object

addUniquenessValidation

Add uniqueness validation for the specified field(s)

public addUniquenessValidation(\PhalconKit\Filter\Validation $validator, string|array $field, bool $allowEmpty = true): \PhalconKit\Filter\Validation

Parameters:

Return Value:

The modified validation object

addEmailValidation

Add email validation to a field

public addEmailValidation(\PhalconKit\Filter\Validation $validator, array|string $field, bool $allowEmpty = true): \PhalconKit\Filter\Validation

Parameters:

Return Value:

The modified validator object

addDateValidation

Add basic validations for the date field - Must not be empty - Must be a valid date in the specified format

public addDateValidation(\PhalconKit\Filter\Validation $validator, array|string $field, bool $allowEmpty = true, string $format = \PhalconKit\Db\Column::DATE_FORMAT): \PhalconKit\Filter\Validation

Parameters:

Return Value:

The updated validation object

addDateTimeValidation

Add basic validations for the datetime field - Must not be empty - Must be a valid datetime format

public addDateTimeValidation(\PhalconKit\Filter\Validation $validator, array|string $field, bool $allowEmpty = true, string $format = \PhalconKit\Db\Column::DATETIME_FORMAT): \PhalconKit\Filter\Validation

Parameters:

Return Value:

The updated validation object

addJsonValidation

Add validations for a JSON field - Must not be empty (unless allowEmpty is set to true) - Must be a valid JSON string

public addJsonValidation(\PhalconKit\Filter\Validation $validator, array|string $field, bool $allowEmpty = true, int $depth = 512, int $flags = 0): \PhalconKit\Filter\Validation

Parameters:

Return Value:

The updated validator object

addColorValidation

Add basic validations for the color field - Must not be empty (unless $allowEmpty is set to true) - Must be a valid hex color code

public addColorValidation(\PhalconKit\Filter\Validation $validator, array|string $field, bool $allowEmpty = true): \PhalconKit\Filter\Validation

Parameters:

Return Value:

The modified validation object

addIdValidation

Add basic validations for the id field - Must be an unsigned integer

public addIdValidation(\PhalconKit\Filter\Validation $validator, string $field = 'id'): \PhalconKit\Filter\Validation

Parameters:

Return Value:

The updated validation object

addPositionValidation

Add position validation to a validator object.

public addPositionValidation(\PhalconKit\Filter\Validation $validator, string $field = 'position', bool $allowEmpty = true, bool $allowRawValue = true): \PhalconKit\Filter\Validation

Parameters:

Return Value:

The updated validator object with the position validation added.

addSoftDeleteValidation

Add soft delete validation to a validator object.

public addSoftDeleteValidation(\PhalconKit\Filter\Validation $validator, string $field = 'deleted', bool $allowEmpty = true): \PhalconKit\Filter\Validation

Parameters:

Return Value:

The updated validator object with the soft delete validation added.

addUuidValidation

Add UUID validation to a validator object.

public addUuidValidation(\PhalconKit\Filter\Validation $validator, string $field = 'uuid', bool $allowEmpty = false): \PhalconKit\Filter\Validation

Parameters:

Return Value:

The updated validator object with the UUID validation added.

addCrudValidation

Add CRUD validation to a validator object.

public addCrudValidation(\PhalconKit\Filter\Validation $validator, string $userIdField, string $dateField, bool $allowEmpty = true): \PhalconKit\Filter\Validation

Parameters:

Return Value:

The updated validator object with the CRUD validation added.

addCreatedValidation

Add created validation to a validator object.

public addCreatedValidation(\PhalconKit\Filter\Validation $validator, string $createdByField = 'createdBy', string $createdAtField = 'createdAt', bool $allowEmpty = true): \PhalconKit\Filter\Validation

Parameters:

Return Value:

The updated validator object with the created validation added.

addUpdatedValidation

Add updated validation to a validator object.

public addUpdatedValidation(\PhalconKit\Filter\Validation $validator, string $updatedByField = 'updatedBy', string $updatedAtField = 'updatedAt', bool $allowEmpty = true): \PhalconKit\Filter\Validation

Parameters:

Return Value:

The updated validator object with the updated validation added.

addDeletedValidation

Add deleted validation to a validator object.

public addDeletedValidation(\PhalconKit\Filter\Validation $validator, string $deletedField = 'deletedBy', string $dateField = 'deletedAt', bool $allowEmpty = true): \PhalconKit\Filter\Validation

Parameters:

Return Value:

The updated validator object with the deleted validation added.

addRestoredValidation

Add restored validation to a validator object.

public addRestoredValidation(\PhalconKit\Filter\Validation $validator, string $restoredByField = 'restoredBy', string $restoredAtField = 'restoredAt', bool $allowEmpty = true): \PhalconKit\Filter\Validation

Parameters:

Return Value:

The updated validator object with the restored validation added.

initializeUuid

Initialize the UUID transform behavior for create validation.

public initializeUuid(array<string,mixed>|null $options = null): void

Options default to the model options manager under uuid. Supported keys are:

• field: target attribute name, default uuid
• native: when true, use database UUID() expressions
• binary: when true, store UUIDs as binary values

Parameters:

Throws:

When the security service cannot be resolved through the PhalconKit DI contract. - ServiceException

getBinaryUuid

Convert a canonical UUID string to its packed binary representation.

private getBinaryUuid(string $uuid): string

Parameters:

Return Value:

Binary bytes suitable for binary UUID columns.

setUuidBehavior

Register the UUID transform behavior under the standard behavior name.

public setUuidBehavior(\PhalconKit\Mvc\Model\Behavior\Transformable $uuidBehavior): void

Parameters:

Throws:

When the current models manager does not expose the PhalconKit behavior registry. - ServiceException

getUuidBehavior

Retrieve the registered UUID transform behavior.

public getUuidBehavior(): \PhalconKit\Mvc\Model\Behavior\Transformable

Return Value:

Transformable behavior responsible for UUID values.

Throws:

When the current models manager does not expose the PhalconKit behavior registry. - ServiceException

initializeSoftDelete

Initializing SoftDelete

public initializeSoftDelete(?array $options = null): void

Parameters:

setSoftDeleteBehavior

Set the SoftDeleteBehavior variable Attach the SoftDelete behavior class

public setSoftDeleteBehavior(\PhalconKit\Mvc\Model\Behavior\SoftDelete $softDeleteBehavior): void

Parameters:

getSoftDeleteBehavior

Return the soft delete behavior instance

public getSoftDeleteBehavior(): \PhalconKit\Mvc\Model\Behavior\SoftDelete

disableSoftDelete

Disable the soft delete for the current instance Note: SoftDelete behavior must be attached

public disableSoftDelete(): void

enableSoftDelete

Enable the soft delete for the current instance Note: SoftDelete behavior must be attached

public enableSoftDelete(): void

isDeleted

Helper method to check if the row is soft deleted

public isDeleted(?string $field = null, ?int $deletedValue = null): bool

Parameters:

restore

Restore a previously Soft-deleted entry and fire events Events: - beforeRestore - notRestored - afterRestore

public restore(?string $field = null, ?int $notDeletedValue = null): bool

The native ORM events flag is read from INI here because the trait can be used without access to the original model setup options.

Parameters:

keepSnapshots

protected keepSnapshots(bool $keepSnapshot): void

• This method is abstract. Parameters:

getModelsMetaData

public getModelsMetaData(): \Phalcon\Mvc\Model\MetaDataInterface

• This method is abstract.

getChangedFields

public getChangedFields(): array

• This method is abstract.

getSnapshotData

public getSnapshotData(): array

• This method is abstract.

hasSnapshotData

public hasSnapshotData(): bool

• This method is abstract.

initializeSnapshot

Initialize the snapshot for the model.

public initializeSnapshot(array|null $options = null): void

Parameters:

setSnapshotBehavior

Set the SnapshotBehavior for the model

public setSnapshotBehavior(\PhalconKit\Mvc\Model\Behavior\Snapshot $snapshotBehavior): void

Parameters:

getSnapshotBehavior

Get the SnapshotBehavior instance for the model.

public getSnapshotBehavior(): \PhalconKit\Mvc\Model\Behavior\Snapshot

Return Value:

The SnapshotBehavior instance.

getSnapshotChangedFields

Return model fields whose raw values differ from the stored snapshot.

public getSnapshotChangedFields(array<int,string> $ignoreFields = []): list<string>

Phalcon's native getChangedFields() reports the extension's current dirty tracking state. This helper complements it for audit, domain comparison, replication, and response-building code that needs a stable snapshot-versus-current diff expressed with application model field names.

Snapshot arrays can be keyed by either database column names or mapped model field names. Returned fields are normalized through the model column map whenever metadata is available, unknown snapshot entries are ignored, and current values are read through readAttribute() so model getters do not format values or trigger domain side effects during comparison.

The ignore list accepts database column names and mapped model field names. Use it for lifecycle or bookkeeping fields such as updatedAt, updatedBy, updatedAs, or their database-column equivalents. Nullable fields preserve PhalconKit's SQL "NULL" string convention by comparing those values as null when metadata marks the field nullable.

When Phalcon has no snapshot for the model, the method falls back to native getChangedFields(), still applying column-map normalization and the ignore list. This method is intentionally not a replacement for native dirty tracking and should not be used as the sole authorization context for sensitive flows such as password reset or privileged account changes.

Parameters:

Return Value:

Mapped model field names whose snapshot value differs from the current raw attribute value.

Throws:

When the trait host cannot expose Phalcon's raw entity attribute API. - LogicException

hasChangedCallback

Creates a closure that can be used as a callback to determine if a model attribute has changed.

public hasChangedCallback(callable $callback, bool $anyField = true): \Closure

Parameters:

Return Value:

A closure that takes a Model instance and a field name as arguments, and returns the result of the callback function if the attribute has changed, or the value of the attribute if it has not changed.

getSnapshotFieldContext

Build the field metadata used to normalize snapshot keys and comparisons.

private getSnapshotFieldContext(): array{columnMap: array<string,string>, databaseFields: array<string,true>|null, modelFields: array<string,true>|null, nullableFields: array<string,true>}

Metadata access is best-effort because callers can use model doubles or partially bootstrapped models in tests. When metadata is unavailable the helper keeps field names as provided, which mirrors Phalcon's native changed-field behavior without inventing mappings.

normalizeNativeChangedFields

Normalize native changed-field output through the same mapped-name rules.

private normalizeNativeChangedFields(array<int,mixed> $changedFields, array<string,true> $ignoredFields, array{columnMap: array<string,string>, databaseFields: array<string,true>|null, modelFields: array<string,true>|null, nullableFields: array<string,true>} $context): list<string>

Native Phalcon changed fields are used only when no snapshot is available. If metadata cannot identify a field, the original native name is kept so the fallback remains faithful to Phalcon's own result.

Parameters:

normalizeSnapshotFieldName

Convert database-column snapshot keys and ignore entries to model fields.

private normalizeSnapshotFieldName(string $field, array{columnMap: array<string,string>, databaseFields: array<string,true>|null, modelFields: array<string,true>|null, nullableFields: array<string,true>} $context): ?string

When metadata knows the model fields, unknown snapshot keys return null so relation payloads or transient data stored alongside snapshots do not create false changed-field results.

Parameters:

normalizeSnapshotIgnoredFields

Normalize ignore-list entries once so comparisons stay simple.

private normalizeSnapshotIgnoredFields(array<int,string> $ignoreFields, array{columnMap: array<string,string>, databaseFields: array<string,true>|null, modelFields: array<string,true>|null, nullableFields: array<string,true>} $context): array<string,true>

Parameters:

normalizeSnapshotColumnMap

Normalize a Phalcon metadata column map into string keys and values.

private normalizeSnapshotColumnMap(array<array-key,int|string> $columnMap): array<string,string>

Parameters:

Return Value:

Database column name to mapped model field.

normalizeSnapshotComparisonValue

Normalize comparison values for nullable SQL NULL-string conventions.

private normalizeSnapshotComparisonValue(string $field, mixed $value, array<string,true> $nullableFields): mixed

PhalconKit already converts "NULL" strings to null before persistence for nullable attributes. The snapshot diff mirrors that rule during comparison, without mutating the model or its snapshot arrays.

Parameters:

requireSnapshotEntity

Require the trait host to expose Phalcon's raw entity attribute API.

private requireSnapshotEntity(): \Phalcon\Mvc\EntityInterface

Snapshot comparison intentionally avoids magic property access and domain getters. If a downstream class composes this trait outside a Phalcon entity, fail with a framework-scoped exception instead of a late method error from readAttribute().

Throws:

When the trait host is not a Phalcon entity. - LogicException

initializeSlug

Initializes the slug behavior for the model.

public initializeSlug(array|null $options = null): void

Parameters:

setSlugBehavior

Sets the slug behavior for the model.

public setSlugBehavior(\PhalconKit\Mvc\Model\Behavior\Transformable $slugBehavior): void

Parameters:

getSlugBehavior

Returns the slug behavior associated with the model.

public getSlugBehavior(): \PhalconKit\Mvc\Model\Behavior\Transformable

Return Value:

The slug behavior associated with the model.

initializeSecurity

Initializes the security

public initializeSecurity(array|null $options = null): void

Parameters:

setSecurityBehavior

Sets the security behavior

public setSecurityBehavior(\PhalconKit\Mvc\Model\Behavior\Security $securityBehavior): void

Parameters:

getSecurityBehavior

Retrieves the security behavior

public getSecurityBehavior(): \PhalconKit\Mvc\Model\Behavior\Security

Return Value:

The security behavior instance.

setConnectionService

Set the default connection service used by Phalcon for this model.

public setConnectionService(string $connectionService): void

Implemented by Phalcon's model base class.

• This method is abstract. Parameters:

setReadConnectionService

Set the read connection service used by Phalcon for this model.

public setReadConnectionService(string $connectionService): void

• This method is abstract. Parameters:

setWriteConnectionService

Set the write connection service used by Phalcon for this model.

public setWriteConnectionService(string $connectionService): void

• This method is abstract. Parameters:

getWriteConnectionService

Return the configured write connection service name.

public getWriteConnectionService(): string

• This method is abstract. Return Value:

DI service name for write operations.

getReadConnectionService

Return the configured read connection service name.

public getReadConnectionService(): string

• This method is abstract. Return Value:

DI service name for read operations.

getModelsManager

Return the model manager responsible for connection selection.

public getModelsManager(): \Phalcon\Mvc\Model\ManagerInterface

Phalcon's manager applies transaction and sticky-write state before resolving the configured read service.

• This method is abstract.

getReplicationLag

Return the configured replica lag window in milliseconds.

public static getReplicationLag(): int|null

• This method is static. Return Value:

Lag window, or null before replication initialization.

setReplicationLag

Set the replica lag window in milliseconds.

public static setReplicationLag(int|null $replicationLag = null): void

• This method is static. Parameters:

getReplicationReadyAt

Return the timestamp after which replica reads may resume.

public static getReplicationReadyAt(): int|null

• This method is static. Return Value:

Unix timestamp in milliseconds, or null when reads are not currently pinned to the write connection.

setReplicationReadyAt

Set the timestamp after which replica reads may resume.

public static setReplicationReadyAt(int|null $replicationReadyAt = null): void

• This method is static. Parameters:

initializeReplication

Initialize read/write connection services for replica-aware models.

public initializeReplication(array<array-key,mixed>|null $options = null): void

The trait reads database.drivers.readonly.enable from the config service. When enabled, it configures connection service names and attaches write-event listeners that temporarily pin reads to the write connection.

Parameters:

Throws:

When the config service cannot be resolved through the PhalconKit DI contract. - ServiceException

selectReadConnection

Select the connection used for model reads.

public selectReadConnection(): \Phalcon\Contracts\Db\Adapter\Adapter

During the replica-cooldown window, the write connection is returned directly. Otherwise selection is delegated to Phalcon's model manager so transactions and native sticky-write state still take precedence over the configured read service.

Return Value:

Read connection when replicas are ready; write connection while reads are pinned after a mutation.

Throws:

When the read or write connection service cannot be resolved through the PhalconKit DI contract. - ServiceException

addReadWriteConnectionBehavior

Attach lifecycle listeners that pin reads to the write connection.

public addReadWriteConnectionBehavior(): void

Each write-like event updates replicationReadyAt to now + lag. Native Phalcon requires a compatible events manager to attach these callbacks.

Throws:

When the model events manager is missing or does not implement Phalcon's events manager contract. - ServiceException

isReplicationReady

Determine whether reads may use a replica again.

public isReplicationReady(): bool

When the cooldown has expired, the ready timestamp is cleared so future calls remain ready until another write event updates it.

Return Value:

True when the replica cooldown is absent or expired.

nowMs

Return the current process time in milliseconds.

protected static nowMs(): int

This helper keeps replication timestamps integer-based and easy to compare without leaking floating-point microtime values into public replication state.

• This method is static. Return Value:

Unix timestamp in milliseconds.

appendMessage

public appendMessage(\Phalcon\Messages\MessageInterface $message): \Phalcon\Mvc\ModelInterface

• This method is abstract. Parameters:

setStrictRelatedAssignment

Enable or disable strict validation for relationship payloads.

public setStrictRelatedAssignment(bool $strictRelatedAssignment): void

Leave this disabled for legacy forms that may send extra nested data. Enable it in API/resource layers where relation aliases are controlled by explicit save-field policies and a malformed relation should fail loudly.

Parameters:

isStrictRelatedAssignment

Return whether malformed relationship payloads should throw exceptions.

public isStrictRelatedAssignment(): bool

setRelationshipOptions

Replace the configured relationship behavior options.

public setRelationshipOptions(array $options): void

The option group is intentionally stored in the shared model options manager so applications can opt into stricter behavior per model without changing generated relationship declarations.

Parameters:

getRelationshipOptions

Return relationship options, optionally including a per-alias override.

public getRelationshipOptions(?string $alias = null): array

Parameters:

getConfiguredRelationshipOptions

Read relationship defaults from bootstrap config when available.

private getConfiguredRelationshipOptions(): array<string,mixed>

The config path is intentionally feature-specific (model.relationship) rather than part of the generic model options manager.

getRelationshipOption

Return one configured relationship behavior option.

public getRelationshipOption(string $option, ?string $alias = null, mixed $default = null): mixed

Parameters:

getRelationshipAliasOptions

private getRelationshipAliasOptions(array $configured, string $alias): array

Parameters:

setKeepMissingRelated

Set the missing related configuration list

public setKeepMissingRelated(array $keepMissingRelated): void

Parameters:

getKeepMissingRelated

Return the missing related configuration list

public getKeepMissingRelated(): array<string,bool>

getKeepMissingRelatedAlias

Return the keepMissing configuration for a specific relationship alias

public getKeepMissingRelatedAlias(string $alias): bool

Parameters:

setKeepMissingRelatedAlias

Set the keepMissing configuration for a specific relationship alias

public setKeepMissingRelatedAlias(string $alias, bool $keepMissing): void

Parameters:

getRelationshipContext

Get the current relationship context

public getRelationshipContext(): string

setRelationshipContext

Set the current relationship context

public setRelationshipContext(string $context): void

Parameters:

getDirtyRelated

Return the dirtyRelated entities

public getDirtyRelated(): array<string,mixed>

setDirtyRelated

Set the dirtyRelated entities

public setDirtyRelated(array $dirtyRelated): void

Parameters:

getDirtyRelatedAlias

Return the dirtyRelated entities

public getDirtyRelatedAlias(string $alias): mixed

Parameters:

setDirtyRelatedAlias

Return the dirtyRelated entities

public setDirtyRelatedAlias(string $alias, mixed $value): void

Parameters:

hasDirtyRelated

Check whether the current entity has dirty related or not

public hasDirtyRelated(): bool

hasDirtyRelatedAlias

Check whether the current entity has dirty related or not

public hasDirtyRelatedAlias(string $alias): bool

Parameters:

getLoadedRelated

Return the eager-loaded related entities

public getLoadedRelated(): array<string,mixed>

setLoadedRelated

Set the eager-loaded related entities

public setLoadedRelated(array $loadedRelated): void

Parameters:

getLoadedRelatedAlias

Return eager-loaded related entities for one alias

public getLoadedRelatedAlias(string $alias): mixed

Parameters:

setLoadedRelatedAlias

Set eager-loaded related entities for one alias

public setLoadedRelatedAlias(string $alias, mixed $value): void

Parameters:

hasLoadedRelatedAlias

Check whether an eager-loaded relation alias exists

public hasLoadedRelatedAlias(string $alias): bool

Parameters:

setRelated

Store a related value in both Phalcon's native relation cache and PhalconKit's read-only eager-loading cache.

public setRelated(string $alias, mixed $records): \Phalcon\Mvc\ModelInterface

Phalcon 5.18's native eager loader calls this method while hydrating find(['eager' => [...]]) results. Mirroring the value keeps direct property access, getRelated(), exports, and native isRelationshipLoaded() checks consistent without marking the relation for persistence.

Parameters:

Return Value:

The current model instance.

normalizeRelationAlias

private normalizeRelationAlias(string $alias): string

Parameters:

normalizeRelationAliases

private normalizeRelationAliases(array $related): array

Parameters:

writeDeclaredRelatedAlias

private writeDeclaredRelatedAlias(string $alias, mixed $value): void

Parameters:

assign

Assigns values to the model from an array, with options to control which fields are assigned.

public assign(array $data, array|null $whiteList = null, array|null $dataColumnMap = null): \Phalcon\Mvc\ModelInterface

Handles related records using assignRelated method and passes remaining values to the parent's assign method.

Parameters:

Return Value:

Returns the updated ModelInterface instance.

Throws:

• InvalidArgumentException

assignRelated

Assign related

public assignRelated(array $data, array|null $whiteList = null, array|null $dataColumnMap = null): \Phalcon\Mvc\ModelInterface

Single [alias => new Alias()] // create new alias

Many [alias => [new Alias()]] // create new alias [alias => [1, 2, 3, 4]] // append / merge 1, 2, 3, 4 [alias => [false, 1, 2, 4]]; // delete 3

Parameters:

Throws:

• InvalidArgumentException

isRelatedAssignmentWhiteListed

Check whether a relation alias is allowed by a nested assignment whitelist.

private isRelatedAssignmentWhiteListed(string $alias, array $whiteList): bool

The whitelist can contain relation aliases as plain values or as keys that point to nested allowed fields. This mirrors existing PhalconKit save-field payloads without forcing callers to choose one representation.

Parameters:

isRelationPayload

Determine whether an unknown key carries relationship-shaped data.

private isRelationPayload(mixed $value): bool

Scalar unknown keys are left to native model assignment. Complex values are the only safe candidates for strict relationship-alias validation because they are how REST/save payloads express nested relations.

Parameters:

isModelAssignmentField

Check whether a non-relation assignment key is a known model field.

private isModelAssignmentField(string $field, ?array $dataColumnMap = null): bool

Strict relationship assignment must not reject JSON/array columns or mapped model attributes just because their values look like nested relation payloads. The optional data column map is checked first because callers may use external request keys that Phalcon maps before writing.

Parameters:

isDirectOwnedRelationType

private isDirectOwnedRelationType(?int $type): bool

Parameters:

assertDirectRelatedRecordCanBeAssigned

private assertDirectRelatedRecordCanBeAssigned(?string $alias, ?int $type, array $relationFields, array $referencedFields, \Phalcon\Mvc\EntityInterface $record): void

Parameters:

getDirectRelatedOwnershipState

private getDirectRelatedOwnershipState(array $relationFields, array $referencedFields, \Phalcon\Mvc\EntityInterface $record): string

Parameters:

isEmptyRelationValue

private isEmptyRelationValue(mixed $value): bool

Parameters:

isSameRelationValue

private isSameRelationValue(mixed $expected, mixed $actual): bool

Parameters:

prepareDirectRelatedRecordForSave

private prepareDirectRelatedRecordForSave(\Phalcon\Mvc\Model\RelationInterface $relation, \Phalcon\Mvc\EntityInterface $record, ?string $alias, ?int $index = null): bool

Parameters:

preSaveRelatedRecords

Saves related records that must be stored prior to save the master record Refactored based on the native cphalcon version, so we can support : - combined keys on relationship definition - relationship context within the model messages based on the alias definition

protected preSaveRelatedRecords(\Phalcon\Db\Adapter\AdapterInterface $connection, \Phalcon\Mvc\ModelInterface[] $related, \Phalcon\Support\Collection\CollectionInterface $visited): bool

Parameters:

Throws:

• InvalidArgumentException

postSaveRelatedRecords

Processes the saving of related records for the current model.

protected postSaveRelatedRecords(\Phalcon\Db\Adapter\AdapterInterface $connection, array|object[]|\Phalcon\Mvc\ModelInterface[] $related, \Phalcon\Support\Collection\CollectionInterface $visited): bool

Performs operations based on relationship types such as HAS_MANY, HAS_ONE, HAS_MANY_THROUGH, etc. Handles automatic deletion of missing related records and ensures correct binding and transaction management.

NOTE: we need this, this behavior only happens: - in many-to-many nodes Fix uniqueness on combined keys in node entities, and possibly more...

Parameters:

Return Value:

Returns true on successful processing of related records, false if an error occurs.

Throws:

Throws an exception if there are no defined relations for a given alias or if invalid data types are provided. - InvalidArgumentException

See Also:

• https://forum.phalconphp.com/discussion/2190/many-to-many-expected-behaviour
• http://stackoverflow.com/questions/23374858/update-a-records-n-n-relationships
• https://github.com/phalcon/cphalcon/issues/2871

postSaveRelatedRecordsAfter

Handles the saving process of related records after the parent record's save operation.

public postSaveRelatedRecordsAfter(\Phalcon\Mvc\Model\RelationInterface $relation, array|object[]|\Phalcon\Mvc\ModelInterface[] $relatedRecords, \Phalcon\Support\Collection\CollectionInterface $visited): bool|null

It assigns referenced fields to the related records and ensures they are saved with proper relationships maintained. If the relation is defined as Through, this method skips further processing.

Parameters:

Return Value:

Returns true if all related records are saved successfully, false if an error occurs during saving, and null if the relation is of type Through.

Throws:

If there is an error during the save operation for a related record. - InvalidArgumentException

postSaveRelatedThroughAfter

Handles saving related records for through relationships after the primary records have been saved.

public postSaveRelatedThroughAfter(\Phalcon\Mvc\Model\RelationInterface $relation, array|object[]|\Phalcon\Mvc\ModelInterface[] $relatedRecords, \Phalcon\Support\Collection\CollectionInterface $visited): bool|null

Primarily used to manage intermediate models and ensure proper linkage and saving of related records in many-to-many or has-one-through relationships.

Parameters:

Return Value:

Returns true if all related records and intermediate records were successfully saved. Returns false if any save operation failed. Returns null if the relation is not a through relationship.

Throws:

If the intermediate model or related records cannot be properly saved. - InvalidArgumentException

findFirstByPrimaryKeys

Find the first record by its primary key attributes.

public findFirstByPrimaryKeys(array $data, string|null $modelClass): \Phalcon\Mvc\ModelInterface|\Phalcon\Mvc\Model\Row|null

Parameters:

Return Value:

The found record entity.

getEntityFromData

Get the entity object from the given data.

public getEntityFromData(array $data, array $configuration = []): \Phalcon\Mvc\ModelInterface|\Phalcon\Mvc\Model\Row|null

It will try to find the existing record and then assign the new data. - Will first try using the primary key of the related record - Then will try using the defined relationship fields using the relationship alias

Parameters:

Return Value:

The entity object or null if not found.

appendMessages

public appendMessages(array $messages = [], ?string $context = null, ?int $index = null): void

Parameters:

appendMessagesFromRecord

Appends messages from a record to the current messages container.

public appendMessagesFromRecord(\Phalcon\Mvc\ModelInterface|null $record = null, string|null $context = null, int|null $index = null): void

Parameters:

appendMessagesFromResultset

Append messages from a resultset to the current message container.

public appendMessagesFromResultset(\Phalcon\Mvc\Model\ResultsetInterface|null $resultset = null, string|null $context = null, int|null $index = null): void

Parameters:

appendMessagesFromRecordList

Appends messages from a record list to the current message container.

public appendMessagesFromRecordList(iterable|null $recordList = null, string|null $context = null, int|null $index = null): void

Parameters:

rebuildMessageContext

Rebuilds the message context.

public rebuildMessageContext(\Phalcon\Messages\Message $message, string|null $context = null): string

This method appends the given context to the previous context stored in the message metadata. If there is no previous context, only the given context is returned.

Parameters:

Return Value:

The rebuilt context

rebuildMessageIndex

Rebuilds the message index.

public rebuildMessageIndex(\Phalcon\Messages\Message $message, int|null $index = null): string

This method constructs the new message index based on the provided $index argument and the previous index stored in the message's metadata. It returns the new index as a string.

Parameters:

Return Value:

The new index as a string

relatedToArray

Retrieves the related records as an array.

public relatedToArray(array|null $columns = null, bool $useGetter = true): array<string,mixed>

If $columns is provided, only the specified columns will be included in the array. If $useGetter is set to true, it will use the getter methods of the related records.

Parameters:

Return Value:

The related records as an array

getRelated

Overriding default phalcon getRelated in order to fix an important issue where the related record is being stored into the "related" property and then passed from the collectRelatedToSave and is mistakenly saved without the user consent

public getRelated(string $alias, mixed $arguments = null): mixed

Parameters:

Return Value:

Cached related data or the models manager query result.

Throws:

• InvalidArgumentException

toArray

Returns the instance as an array representation

public toArray(array $columns = null, bool $useGetter = true): array

Parameters:

initializePosition

Initializes the position behavior for the current object.

public initializePosition(array|null $options = null): void

Sets the position options and sets the position behavior accordingly.

Parameters:

setPositionBehavior

Sets the position behavior for the current object.

public setPositionBehavior(\PhalconKit\Mvc\Model\Behavior\Position $positionBehavior): void

Parameters:

getPositionBehavior

Retrieves the position behavior attached to the current object.

public getPositionBehavior(): \PhalconKit\Mvc\Model\Behavior\Position

Return Value:

The position behavior object.

Throws:

if the position behavior is not found. - LogicException

reorder

Reorders the current object's position in the list.

public reorder(int|null $position = null, string|null $positionField = null): bool

• Update position+1 done using afterSave event

Parameters:

Return Value:

Returns true if the reorder operation was successful, false otherwise.

Throws:

When the trait is used on an incompatible model. - LogicException

requirePositionModel

Require the trait host to be a PhalconKit model.

protected requirePositionModel(): \PhalconKit\Mvc\Model

Position reordering depends on model events, assignment, snapshots, and persistence APIs. This helper keeps reorder() readable while producing a deterministic PhalconKit exception if the trait is composed into an incompatible class.

Throws:

When the trait host is not a PhalconKit model. - LogicException

initializeOptions

Initialize the Options Manager for the current instance

public initializeOptions(): void

getOptionsManager

Get the Options Manager for the current instance

public getOptionsManager(): \PhalconKit\Support\Options\ManagerInterface

Return Value:

The Options Manager for the current instance

setOptionsManager

Sets the options manager.

public setOptionsManager(\PhalconKit\Support\Options\ManagerInterface $optionsManager): void

Parameters:

getColumnMap

Get the column mapping of the model

public getColumnMap(): array|null

Return Value:

The column mapping of the model, or null if no mapping is defined

getPrimaryKeys

Retrieves the primary keys attributes of the model.

public getPrimaryKeys(): array

Return Value:

Array containing the primary keys of the model.

getPrimaryKeysValues

Retrieves the values of the primary keys attributes of the entity.

public getPrimaryKeysValues(): array

Return Value:

Array containing the values of the primary keys attributes of the entity.

_

Translate a key through the model's translate service.

public _(string $translateKey, array<array-key,mixed> $placeholders = []): string

This is a model-level convenience wrapper around Phalcon's translate adapter. It keeps model validation messages and computed labels aligned with the same translate service used by the rest of the application.

Parameters:

Return Value:

Translated string returned by the adapter.

Throws:

When the translate service cannot be resolved through the PhalconKit DI contract. - ServiceException

__call

Dispatch missing method calls to locale-suffixed methods when available.

public __call(string $method, array<array-key,mixed> $arguments): mixed

For example, with locale fr, a call to label() will try labelFr() before delegating to the parent model magic handler. This is intended for computed localized accessors, not for replacing explicit public methods.

Parameters:

Return Value:

Localized method result, or the parent magic-call result.

Throws:

When the parent Phalcon model magic handler rejects the missing method. - Exception When the locale service cannot be resolved through the PhalconKit DI contract. - ServiceException

__set

Handles dynamic model writes before Phalcon sees them.

public __set(string $property, mixed $value): void

Parameters:

__get

Handles dynamic model reads before Phalcon sees them.

public __get(string $property): mixed

Parameters:

prepareLifeCycleQuery

Apply safety defaults to a lifecycle query builder.

public static prepareLifeCycleQuery(\Phalcon\Mvc\Model\Query\BuilderInterface $builder, array<string,mixed>|null $parameters = null): void

A model with no resolved policy query should never accidentally match all records. When parameters are empty, the builder receives a false condition and empty bind arrays so the resulting query is intentionally empty.

• This method is static. Parameters:

getLifeCyclePolicy

Return the lifecycle policy configured for the current model class.

public static getLifeCyclePolicy(): array<string,mixed>

The config maps model class names to policy names under dataLifeCycle.models; the policy payload is then read from dataLifeCycle.policies. Missing mappings return an empty policy.

• This method is static. Return Value:

Policy payload for the calling model class.

Throws:

When the default DI or config service cannot be resolved through the PhalconKit DI contract. - ServiceException

getLifeCyclePolicyQuery

Return only the lifecycle query portion of the configured policy.

public static getLifeCyclePolicyQuery(): array<string,mixed>|null

• This method is static. Return Value:

Query definition accepted by Phalcon's model query builder, or null when no policy query is configured.

Throws:

When the lifecycle policy cannot be resolved. - ServiceException

getLifeCycleQuery

Build the executable lifecycle query for the current model class.

public static getLifeCycleQuery(array<string,mixed>|null $parameters = null, \Phalcon\Mvc\Model\Query\BuilderInterface|null $builder = null): \Phalcon\Mvc\Model\QueryInterface

Callers may pass explicit query parameters or a preconfigured builder for tests and custom lifecycle workflows. When both are omitted, the configured policy query is used.

• This method is static. Parameters:

Return Value:

Executable query for lifecycle processing.

Throws:

When the default DI or models manager service cannot be resolved through the PhalconKit DI contract. - ServiceException

getBuilder

Create a lifecycle query builder for the current model class.

public static getBuilder(array<string,mixed>|null $parameters = null): \Phalcon\Mvc\Model\Query\BuilderInterface

The builder is initialized from the provided parameters and forced to use the calling model class as its from model. A top-level limit parameter is applied explicitly because Phalcon's builder parameters do not always preserve that value when lifecycle tasks construct custom arrays.

• This method is static. Parameters:

Return Value:

Builder scoped to the calling model class.

Throws:

When the default DI or models manager service cannot be resolved through the PhalconKit DI contract. - ServiceException

findLifeCycle

Execute the lifecycle query and return matching records.

public static findLifeCycle(array<string,mixed>|null $parameters = null): mixed

If a resultset is returned and the policy parameters include a hydration value, the resultset hydrate mode is updated before returning it to the caller. Non-resultset query outputs are returned untouched to preserve native Phalcon behavior.

• This method is static. Parameters:

Return Value:

Query execution result, usually a Phalcon model resultset.

Throws:

When the lifecycle query cannot be built because required DI services are unavailable or incompatible. - ServiceException

jsonEncode

Encodes a value to JSON.

public jsonEncode(mixed $value, int $flags = \PhalconKit\Mvc\Model\Traits\JSON_UNESCAPED_SLASHES, int $depth = 512): string|false

Parameters:

Return Value:

The JSON encoded string on success, or false on failure.

jsonDecode

Decodes a JSON string.

public jsonDecode(string $json, bool|null $associative = null, int $depth = 512, int $flags = 0): mixed

Parameters:

Return Value:

The decoded value on success, or the original JSON string on failure.

validateJsonDepth

Validates that the provided depth is within the supported JSON recursion range.

private validateJsonDepth(int $depth): int<1, 2147483647>

Parameters:

Return Value:

The validated depth.

Throws:

If depth is outside the valid range. - InvalidArgumentException

loadInstance

public static loadInstance(): static

• This method is static.

getIdentityService

Resolve the current identity manager from the model DI.

public getIdentityService(): \PhalconKit\Identity\ManagerInterface

The service must implement PhalconKit\Identity\ManagerInterface; this allows applications to provide custom identity managers without extending the concrete core manager class.

Return Value:

Current identity manager service.

Throws:

When the identity service cannot be resolved through the PhalconKit DI contract. - ServiceException

isLoggedIn

Check whether the current identity is logged in.

public isLoggedIn(bool $as = false): bool

Parameters:

Return Value:

True when the requested identity state is authenticated.

Throws:

When the identity service cannot be resolved through the PhalconKit DI contract. - ServiceException

isLoggedInAs

Check whether the current identity is acting as another user.

public isLoggedInAs(): bool

Return Value:

True when a delegated/impersonated user is active.

Throws:

When the identity service cannot be resolved through the PhalconKit DI contract. - ServiceException

getCurrentUser

Return the current user model from the identity service.

public getCurrentUser(bool $as = false): \PhalconKit\Models\Interfaces\UserInterface|null

Parameters:

Return Value:

Current user, delegated user, or null when no matching identity is available.

Throws:

When the identity service cannot be resolved through the PhalconKit DI contract. - ServiceException

getCurrentUserAs

Return the delegated user model from the identity service.

public getCurrentUserAs(): \PhalconKit\Models\Interfaces\UserInterface|null

Return Value:

Delegated/impersonated user, or null when no delegated identity is active.

Throws:

When the identity service cannot be resolved through the PhalconKit DI contract. - ServiceException

getCurrentUserId

Return the integer ID of the current or delegated user.

public getCurrentUserId(bool $as = false): int|null

Parameters:

Return Value:

User ID cast to int, or null when no user is available or the user does not expose an ID.

Throws:

When the identity service cannot be resolved through the PhalconKit DI contract. - ServiceException

getCurrentUserIdCallback

Build a callback that returns the current or delegated user ID.

public getCurrentUserIdCallback(bool $as = false): callable

Behaviors can store this closure and evaluate it later during lifecycle events, ensuring they use the identity state at execution time rather than initialization time.

Parameters:

Return Value:

Callback returning the requested user ID or null.

hash

Hash a string

public hash(string $string, string|null $salt = null, string|null $workFactor = null): string

Parameters:

Return Value:

The salted hash value of the input string

Throws:

When the config or security service cannot be resolved through the PhalconKit DI contract. - ServiceException

checkHash

Checks whether a given hash is valid for a given string.

public checkHash(string|null $hash = null, string|null $string = null, int $maxPassLength = 0): bool

Parameters:

Return Value:

Returns true if the hash is valid for the string, false otherwise.

Throws:

When the config or security service cannot be resolved through the PhalconKit DI contract. - ServiceException

findInById

public static findInById(array $idList = []): \Phalcon\Mvc\Model\ResultsetInterface

• This method is static. Parameters:

expose

public expose(?array $columns = null, ?bool $expose = null, ?bool $protected = null): array

Parameters:

fireEventCancel

public fireEventCancel(string $eventName): bool

• This method is abstract. Parameters:

ensureTraversableResultset

private static ensureTraversableResultset(\Phalcon\Mvc\Model\ResultsetInterface $resultset): \Phalcon\Mvc\Model\ResultsetInterface&\Traversable

• This method is static. Parameters:

find

Run Phalcon's native static finder for the model using this trait.

public static find(mixed $parameters = null): \Phalcon\Mvc\Model\ResultsetInterface

The explicit mixed parameter mirrors PhalconKit's patched phalcon/ide-stubs contract for Phalcon\Mvc\Model::find(). Keeping the abstract dependency in sync with the upstream model API prevents static analyzers and downstream projects from seeing this trait as a narrower, incompatible declaration.

Eager loading requires an iterable Phalcon resultset because findWith() delegates the returned records to the eager-loading loader.

• This method is static. This method is abstract. Parameters:*

Return Value:

Resultset returned by the concrete model implementation.

findFirst

Run Phalcon's native static first-record finder for the model using this trait.

public static findFirst(mixed $parameters = null): mixed

Phalcon can return a model instance, a row, false, null, or another value depending on hydration and extension behavior, so this dependency keeps the same broad mixed return declared by the patched Phalcon stubs. findFirstWith() narrows that value at runtime and only eager-loads when a real model instance is returned.

• This method is static. This method is abstract. Parameters:*

Return Value:

Native result returned by the concrete model implementation.

count

Counts the number of records that match the given parameters.

public static count(mixed $parameters = null): \Phalcon\Mvc\Model\ResultsetInterface|int

This method wraps the core static count model call with beforeCount/afterCount cancellable events. The "beforeCount" event can cancel the operation. Since Phalcon 5.16's native contract cannot return false for count(), cancellation returns 0.

• This method is static. Parameters:

Return Value:

The count result or a ResultsetInterface, depending on the implementation.

See Also:

• \Phalcon\Mvc\Model::count()

sum

Executes a sum operation on the underlying data with optional parameters.

public static sum(mixed $parameters = null): \Phalcon\Mvc\Model\ResultsetInterface|float

This method supports cancellable events triggered before and after execution. If the "beforeSum" event cancels the operation, this method returns 0.0 to satisfy Phalcon 5.16's native return contract.

• This method is static. Parameters:

Return Value:

Returns the sum result as a float or a result set interface.

See Also:

• \Phalcon\Mvc\Model::sum()

average

Calculates the average of results based on the provided parameters. It wraps the method execution with before/after cancellable events.

public static average(array $parameters = []): \Phalcon\Mvc\Model\ResultsetInterface|float

Example events triggered: - beforeAverage() - afterAverage()

If the "beforeAverage" event cancels the operation, 0.0 is returned to satisfy Phalcon 5.16's native return contract.

• This method is static. Parameters:

Return Value:

The calculated average or a ResultsetInterface, depending on the implementation.

See Also:

• \Phalcon\Mvc\Model::average()

minimum

Calculates the minimum value of a specified column in the database according to the given conditions.

public static minimum(mixed $parameters = null): \Phalcon\Mvc\Model\ResultsetInterface|float|false

• This method is static. Parameters:

Return Value:

Returns the minimum value as a float, a ResultsetInterface object, or false if no matching records are found or the operation fails.

maximum

Calculates the maximum value of a specified column in the database based on the given conditions.

public static maximum(mixed $parameters = null): \Phalcon\Mvc\Model\ResultsetInterface|float|false

• This method is static. Parameters:

Return Value:

Returns the computed maximum value as a float, a ResultsetInterface object for detailed results, or false on failure.

fireEventCancelCall

Wraps core static model calls (find, findFirst, count, sum, average, minimum, maximum) with beforeX/afterX cancellable events.

public static fireEventCancelCall(string $method, callable $callable): mixed

Example (beforeX/afterX events): - beforeAverage() - beforeSum() - beforeCount() - beforeFind() - beforeFindFirst() - afterAverage() - afterSum() - afterCount() - afterFind() - afterFindFirst()

Returns false if the "beforeX" event cancels the operation. Callers whose native Phalcon contracts cannot return false must normalize this sentinel before returning.

• This method is static. Parameters:

findWith

Example:

public static findWith(array $arguments): array

$limit = 100;
$offset = max(0, $this->request->getQuery('page', 'int') - 1) * $limit;

$manufacturers = Manufacturer::with('Robots.Parts', [
    'limit' => [$limit, $offset]
]);

foreach ($manufacturers as $manufacturer) {
    foreach ($manufacturer->robots as $robot) {
        foreach ($robot->parts as $part) { ... }
    }
}

• This method is static. Parameters:

findFirstWith

Same as EagerLoadingTrait::findWith() for a single record

public static findFirstWith(array $arguments): ?\Phalcon\Mvc\ModelInterface

• This method is static. Parameters:

with

public static with(array $arguments): array

• This method is static. Warning: this method is deprecated. This means that this method will likely be removed in a future version. Parameters:*

See Also:

• static::findWith()

firstWith

public static firstWith(array $arguments): ?\Phalcon\Mvc\ModelInterface

• This method is static. Warning: this method is deprecated. This means that this method will likely be removed in a future version. Parameters:*

See Also:

• static::findFirstWith()

__callStatic

Dynamically handles static method calls for the class, forwarding them to appropriate internal methods based on the method name patterns.

public static __callStatic(string $method, array $arguments = []): array|\Phalcon\Mvc\ModelInterface|null

The method provides a mechanism to resolve calls like "findFirstWithBy..."/"firstWithBy..." and "findWithBy..."/"withBy..." to their corresponding mapped operations.

The static magic method keeps the existing PhalconKit findWithBy* surface. Moving this to native missingMethods() remains a compatibility decision because it would change where dynamic calls are intercepted.

• This method is static. Parameters:

Return Value:

Returns the result of the forwarded operation, which may be an array, an implementation of ModelInterface, or null.

findFirstWithBy

Call native Phalcon FindFirstBy function then eager load relationships from the model

protected static findFirstWithBy(string $forwardMethod, array $arguments): ?\Phalcon\Mvc\ModelInterface

• This method is static. Parameters:

findWithBy

Call native Phalcon findBy function then eager load relationships from the resultset

protected static findWithBy(string $forwardMethod, array $arguments): ?array

• This method is static. Parameters:

load

Example:

public load(array $arguments): ?\Phalcon\Mvc\ModelInterface

$manufacturer = Manufacturer::findFirstById(51);

$manufacturer->load('Robots.Parts');

foreach ($manufacturer->robots as $robot) {
   foreach ($robot->parts as $part) { ... }
}

Parameters:

getParametersFromArguments

Get the query parameters from a list of arguments

public static getParametersFromArguments(array& $arguments): mixed

The final argument is treated as the native Phalcon finder parameters when at least two arguments were passed. Eager loading needs complete parent models so relation keys are available, therefore custom columns selections are expanded to include * before the parameters are passed to find() or findFirst(). Native Phalcon accepts both array and string column definitions, so both shapes are normalized without changing any other finder options.

• This method is static. Parameters:

subCount

Count rows through a subquery generated by the models manager.

public static subCount(mixed $find): int

The supplied find definition is converted to a query builder for the calling model class, compiled to SQL, and wrapped in SELECT COUNT(*) FROM (...). Bind parameters and bind types are reused from the generated query.

• This method is static. Parameters:

Return Value:

Total row count reported by the database.

Throws:

When the default DI, models manager, or database service cannot be resolved through the PhalconKit DI contract. - ServiceException

initializeCache

Initialize model cache invalidation for the current model.

public initializeCache(): void

The models service supplies framework model class mappings used for the default blacklist. After the blacklist is prepared, the trait adds the flush behavior unless this model instance or class is excluded.

Throws:

When the models service cannot be resolved through the PhalconKit DI contract. - ServiceException

addFlushCacheBehavior

Add an after-event behavior that clears the shared models cache.

public addFlushCacheBehavior(array<int,class-string|object|string>|null $flushModelsCacheBlackList = null): void

The behavior is skipped when preventFlushCache is true or the current model is an instance of one of the blacklisted classes. Cache clearing is attempted only when snapshots indicate that persisted data changed.

Parameters: