Class Entity
An entity represents a single result row from a repository. It exposes the methods for retrieving and storing properties associated in this row.
Property Summary
-
$_accessible protected
array
Map of properties in this entity that can be safely assigned, each property name points to a boolean indicating its status. An empty array means no properties are accessible
-
$_accessors protected static
array
Holds a cached list of getters/setters per class
-
$_className protected deprecated
string
Holds the name of the class for the instance object
-
$_dirty protected
array
Holds a list of the properties that were modified or added after this object was originally created.
-
$_errors protected
array
List of errors per field as stored in this object
-
$_hidden protected
array
List of property names that should not be included in JSON or Array representations of this Entity.
-
$_invalid protected
array
List of invalid fields and their data for errors upon validation/patching
-
$_new protected
bool
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.
-
$_original protected
array
Holds all properties that have been changed and their original values for this entity
-
$_properties protected
array
Holds all properties and their values for this entity
-
$_registryAlias protected
string
The alias of the repository this entity came from
-
$_virtual protected
array
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.
-
$id public @property
mixed
Alias for commonly used primary key.
Method Summary
-
__construct() public
Initializes the internal properties of this entity out of the keys in an array. The following list of options can be used:
-
__debugInfo() public
Returns an array that can be used to describe the internal state of this object.
-
__get() public
Magic getter to access properties that have been set in this entity
-
__isset() public
Returns whether this entity contains a property named $property regardless of if it is empty.
-
__set() public
Magic setter to add or edit a property in this entity
-
__toString() public
Returns a string representation of this object in a human readable format.
-
__unset() public
Removes a property from this entity
-
_accessor() protected static
Fetch accessor method name Accessor methods (available or not) are cached in $_accessors
-
_nestedErrors() protected
Auxiliary method for getting errors in nested entities
-
_readError() protected
Read the error(s) from one or many objects.
-
accessible() public deprecated
Stores whether or not a property value can be changed or set in this entity. The special property
*
can also be marked as accessible or protected, meaning that any other property specified before will take its value. For example$entity->accessible('*', true)
means that any property not specified already will be accessible by default. -
clean() public
Sets the entire entity as clean, which means that it will appear as no properties being modified or added at all. This is an useful call for an initial object hydration
-
dirty() public deprecated
Sets the dirty status of a single property. If called with no second argument, it will return whether the property was modified or not after the object creation.
-
errors() public deprecated
Sets the error messages for a field or a list of fields. When called without the second argument it returns the validation errors for the specified fields. If called with no arguments it returns all the validation error messages stored in this entity and any other nested entity.
-
extract() public
Returns an array with the requested properties stored in this entity, indexed by property name
-
extractOriginal() public
Returns an array with the requested original properties stored in this entity, indexed by property name.
-
extractOriginalChanged() public
Returns an array with only the original properties stored in this entity, indexed by property name.
-
get() public
Returns the value of a property by name
-
getDirty() public
Gets the dirty properties.
-
getError() public
Returns validation errors of a field
-
getErrors() public
Returns all validation errors.
-
getHidden() public
Gets the hidden properties.
-
getOriginal() public
Returns the value of an original property by name
-
getOriginalValues() public
Gets all original values of the entity.
-
getSource() public
Returns the alias of the repository from which this entity came from.
-
getVirtual() public
Gets the virtual properties on this entity.
-
has() public
Returns whether this entity contains a property named $property that contains a non-null value.
-
hiddenProperties() public deprecated
Get/Set the hidden properties on this entity.
-
invalid() public
Sets a field as invalid and not patchable into the entity.
-
isAccessible() public
Checks if a property is accessible
-
isDirty() public
Checks if the entity is dirty or if a single property of it is dirty.
-
isNew() public
Returns whether or not this entity has already been persisted. This method can return null in the case there is no prior information on the status of this entity.
-
jsonSerialize() public
Returns the properties that will be serialized as JSON
-
offsetExists() public
Implements isset($entity);
-
offsetGet() public
Implements $entity[$offset];
-
offsetSet() public
Implements $entity[$offset] = $value;
-
offsetUnset() public
Implements unset($result[$offset]);
-
set() public
Sets a single property inside this entity.
-
setAccess() public
Stores whether or not a property value can be changed or set in this entity. The special property
*
can also be marked as accessible or protected, meaning that any other property specified before will take its value. For example$entity->setAccess('*', true)
means that any property not specified already will be accessible by default. -
setDirty() public
Sets the dirty status of a single property.
-
setError() public
Sets errors for a single field
-
setErrors() public
Sets error messages to the entity
-
setHidden() public
Sets hidden properties.
-
setSource() public
Sets the source alias
-
setVirtual() public
Sets the virtual properties on this entity.
-
source() public deprecated
Returns the alias of the repository from which this entity came from.
-
toArray() public
Returns an array with all the properties that have been set to this entity
-
unsetProperty() public
Removes a property or list of properties from this entity
-
virtualProperties() public deprecated
Get/Set the virtual properties on this entity.
-
visibleProperties() public
Get the list of visible properties.
Method Detail
__construct() ¶ public
__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:
- useSetters: whether use internal setters for properties or not
- markClean: whether to mark all properties as clean after setting them
- markNew: whether this instance has not yet been persisted
- guard: whether to prevent inaccessible properties from being set (default: false)
- source: A string representing the alias of the repository this entity came from
Example:
$entity = new Entity(['id' => 1, 'name' => 'Andrew'])
Parameters
-
array
$properties optional hash of properties to set in this entity
-
array
$options optional list of options to use when creating this entity
__debugInfo() ¶ public
__debugInfo(): array
Returns an array that can be used to describe the internal state of this object.
Returns
array
__get() ¶ public
__get(string $property): mixed
Magic getter to access properties that have been set in this entity
Parameters
-
string
$property Name of the property to access
Returns
mixed
__isset() ¶ public
__isset(string $property): bool
Returns whether this entity contains a property named $property regardless of if it is empty.
Parameters
-
string
$property The property to check.
Returns
bool
See Also
__set() ¶ public
__set(string $property, mixed $value): void
Magic setter to add or edit a property in this entity
Parameters
-
string
$property The name of the property to set
-
mixed
$value The value to set to the property
Returns
void
__toString() ¶ public
__toString(): string
Returns a string representation of this object in a human readable format.
Returns
string
__unset() ¶ public
__unset(string $property): void
Removes a property from this entity
Parameters
-
string
$property The property to unset
Returns
void
_accessor() ¶ protected static
_accessor(string $property, string $type): string
Fetch accessor method name Accessor methods (available or not) are cached in $_accessors
Parameters
-
string
$property the field name to derive getter name from
-
string
$type the accessor type ('get' or 'set')
Returns
string
_nestedErrors() ¶ protected
_nestedErrors(string $field): array
Auxiliary method for getting errors in nested entities
Parameters
-
string
$field the field in this entity to check for errors
Returns
array
_readError() ¶ protected
_readError(array|Cake\Datasource\EntityTrait $object, string|null $path = null): array
Read the error(s) from one or many objects.
Parameters
-
array|Cake\Datasource\EntityTrait
$object The object to read errors from.
-
string|null
$path optional The field name for errors.
Returns
array
accessible() ¶ public
accessible(string|array $property, bool|null $set = null): $this|bool
Stores whether or not a property value can be changed or set in this entity.
The special property *
can also be marked as accessible or protected, meaning
that any other property specified before will take its value. For example
$entity->accessible('*', true)
means that any property not specified already
will be accessible by default.
You can also call this method with an array of properties, in which case they will each take the accessibility value specified in the second argument.
Example:
$entity->accessible('id', true); // Mark id as not protected
$entity->accessible('author_id', false); // Mark author_id as protected
$entity->accessible(['id', 'user_id'], true); // Mark both properties as accessible
$entity->accessible('*', false); // Mark all properties as protected
When called without the second param it will return whether or not the property can be set.
Example:
$entity->accessible('id'); // Returns whether it can be set or not
Parameters
-
string|array
$property single or list of properties to change its accessibility
-
bool|null
$set optional true marks the property as accessible, false will mark it as protected.
Returns
$this|bool
clean() ¶ public
clean(): void
Sets the entire entity as clean, which means that it will appear as no properties being modified or added at all. This is an useful call for an initial object hydration
Returns
void
dirty() ¶ public
dirty(string|null $property = null, null|bool $isDirty = null): bool
Sets the dirty status of a single property. If called with no second argument, it will return whether the property was modified or not after the object creation.
When called with no arguments it will return whether or not there are any dirty property in the entity
Parameters
-
string|null
$property optional the field to set or check status for
-
null|bool
$isDirty optional true means the property was changed, false means it was not changed and null will make the function return current state for that property
Returns
bool
errors() ¶ public
errors(string|array|null $field = null, string|array|null $errors = null, bool $overwrite = false): array|$this
Sets the error messages for a field or a list of fields. When called without the second argument it returns the validation errors for the specified fields. If called with no arguments it returns all the validation error messages stored in this entity and any other nested entity.
Example
// Sets the error messages for a single field
$entity->errors('salary', ['must be numeric', 'must be a positive number']);
// Returns the error messages for a single field
$entity->errors('salary');
// Returns all error messages indexed by field name
$entity->errors();
// Sets the error messages for multiple fields at once
$entity->errors(['salary' => ['message'], 'name' => ['another message']);
When used as a setter, this method will return this entity instance for method chaining.
Parameters
-
string|array|null
$field optional The field to get errors for, or the array of errors to set.
-
string|array|null
$errors optional The errors to be set for $field
-
bool
$overwrite optional Whether or not to overwrite pre-existing errors for $field
Returns
array|$this
extract() ¶ public
extract(array $properties, bool $onlyDirty = false): array
Returns an array with the requested properties stored in this entity, indexed by property name
Parameters
-
array
$properties list of properties to be returned
-
bool
$onlyDirty optional Return the requested property only if it is dirty
Returns
array
extractOriginal() ¶ public
extractOriginal(array $properties): array
Returns an array with the requested original properties stored in this entity, indexed by property name.
Properties that are unchanged from their original value will be included in the return of this method.
Parameters
-
array
$properties List of properties to be returned
Returns
array
extractOriginalChanged() ¶ public
extractOriginalChanged(array $properties): array
Returns an array with only the original properties stored in this entity, indexed by property name.
This method will only return properties that have been modified since the entity was built. Unchanged properties will be omitted.
Parameters
-
array
$properties List of properties to be returned
Returns
array
get() ¶ public
get(string $property): mixed
Returns the value of a property by name
Parameters
-
string
$property the name of the property to retrieve
Returns
mixed
Throws
InvalidArgumentException
if an empty property name is passed
getError() ¶ public
getError(mixed $field): array
Returns validation errors of a field
Parameters
-
$field
Field name to get the errors from
Returns
array
getOriginal() ¶ public
getOriginal(string $property): mixed
Returns the value of an original property by name
Parameters
-
string
$property the name of the property for which original value is retrieved.
Returns
mixed
Throws
InvalidArgumentException
if an empty property name is passed.
getOriginalValues() ¶ public
getOriginalValues(): array
Gets all original values of the entity.
Returns
array
getSource() ¶ public
getSource(): string
Returns the alias of the repository from which this entity came from.
Returns
string
has() ¶ public
has(string $property): bool
Returns whether this entity contains a property named $property that contains a non-null value.
Example:
$entity = new Entity(['id' => 1, 'name' => null]);
$entity->has('id'); // true
$entity->has('name'); // false
$entity->has('last_name'); // false
You can check multiple properties by passing an array:
$entity->has(['name', 'last_name']);
All properties must not be null to get a truthy result.
When checking multiple properties. All properties must not be null in order for true to be returned.
Parameters
-
string
$property The property or properties to check.
Returns
bool
hiddenProperties() ¶ public
hiddenProperties(null|array $properties = null): array|$this
Get/Set the hidden properties on this entity.
If the properties argument is null, the currently hidden properties will be returned. Otherwise the hidden properties will be set.
Parameters
-
null|array
$properties optional Either an array of properties to hide or null to get properties
Returns
array|$this
invalid() ¶ public
invalid(string|array|null $field = null, mixed|null $value = null, bool $overwrite = false): $this|mixed
Sets a field 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.
Parameters
-
string|array|null
$field optional The field to get invalid value for, or the value to set.
-
mixed|null
$value optional The invalid value to be set for $field.
-
bool
$overwrite optional Whether or not to overwrite pre-existing values for $field.
Returns
$this|mixed
isAccessible() ¶ public
isAccessible(mixed $property): bool
Checks if a property is accessible
Example:
$entity->isAccessible('id'); // Returns whether it can be set or not
Parameters
-
$property
Property name to check
Returns
bool
isDirty() ¶ public
isDirty(mixed $property = null): bool
Checks if the entity is dirty or if a single property of it is dirty.
Parameters
-
$property optional
the field to check the status for
Returns
bool
isNew() ¶ public
isNew(bool|null $new = null): bool
Returns whether or not this entity has already been persisted. This method can return null in the case there is no prior information on the status of this entity.
If called with a boolean it will set the known status of this instance, true means that the instance is not yet persisted in the database, false that it already is.
Parameters
-
bool|null
$new optional true if it is known this instance was not yet persisted
Returns
bool
jsonSerialize() ¶ public
jsonSerialize(): array
Returns the properties that will be serialized as JSON
Returns
array
offsetExists() ¶ public
offsetExists(mixed $offset): bool
Implements isset($entity);
Parameters
-
mixed
$offset The offset to check.
Returns
bool
offsetGet() ¶ public
offsetGet(mixed $offset): mixed
Implements $entity[$offset];
Parameters
-
mixed
$offset The offset to get.
Returns
mixed
offsetSet() ¶ public
offsetSet(mixed $offset, mixed $value): void
Implements $entity[$offset] = $value;
Parameters
-
mixed
$offset The offset to set.
-
mixed
$value The value to set.
Returns
void
offsetUnset() ¶ public
offsetUnset(mixed $offset): void
Implements unset($result[$offset]);
Parameters
-
mixed
$offset The offset to remove.
Returns
void
set() ¶ public
set(string|array $property, mixed $value = null, array $options = []): $this
Sets a single property inside this entity.
Example:
$entity->set('name', 'Andrew');
It is also possible to mass-assign multiple properties to this entity with one call by passing a hashed array as properties in the form of property => value pairs
Example:
$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
properties. 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 properties 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' => true]);
You do not need to use the guard option when assigning properties individually:
// No need to use the guard option.
$entity->set('name', 'Andrew');
Parameters
-
string|array
$property the name of property to set or a list of properties with their respective values
-
mixed
$value optional The value to set to the property 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 property. Allowed option keys are
setter
andguard
Returns
$this
Throws
InvalidArgumentException
setAccess() ¶ public
setAccess(string|array $property, bool $set): $this
Stores whether or not a property value can be changed or set in this entity.
The special property *
can also be marked as accessible or protected, meaning
that any other property specified before will take its value. For example
$entity->setAccess('*', true)
means that any property not specified already
will be accessible by default.
You can also call this method with an array of properties, in which case they will each take the accessibility value specified in the second argument.
Example:
$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 properties as accessible
$entity->setAccess('*', false); // Mark all properties as protected
Parameters
-
string|array
$property single or list of properties to change its accessibility
-
bool
$set true marks the property as accessible, false will mark it as protected.
Returns
$this
setDirty() ¶ public
setDirty(mixed $property, mixed $isDirty): $this
Sets the dirty status of a single property.
Parameters
-
$property
the field to set or check status for
-
$isDirty
true means the property was changed, false means it was not changed
Returns
$this
setError() ¶ public
setError(mixed $field, mixed $errors, mixed $overwrite = false): $this
Sets errors for a single field
Example
// Sets the error messages for a single field
$entity->errors('salary', ['must be numeric', 'must be a positive number']);
Parameters
-
$field
The field to get errors for, or the array of errors to set.
-
$errors
The errors to be set for $field
-
$overwrite optional
Whether or not to overwrite pre-existing errors for $field
Returns
$this
setErrors() ¶ public
setErrors(array $fields, mixed $overwrite = false): $this
Sets error messages to the entity
Example
// Sets the error messages for multiple fields at once
$entity->errors(['salary' => ['message'], 'name' => ['another message']);
Parameters
-
array
$fields The array of errors to set.
-
$overwrite optional
Whether or not to overwrite pre-existing errors for $fields
Returns
$this
setHidden() ¶ public
setHidden(array $properties, mixed $merge = false): $this
Sets hidden properties.
Parameters
-
array
$properties An array of properties to hide from array exports.
-
$merge optional
Merge the new properties with the existing. By default false.
Returns
$this
setSource() ¶ public
setSource(string $alias): $this
Sets the source alias
Parameters
-
string
$alias the alias of the repository
Returns
$this
setVirtual() ¶ public
setVirtual(array $properties, mixed $merge = false): $this
Sets the virtual properties on this entity.
Parameters
-
array
$properties An array of properties to treat as virtual.
-
$merge optional
Merge the new properties with the existing. By default false.
Returns
$this
source() ¶ public
source(string|null $alias = null): string|$this
Returns the alias of the repository from which this entity came from.
If called with no arguments, it returns the alias of the repository this entity came from if it is known.
Parameters
-
string|null
$alias optional the alias of the repository
Returns
string|$this
toArray() ¶ public
toArray(): array
Returns an array with all the properties that have been set to this entity
This method will recursively transform entities assigned to properties into arrays as well.
Returns
array
unsetProperty() ¶ public
unsetProperty(string|array $property): $this
Removes a property or list of properties from this entity
Examples:
$entity->unsetProperty('name');
$entity->unsetProperty(['name', 'last_name']);
Parameters
-
string|array
$property The property to unset.
Returns
$this
virtualProperties() ¶ public
virtualProperties(null|array $properties = null): array|$this
Get/Set the virtual properties on this entity.
If the properties argument is null, the currently virtual properties will be returned. Otherwise the virtual properties will be set.
Parameters
-
null|array
$properties optional Either an array of properties to treat as virtual or null to get properties
Returns
array|$this
visibleProperties() ¶ public
visibleProperties(): array
Get the list of visible properties.
The list of visible properties is all standard properties plus virtual properties minus hidden properties.
Returns
array
Property Detail
$_accessible ¶ protected
Map of properties in this entity that can be safely assigned, each property name points to a boolean indicating its status. An empty array means no properties are accessible
The special property '*' can also be mapped, meaning that any other property
not defined in the map will take its value. For example, '\*' => true
means that any property not defined in the map will be accessible by default
Type
array
$_dirty ¶ protected
Holds a list of the properties that were modified or added after this object was originally created.
Type
array
$_hidden ¶ protected
List of property names that should not be included in JSON or Array representations of this Entity.
Type
array
$_invalid ¶ protected
List of invalid fields and their data for errors upon validation/patching
Type
array
$_new ¶ protected
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.
Type
bool
$_original ¶ protected
Holds all properties that have been changed and their original values for this entity
Type
array
$_virtual ¶ protected
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.
Type
array