An entity represents a single result row from a repository. It exposes the methods for retrieving and storing properties associated in this row.
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
Holds a cached list of getters/setters per class
bool[]
Holds a list of the fields that were modified or added after this object was originally created.
array
List of errors per field as stored in this object.
array
Holds all fields and their values for this entity.
string[]
List of field names that should not be included in JSON or Array representations of this Entity.
array
List of invalid fields and their data for errors upon validation/patching.
bool
Indicates whether or not this entity is yet to be persisted.
array
Holds all fields that have been changed and their original values for this entity.
string
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.
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.
Returns whether this entity contains a field named $field regardless of if it is empty.
Fetch accessor method name Accessor methods (available or not) are cached in $_accessors
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 whether this entity contains a field named $field that contains a non-null value.
__construct(array $properties, array $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
$properties optional hash of properties to set in this entity
array
$options optional list of options to use when creating this entity
__debugInfo()
Returns an array that can be used to describe the internal state of this object.
array
__get(string $field)
Magic getter to access fields that have been set in this entity
string
$field Name of the field to access
mixed
__isset(string $field)
Returns whether this entity contains a field named $field regardless of if it is empty.
string
$field The field to check.
bool
__set(string $field, mixed $value)
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
__toString()
Returns a string representation of this object in a human readable format.
string
__unset(string $field)
Removes a field from this entity
string
$field The field to unset
_accessor(string $property, string $type)
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
method name or empty string (no method available)
_nestedErrors(string $field)
Auxiliary method for getting errors in nested entities
string
$field the field in this entity to check for errors
array
errors in nested entity if any
_readError(mixed $object, mixed $path)
Read the error(s) from one or many objects.
iterable|\Cake\Datasource\EntityInterface
$object The object to read errors from.
string|null
$path optional The field name for errors.
array
_readHasErrors(mixed $object)
Reads if there are errors for one or many objects.
array|\Cake\Datasource\EntityInterface
$object The object to read errors from.
bool
clean()
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
extract(array $fields, bool $onlyDirty)
Returns an array with the requested fields stored in this entity, indexed by field name
string[]
$fields list of fields to be returned
bool
$onlyDirty optional Return the requested field only if it is dirty
array
extractOriginal(array $fields)
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.
string[]
$fields List of fields to be returned
array
extractOriginalChanged(array $fields)
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.
string[]
$fields List of fields to be returned
array
get(string $field)
Returns the value of a field by name
string
$field the name of the field to retrieve
mixed
InvalidArgumentException
getAccessible()
Returns the raw accessible configuration for this entity.
The *
wildcard refers to all fields.
bool[]
getDirty()
Gets the dirty fields.
string[]
getError(string $field)
Returns validation errors of a field
string
$field Field name to get the errors from
array
getErrors()
Returns all validation errors.
array
getHidden()
Gets the hidden fields.
string[]
getInvalid()
Get a list of invalid fields and their data for errors upon validation/patching
array
getInvalidField(string $field)
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)
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()
Gets all original values of the entity.
array
getSource()
Returns the alias of the repository from which this entity came from.
string
getVirtual()
Gets the virtual fields on this entity.
string[]
getVisible()
Gets the list of visible fields.
The list of visible fields is all standard fields plus virtual fields minus hidden fields.
string[]
A list of fields that are 'visible' in all representations.
has(mixed $field)
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.
string|string[]
$field The field or fields to check.
bool
hasErrors(bool $includeNested)
Returns whether this entity has errors.
bool
$includeNested optional true will check nested entities for hasErrors()
bool
hasValue(string $field)
Checks tha 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)
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 $field)
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
Whether the field was changed or not
isEmpty(string $field)
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()
Returns whether or not this entity has already been persisted.
bool
Whether or not the entity has been persisted.
jsonSerialize()
Returns the fields that will be serialized as JSON
array
offsetExists(mixed $offset)
Implements isset($entity);
string
$offset The offset to check.
bool
Success
offsetGet(mixed $offset)
Implements $entity[$offset];
string
$offset The offset to get.
mixed
offsetSet(mixed $offset, mixed $value)
Implements $entity[$offset] = $value;
string
$offset The offset to set.
mixed
$value The value to set.
offsetUnset(mixed $offset)
Implements unset($result[$offset]);
string
$offset The offset to remove.
set(mixed $field, mixed $value, array $options)
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');
string|array
$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
$options optional options to be used for setting the field. Allowed option keys are setter
and guard
$this
InvalidArgumentException
setAccess(mixed $field, bool $set)
Stores whether or not 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
string|array
$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)
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, mixed $errors, bool $overwrite)
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.
string|array
$errors The errors to be set for $field
bool
$overwrite optional Whether or not to overwrite pre-existing errors for $field
$this
setErrors(array $errors, bool $overwrite)
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 or not to overwrite pre-existing errors for $fields
$this
setHidden(array $fields, bool $merge)
Sets hidden fields.
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 $fields, bool $overwrite)
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
$fields The values to set.
bool
$overwrite optional Whether or not to overwrite pre-existing values for $field.
$this
setInvalidField(string $field, mixed $value)
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)
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 or not this entity has been persisted.
$this
setSource(string $alias)
Sets the source alias
string
$alias the alias of the repository
$this
setVirtual(array $fields, bool $merge)
Sets the virtual fields on this entity.
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()
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(mixed $field)
Removes a field or list of fields from this entity
$entity->unset('name'); $entity->unset(['name', 'last_name']);
string|string[]
$field The field to unset.
$this
unsetProperty(mixed $field)
Removes a field or list of fields from this entity
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
bool[]
Holds a cached list of getters/setters per class
array
Holds a list of the fields that were modified or added after this object was originally created.
bool[]
List of errors per field as stored in this object.
array
Holds all fields and their values for this entity.
array
List of field names that should not be included in JSON or Array representations of this Entity.
string[]
List of invalid fields and their data for errors upon validation/patching.
array
Indicates whether or not 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
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.
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.1/class-Cake.ORM.Entity.html