PHP Class lithium\data\Entity

The Entity class can also be used as a base class for your own custom data objects, and is the basis for generating forms with the Form helper.

Protected Properties

Property	Type	Description
$_autoConfig	array	Auto configuration.
$_data	array	Associative array of the entity's fields and values.
$_errors	array	The list of validation errors associated with this object, where keys are field names, and values are arrays containing one or more validation error messages.
$_exists	boolean	A flag indicating whether or not this entity exists. Set to false if this is a newly-created entity, or if this entity has been loaded and subsequently deleted. Set to true if the entity has been loaded from the database, or has been created and subsequently saved.
$_handlers	array	Hold the "data export" handlers where the keys are fully-namespaced class names, and the values are closures that take an instance of the class as a parameter, and return an array or scalar value that the instance represents.
$_increment	array	An array of key/value pairs corresponding to fields that should be updated using atomic incrementing / decrementing operations. Keys match field names, and values indicate the value each field should be incremented or decremented by.
$_model	string	Fully-namespaced class name of model that this record is bound to. Instance methods declared in the model may be called on the entity. See the Model class documentation for more information.
$_parent	object	If this record is chained off of another, contains the origin object.
$_relationships	array	An array containing all related records and recordsets, keyed by relationship name, as defined in the bound model class.
$_schema	array	to create a form.
$_updated	array	Contains the values of updated fields. These values will be persisted to the backend data store when the document is saved.

Public Methods

Method	Description
__call ( string $method, array $params ) : mixed	Magic method that allows calling of model methods on this record instance, i.e.: $record->validates();
__construct ( array $config = [] ) : void	Constructor.
__get ( string $name ) : mixed	Overloading for reading inaccessible properties.
__isset ( string $name ) : mixed	Overloading for calling isset() or empty() on inaccessible properties.
__set ( string $name, mixed $value ) : void	PHP magic method used when setting properties on the Entity instance, i.e.
__toString ( ) : string	Returns a string representation of the Entity instance, based on the result of the 'title' meta value of the bound model class.
assignTo ( object $parent, array $config = [] )	Configures protected properties of an Entity so that it is parented to $parent.
data ( string $name = null ) : mixed	Access the data fields of the record. Can also access a $named field.
decrement ( string $field, string $value = 1 ) : integer	Decrements a field by the specified value. Works identically to increment(), but in reverse.
errors ( array \| string $field = null, string $value = null ) : mixed	Access the errors of the record.
exists ( ) : boolean	A flag indicating whether or not this record exists.
export ( array $options = [] )
increment ( string $field, integer \| string $value = 1 ) : integer	Safely (atomically) increments the value of the specified field by an arbitrary value.
model ( ) : string	Returns the model which this entity is bound to.
modified ( $field = null ) : mixed	Gets the current state for a given field or, if no field is given, gets the array of fields modified on this entity.
parent ( ) : object	Returns the parent object of this object, if any.
respondsTo ( string $method, boolean $internal = false ) : boolean	Determines if a given method can be called.
schema ( $field = null )
serialize ( ) : string	Prepares, enables and executes serialization of the object.
set ( array $data ) : void	Allows several properties to be assigned at once, i.e.: $record->set(array('title' => 'Lorem Ipsum', 'value' => 42));
sync ( mixed $id = null, array $data = [], array $options = [] )	Called after an Entity is saved. Updates the object's internal state to reflect the corresponding database entity, and sets the Entity object's key, if this is a newly-created object. Do not call this method if you intend to update the database's copy of the entity. Instead, see Model::save().
to ( string $format, array $options = [] ) : mixed	Converts the data in the record set to a different format, i.e. an array.
unserialize ( string $data ) : void	Prepares, enables and executes unserialization of the object.

Protected Methods

Method	Description
_init ( )

Method Details

__call() public method

Magic method that allows calling of model methods on this record instance, i.e.: $record->validates();

public __call ( string $method, array $params ) : mixed
$method	string	Method name caught by `__call()`.
$params	array	Arguments given to the above `$method` call.
return	mixed

__construct() public method

Constructor.

public __construct ( array $config = [] ) : void
$config	array	Available configuration options are: - `'data'` _array_: Data to enter into the record. Defaults to an empty array. - `'model'` _string_: Class name that provides the data-source for this record. Defaults to `null`.
return	void

__get() public method

Overloading for reading inaccessible properties.

public __get ( string $name ) : mixed
$name	string	Property name.
return	mixed	Result.

__isset() public method

Overloading for calling isset() or empty() on inaccessible properties.

public __isset ( string $name ) : mixed
$name	string	Property name.
return	mixed	Result.

__set() public method

$entity->title = 'Lorem Ipsum'.

public __set ( string $name, mixed $value ) : void
$name	string	The name of the field/property to write to, i.e. `title` in the above example.
$value	mixed	The value to write, i.e. `'Lorem Ipsum'`.
return	void

__toString() public method

Returns a string representation of the Entity instance, based on the result of the 'title' meta value of the bound model class.

public __toString ( ) : string
return	string	Returns the generated title of the object.

_init() protected method

protected _init ( )

assignTo() public method

Configures protected properties of an Entity so that it is parented to $parent.

public assignTo ( object $parent, array $config = [] )
$parent	object
$config	array

data() public method

Access the data fields of the record. Can also access a $named field.

public data ( string $name = null ) : mixed
$name	string	Optionally included field name.
return	mixed	Entire data array if $name is empty, otherwise the value from the named field.

decrement() public method

Decrements a field by the specified value. Works identically to increment(), but in reverse.

See also: lithium\data\Entity::increment()

public decrement ( string $field, string $value = 1 ) : integer
$field	string	The name of the field to decrement.
$value	string	The value by which to decrement the field. Defaults to `1`.
return	integer	Returns the new value of `$field`, after modification.

errors() public method

Access the errors of the record.

exists() public method

A flag indicating whether or not this record exists.

public exists ( ) : boolean
return	boolean	`True` if the record was `read` from the data-source, or has been `create`d and `save`d. Otherwise `false`.

export() public method

public export ( array $options = [] )
$options	array

increment() public method

Defaults to 1 if no value is specified. Throws an exception if the specified field is non-numeric.

public increment ( string $field, integer \| string $value = 1 ) : integer
$field	string	The name of the field to be incremented.
$value	integer \| string	The value to increment the field by. Defaults to `1` if this parameter is not specified.
return	integer	Returns the current value of `$field`, based on the value retrieved from the data source when the entity was loaded, plus any increments applied. Note that it may not reflect the most current value in the persistent backend data source.

model() public method

Returns the model which this entity is bound to.

public model ( ) : string
return	string	The fully qualified model class name.

modified() public method

Gets the current state for a given field or, if no field is given, gets the array of fields modified on this entity.

public modified ( $field = null ) : mixed
return	mixed	Returns `true` if a field is given and was updated, `false` otherwise and `null` if the field was not set at all. If no field is given returns an arra where the keys are entity field names, and the values are `true` for changed fields.

parent() public method

Returns the parent object of this object, if any.

public parent ( ) : object
return	object	Returns the object that contains this object, or `null`.

respondsTo() public method

Determines if a given method can be called.

public respondsTo ( string $method, boolean $internal = false ) : boolean
$method	string	Name of the method.
$internal	boolean	Provide `true` to perform check from inside the class/object. When `false` checks also for public visibility; defaults to `false`.
return	boolean	Returns `true` if the method can be called, `false` otherwise.

schema() public method

public schema ( $field = null )

serialize() public method

Note: because of the limitations outlined below custom handlers and schema are ignored with serialized objects. Properties that hold anonymous functions are also skipped. Some of these can almost be reconstructed (_handlers) others cannot (_methodFilters and schema).

public serialize ( ) : string
return	string	Serialized properties of the object.

set() public method

Allows several properties to be assigned at once, i.e.: $record->set(array('title' => 'Lorem Ipsum', 'value' => 42));

public set ( array $data ) : void
$data	array	An associative array of fields and values to assign to this `Entity` instance.
return	void

sync() public method

Called after an Entity is saved. Updates the object's internal state to reflect the corresponding database entity, and sets the Entity object's key, if this is a newly-created object. **Do not** call this method if you intend to update the database's copy of the entity. Instead, see Model::save().

to() public method

Converts the data in the record set to a different format, i.e. an array.

public to ( string $format, array $options = [] ) : mixed
$format	string	Currently only `array`.
$options	array	Options for converting: - `'indexed'` _boolean_: Allows to control how converted data of nested collections is keyed. When set to `true` will force indexed conversion of nested collection data. By default `false` which will only index the root level.
return	mixed

unserialize() public method

Restores state of the object including pulled results. Tries to restore _handlers by calling into _init().

public unserialize ( string $data ) : void
$data	string	Serialized properties of the object.
return	void

Property Details

$_autoConfig protected_oe property

Auto configuration.

protected array $_autoConfig
return	array

$_data protected_oe property

Associative array of the entity's fields and values.

protected array $_data
return	array

$_errors protected_oe property

The list of validation errors associated with this object, where keys are field names, and values are arrays containing one or more validation error messages.

$_exists protected_oe property

A flag indicating whether or not this entity exists. Set to false if this is a newly-created entity, or if this entity has been loaded and subsequently deleted. Set to true if the entity has been loaded from the database, or has been created and subsequently saved.

protected bool $_exists
return	boolean

$_handlers protected_oe property

Hold the "data export" handlers where the keys are fully-namespaced class names, and the values are closures that take an instance of the class as a parameter, and return an array or scalar value that the instance represents.

$_increment protected_oe property

An array of key/value pairs corresponding to fields that should be updated using atomic incrementing / decrementing operations. Keys match field names, and values indicate the value each field should be incremented or decremented by.

See also: lithium\data\Entity::increment()

See also: lithium\data\Entity::decrement()

protected array $_increment
return	array

$_model protected_oe property

Fully-namespaced class name of model that this record is bound to. Instance methods declared in the model may be called on the entity. See the Model class documentation for more information.

$_parent protected_oe property

If this record is chained off of another, contains the origin object.

protected object $_parent
return	object

$_relationships protected_oe property

An array containing all related records and recordsets, keyed by relationship name, as defined in the bound model class.

protected array $_relationships
return	array

$_schema protected_oe property

to create a form.

protected array $_schema
return	array

$_updated protected_oe property

Contains the values of updated fields. These values will be persisted to the backend data store when the document is saved.

protected array $_updated
return	array

public errors ( array \| string $field = null, string $value = null ) : mixed
$field	array \| string	If an array, overwrites `$this->_errors` if it is empty, if not, merges the errors with the current values. If a string, and `$value` is not `null`, sets the corresponding key in `$this->_errors` to `$value`. Setting `$field` to `false` will reset the current state.
$value	string	Value to set.
return	mixed	Either the `$this->_errors` array, or single value from it.

public sync ( mixed $id = null, array $data = [], array $options = [] )
$id	mixed	The ID to assign, where applicable.
$data	array	Any additional generated data assigned to the object by the database.
$options	array	Method options: - `'materialize'` _boolean_: Determines whether or not the flag should be set that indicates that this entity exists in the data store. Defaults to `true`. - `'dematerialize'` _boolean_: If set to `true`, indicates that this entity has been deleted from the data store and no longer exists. Defaults to `false`.