An entity represents a single result row from a repository. It exposes the methods for retrieving and storing properties associated in this row.
array<string, bool>
Map of fields in this entity that can be safely assigned, each field name points to a boolean indicating its status. An empty array means no fields are accessible
array<string, array<string, array<string, string>>>
Holds a cached list of getters/setters per class
array<bool>
Holds a list of the fields that were modified or added after this object was originally created.
array<string, mixed>
List of errors per field as stored in this object.
array<string, mixed>
Holds all fields and their values for this entity.
array<string>
List of field names that should not be included in JSON or Array representations of this Entity.
array<string, mixed>
List of invalid fields and their data for errors upon validation/patching.
bool
Indicates whether this entity is yet to be persisted. Entities default to assuming they are new. You can use Table::persisted() to set the new flag on an entity based on records in the database.
array<string, mixed>
Holds all fields that have been changed and their original values for this entity.
string
The alias of the repository this entity came from
array<string>
List of computed or virtual fields that should be included in JSON or array representations of this Entity. If a field is present in both _hidden and _virtual the field will not be in the array/JSON versions of the entity.
mixed
Alias for commonly used primary key.
Initializes the internal properties of this entity out of the keys in an array. The following list of options can be used:
Returns an array that can be used to describe the internal state of this object.
Magic getter to access fields that have been set in this entity
Returns whether this entity contains a field named $field and is not set to null.
Magic setter to add or edit a field in this entity
Returns a string representation of this object in a human readable format.
Removes a field from this entity
Fetch accessor method name Accessor methods (available or not) are cached in $_accessors
Auxiliary method for getting errors in nested entities
Read the error(s) from one or many objects.
Reads if there are errors for one or many objects.
Sets the entire entity as clean, which means that it will appear as no fields being modified or added at all. This is an useful call for an initial object hydration
Returns an array with the requested fields stored in this entity, indexed by field name
Returns an array with the requested original fields stored in this entity, indexed by field name.
Returns an array with only the original fields stored in this entity, indexed by field name.
Returns the value of a field by name
Returns the raw accessible configuration for this entity. The *
wildcard refers to all fields.
Gets the dirty fields.
Returns validation errors of a field
Returns all validation errors.
Gets the hidden fields.
Get a list of invalid fields and their data for errors upon validation/patching
Get a single value of an invalid field. Returns null if not set.
Returns the value of an original field by name
Gets all original values of the entity.
Returns the alias of the repository from which this entity came from.
Gets the virtual fields on this entity.
Gets the list of visible fields.
Returns whether this entity contains a field named $field that contains a non-null value.
Returns whether this entity has errors.
Checks that a field has a value.
Checks if a field is accessible
Checks if the entity is dirty or if a single field of it is dirty.
Checks that a field is empty
Returns whether this entity has already been persisted.
Returns the fields that will be serialized as JSON
Implements isset($entity);
Implements $entity[$offset];
Implements $entity[$offset] = $value;
Implements unset($result[$offset]);
Sets a single field inside this entity.
Stores whether a field value can be changed or set in this entity. The special field *
can also be marked as accessible or protected, meaning that any other field specified before will take its value. For example $entity->setAccess('*', true)
means that any field not specified already will be accessible by default.
Sets the dirty status of a single field.
Sets errors for a single field
Sets error messages to the entity
Sets hidden fields.
Set fields as invalid and not patchable into the entity.
Sets a field as invalid and not patchable into the entity.
Set the status of this entity.
Sets the source alias
Sets the virtual fields on this entity.
Returns an array with all the fields that have been set to this entity
Removes a field or list of fields from this entity
Removes a field or list of fields from this entity
__construct(array<string, mixed> $properties = [], array<string, mixed> $options = [])
Initializes the internal properties of this entity out of the keys in an array. The following list of options can be used:
$entity = new Entity(['id' => 1, 'name' => 'Andrew'])
array<string, mixed>
$properties optional hash of properties to set in this entity
array<string, mixed>
$options optional list of options to use when creating this entity
__debugInfo(): array<string, mixed>
Returns an array that can be used to describe the internal state of this object.
array<string, mixed>
__get(string $field): mixed
Magic getter to access fields that have been set in this entity
string
$field Name of the field to access
mixed
__isset(string $field): bool
Returns whether this entity contains a field named $field and is not set to null.
string
$field The field to check.
bool
__set(string $field, mixed $value): void
Magic setter to add or edit a field in this entity
string
$field The name of the field to set
mixed
$value The value to set to the field
void
__toString(): string
Returns a string representation of this object in a human readable format.
string
__unset(string $field): void
Removes a field from this entity
string
$field The field to unset
void
_accessor(string $property, string $type): string
Fetch accessor method name Accessor methods (available or not) are cached in $_accessors
string
$property the field name to derive getter name from
string
$type the accessor type ('get' or 'set')
string
_nestedErrors(string $field): array
Auxiliary method for getting errors in nested entities
string
$field the field in this entity to check for errors
array
_readError(Cake\Datasource\EntityInterface|iterable $object, string|null $path = null): array
Read the error(s) from one or many objects.
Cake\Datasource\EntityInterface|iterable
$object The object to read errors from.
string|null
$path optional The field name for errors.
array
_readHasErrors(Cake\Datasource\EntityInterface|array $object): bool
Reads if there are errors for one or many objects.
Cake\Datasource\EntityInterface|array
$object The object to read errors from.
bool
clean(): void
Sets the entire entity as clean, which means that it will appear as no fields being modified or added at all. This is an useful call for an initial object hydration
void
extract(array<string> $fields, bool $onlyDirty = false): array
Returns an array with the requested fields stored in this entity, indexed by field name
array<string>
$fields list of fields to be returned
bool
$onlyDirty optional Return the requested field only if it is dirty
array
extractOriginal(array<string> $fields): array
Returns an array with the requested original fields stored in this entity, indexed by field name.
Fields that are unchanged from their original value will be included in the return of this method.
array<string>
$fields List of fields to be returned
array
extractOriginalChanged(array<string> $fields): array
Returns an array with only the original fields stored in this entity, indexed by field name.
This method will only return fields that have been modified since the entity was built. Unchanged fields will be omitted.
array<string>
$fields List of fields to be returned
array
get(string $field): mixed
Returns the value of a field by name
string
$field the name of the field to retrieve
mixed
InvalidArgumentException
getAccessible(): array<bool>
Returns the raw accessible configuration for this entity. The *
wildcard refers to all fields.
array<bool>
getDirty(): array<string>
Gets the dirty fields.
array<string>
getError(string $field): array
Returns validation errors of a field
string
$field Field name to get the errors from
array
getErrors(): array
Returns all validation errors.
array
getHidden(): array<string>
Gets the hidden fields.
array<string>
getInvalid(): array<string, mixed>
Get a list of invalid fields and their data for errors upon validation/patching
array<string, mixed>
getInvalidField(string $field): mixed|null
Get a single value of an invalid field. Returns null if not set.
string
$field The name of the field.
mixed|null
getOriginal(string $field): mixed
Returns the value of an original field by name
string
$field the name of the field for which original value is retrieved.
mixed
InvalidArgumentException
getOriginalValues(): array
Gets all original values of the entity.
array
getSource(): string
Returns the alias of the repository from which this entity came from.
string
getVirtual(): array<string>
Gets the virtual fields on this entity.
array<string>
getVisible(): array<string>
Gets the list of visible fields.
The list of visible fields is all standard fields plus virtual fields minus hidden fields.
array<string>
has(array<string>|string $field): bool
Returns whether this entity contains a field named $field that contains a non-null value.
$entity = new Entity(['id' => 1, 'name' => null]); $entity->has('id'); // true $entity->has('name'); // false $entity->has('last_name'); // false
You can check multiple fields by passing an array:
$entity->has(['name', 'last_name']);
All fields must not be null to get a truthy result.
When checking multiple fields. All fields must not be null in order for true to be returned.
array<string>|string
$field The field or fields to check.
bool
hasErrors(bool $includeNested = true): bool
Returns whether this entity has errors.
bool
$includeNested optional true will check nested entities for hasErrors()
bool
hasValue(string $field): bool
Checks that a field has a value.
This method will return true for
0
and false in all other cases.
string
$field The field to check.
bool
isAccessible(string $field): bool
Checks if a field is accessible
$entity->isAccessible('id'); // Returns whether it can be set or not
string
$field Field name to check
bool
isDirty(string|null $field = null): bool
Checks if the entity is dirty or if a single field of it is dirty.
string|null
$field optional The field to check the status for. Null for the whole entity.
bool
isEmpty(string $field): bool
Checks that a field is empty
This is not working like the PHP empty()
function. The method will return true for:
''
(empty string)null
[]
and false in all other cases.
string
$field The field to check.
bool
isNew(): bool
Returns whether this entity has already been persisted.
bool
jsonSerialize(): array
Returns the fields that will be serialized as JSON
array
offsetExists(string $offset): bool
Implements isset($entity);
string
$offset The offset to check.
bool
offsetGet(string $offset): mixed
Implements $entity[$offset];
string
$offset The offset to get.
mixed
offsetSet(string $offset, mixed $value): void
Implements $entity[$offset] = $value;
string
$offset The offset to set.
mixed
$value The value to set.
void
offsetUnset(string $offset): void
Implements unset($result[$offset]);
string
$offset The offset to remove.
void
set(array<string, mixed>|string $field, mixed $value = null, array<string, mixed> $options = []): $this
Sets a single field inside this entity.
$entity->set('name', 'Andrew');
It is also possible to mass-assign multiple fields to this entity with one call by passing a hashed array as fields in the form of field => value pairs
$entity->set(['name' => 'andrew', 'id' => 1]); echo $entity->name // prints andrew echo $entity->id // prints 1
Some times it is handy to bypass setter functions in this entity when assigning fields. You can achieve this by disabling the setter
option using the $options
parameter:
$entity->set('name', 'Andrew', ['setter' => false]); $entity->set(['name' => 'Andrew', 'id' => 1], ['setter' => false]);
Mass assignment should be treated carefully when accepting user input, by default entities will guard all fields when fields are assigned in bulk. You can disable the guarding for a single set call with the guard
option:
$entity->set(['name' => 'Andrew', 'id' => 1], ['guard' => false]);
You do not need to use the guard option when assigning fields individually:
// No need to use the guard option. $entity->set('name', 'Andrew');
array<string, mixed>|string
$field the name of field to set or a list of fields with their respective values
mixed
$value optional The value to set to the field or an array if the first argument is also an array, in which case will be treated as $options
array<string, mixed>
$options optional Options to be used for setting the field. Allowed option keys are setter
and guard
$this
InvalidArgumentException
setAccess(array<string>|string $field, bool $set): $this
Stores whether a field value can be changed or set in this entity. The special field *
can also be marked as accessible or protected, meaning that any other field specified before will take its value. For example $entity->setAccess('*', true)
means that any field not specified already will be accessible by default.
You can also call this method with an array of fields, in which case they will each take the accessibility value specified in the second argument.
$entity->setAccess('id', true); // Mark id as not protected $entity->setAccess('author_id', false); // Mark author_id as protected $entity->setAccess(['id', 'user_id'], true); // Mark both fields as accessible $entity->setAccess('*', false); // Mark all fields as protected
array<string>|string
$field Single or list of fields to change its accessibility
bool
$set True marks the field as accessible, false will mark it as protected.
$this
setDirty(string $field, bool $isDirty = true): $this
Sets the dirty status of a single field.
string
$field the field to set or check status for
bool
$isDirty optional true means the field was changed, false means it was not changed. Defaults to true.
$this
setError(string $field, array|string $errors, bool $overwrite = false): $this
Sets errors for a single field
// Sets the error messages for a single field $entity->setError('salary', ['must be numeric', 'must be a positive number']);
string
$field The field to get errors for, or the array of errors to set.
array|string
$errors The errors to be set for $field
bool
$overwrite optional Whether to overwrite pre-existing errors for $field
$this
setErrors(array $errors, bool $overwrite = false): $this
Sets error messages to the entity
// Sets the error messages for multiple fields at once $entity->setErrors(['salary' => ['message'], 'name' => ['another message']]);
array
$errors The array of errors to set.
bool
$overwrite optional Whether to overwrite pre-existing errors for $fields
$this
setHidden(array<string> $fields, bool $merge = false): $this
Sets hidden fields.
array<string>
$fields An array of fields to hide from array exports.
bool
$merge optional Merge the new fields with the existing. By default false.
$this
setInvalid(array<string, mixed> $fields, bool $overwrite = false): $this
Set fields as invalid and not patchable into the entity.
This is useful for batch operations when one needs to get the original value for an error message after patching. This value could not be patched into the entity and is simply copied into the _invalid property for debugging purposes or to be able to log it away.
array<string, mixed>
$fields The values to set.
bool
$overwrite optional Whether to overwrite pre-existing values for $field.
$this
setInvalidField(string $field, mixed $value): $this
Sets a field as invalid and not patchable into the entity.
string
$field The value to set.
mixed
$value The invalid value to be set for $field.
$this
setNew(bool $new): $this
Set the status of this entity.
Using true
means that the entity has not been persisted in the database, false
that it already is.
bool
$new Indicate whether this entity has been persisted.
$this
setSource(string $alias): $this
Sets the source alias
string
$alias the alias of the repository
$this
setVirtual(array<string> $fields, bool $merge = false): $this
Sets the virtual fields on this entity.
array<string>
$fields An array of fields to treat as virtual.
bool
$merge optional Merge the new fields with the existing. By default false.
$this
toArray(): array
Returns an array with all the fields that have been set to this entity
This method will recursively transform entities assigned to fields into arrays as well.
array
unset(array<string>|string $field): $this
Removes a field or list of fields from this entity
$entity->unset('name'); $entity->unset(['name', 'last_name']);
array<string>|string
$field The field to unset.
$this
unsetProperty(array<string>|string $field): $this
Removes a field or list of fields from this entity
array<string>|string
$field The field to unset.
$this
Map of fields in this entity that can be safely assigned, each field name points to a boolean indicating its status. An empty array means no fields are accessible
The special field '*' can also be mapped, meaning that any other field not defined in the map will take its value. For example, '*' => true
means that any field not defined in the map will be accessible by default
array<string, bool>
Holds a cached list of getters/setters per class
array<string, array<string, array<string, string>>>
Holds a list of the fields that were modified or added after this object was originally created.
array<bool>
List of errors per field as stored in this object.
array<string, mixed>
Holds all fields and their values for this entity.
array<string, mixed>
List of field names that should not be included in JSON or Array representations of this Entity.
array<string>
List of invalid fields and their data for errors upon validation/patching.
array<string, mixed>
Indicates whether this entity is yet to be persisted. Entities default to assuming they are new. You can use Table::persisted() to set the new flag on an entity based on records in the database.
bool
Holds all fields that have been changed and their original values for this entity.
array<string, mixed>
The alias of the repository this entity came from
string
List of computed or virtual fields that should be included in JSON or array representations of this Entity. If a field is present in both _hidden and _virtual the field will not be in the array/JSON versions of the entity.
array<string>
Alias for commonly used primary key.
mixed
© 2005–present The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/4.4/class-Cake.ORM.Entity.html