Skip to content
Permalink
Browse files

Extracting the EntityInterface, this will help with other datasources…

… that require their own special classes to be saved
  • Loading branch information...
lorenzo committed Feb 16, 2014
1 parent 9509358 commit 9e3ffbac9201d4833c486c5bd634148a0506590a
@@ -0,0 +1,194 @@
<?php
/**
* CakePHP(tm) : Rapid Development Framework (http://cakephp.org)
* Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
*
* Licensed under The MIT License
* For full copyright and license information, please see the LICENSE.txt
* Redistributions of files must retain the above copyright notice.
*
* @copyright Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
* @link http://cakephp.org CakePHP(tm) Project
* @since CakePHP(tm) v 3.0.0
* @license MIT License (http://www.opensource.org/licenses/mit-license.php)
*/
namespace Cake\Datasource;
use ArrayAccess;
use Cake\Validation\Validator;
use JsonSerializable;
/**
* Describes the methods that any class representing a data storage should
* comply with.
*/
interface EntityInterface extends ArrayAccess, JsonSerializable {
/**
* Sets one or multiple properties to the specified value
*
* @param string|array $property the name of property to set or a list of
* properties with their respective values
* @param mixed|array $value 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
* @param array $options options to be used for setting the property. Allowed option
* keys are `setter` and `guard`
* @return \Cake\Datasource\EntityInterface
*/
public function set($property, $value = null, $options = []);
/**
* Returns the value of a property by name
*
* @param string $property the name of the property to retrieve
* @return mixed
*/
public function &get($property);
/**
* Returns whether this entity contains a property named $property
* regardless of if it is empty.
*
* @param string $property
* @return boolean
*/
public function has($property);
/**
* Removes a property or list of properties from this entity
*
* @param string|array $property
* @return \Cake\ORM\
*/
public function unsetProperty($property);
/**
* 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.
*
* @param null|array Either an array of properties to hide or null to get properties
* @return array|Entity
*/
public function hiddenProperties($properties = null);
/**
* 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.
*
* @param null|array Either an array of properties to treat as virtual or null to get properties
* @return array|Entity
*/
public function virtualProperties($properties = null);
/**
* Get the list of visible properties.
*
* @return array A list of properties that are 'visible' in all representations.
*/
public function visibleProperties();
/**
* Returns an array with all the properties that have been set
* to this entity
*
* @return array
*/
public function toArray();
/**
* Returns an array with the requested properties
* stored in this entity, indexed by property name
*
* @param array $properties list of properties to be returned
* @param boolean $onlyDirty Return the requested property only if it is dirty
* @return array
*/
public function extract(array $properties, $onlyDirty = false);
/**
* 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
*
* @param string $property the field to set or check status for
* @param null|boolean true means the property was changed, false means
* it was not changed and null will make the function return current state
* for that property
* @return boolean whether the property was changed or not
*/
public function dirty($property = null, $isDirty = null);
/**
* 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
*
* @return void
*/
public function clean();
/**
* 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.
*
* @param boolean $new true if it is known this instance was persisted
* @return boolean if it is known whether the entity was already persisted
* null otherwise
*/
public function isNew($new = null);
/**
* Validates the internal properties using a validator object. The resulting
* errors will be copied inside this entity and can be retrieved using the
* `errors` method.
*
* This function returns true if there were no validation errors or false
* otherwise.
*
* @param \Cake\Validation\Validator $validator
* @return boolean
*/
public function validate(Validator $validator);
/**
* 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.
*
* When used as a setter, this method will return this entity instance for method
* chaining.
*
* @param string|array $field
* @param string|array $errors The errors to be set for $field
* @return array|\Cake\Datasource\EntityInterface
*/
public function errors($field = null, $errors = null);
/**
* 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.
*
* @param string|array single or list of properties to change its accessibility
* @param boolean $set true marks the property as accessible, false will
* mark it as protected.
* @return \Cake\Datasource\EntityInterface|boolean
*/
public function accessible($property, $set = null);
}
@@ -189,7 +189,7 @@ public function __unset($property) {
* first argument is also an array, in which case will be treated as $options
* @param array $options options to be used for setting the property. Allowed option
* keys are `setter` and `guard`
* @return \Cake\ORM\Entity
* @return \Cake\Datasource\EntityInterface this object
*/
public function set($property, $value = null, $options = []) {
if (is_string($property)) {
@@ -14,7 +14,7 @@
*/
namespace Cake\Datasource;
use Cake\ORM\Entity;
use Cake\Datasource\EntityInterface;
/**
* Describes the methods that any class representing a data storage should
@@ -54,7 +54,7 @@ public function find($type = 'all', $options = []);
* @param array $options options accepted by `Table::find()`
* @throws Cake\ORM\Error\RecordNotFoundException if the record with such id
* could not be found
* @return \Cake\ORM\Entity
* @return \Cake\Datasource\EntityInterface
* @see RepositoryInterface::find()
*/
public function get($primaryKey, $options = []);
@@ -111,23 +111,23 @@ public function exists(array $conditions);
* returns the same entity after a successful save or false in case
* of any error.
*
* @param \Cake\ORM\Entity the entity to be saved
* @param \Cake\Datasource\EntityInterface the entity to be saved
* @param array $options
* @return \Cake\ORM\Entity|boolean
* @return \Cake\Datasource\EntityInterface|boolean
*/
public function save(Entity $entity, array $options = []);
public function save(EntityInterface $entity, array $options = []);
/**
* Delete a single entity.
*
* Deletes an entity and possibly related associations from the database
* based on the 'dependent' option used when defining the association.
*
* @param Entity $entity The entity to remove.
* @param \Cake\Datasource\EntityInterface $entity The entity to remove.
* @param array $options The options fo the delete.
* @return boolean success
*/
public function delete(Entity $entity, array $options = []);
public function delete(EntityInterface $entity, array $options = []);
/**
* Create a new entity + associated entities from an array.
@@ -146,7 +146,7 @@ public function delete(Entity $entity, array $options = []);
* @param array $data The data to build an entity with.
* @param array $associations A whitelist of associations
* to hydrate. Defaults to all associations
* @return Cake\ORM\Entity
* @return Cake\Datasource\EntityInterface
*/
public function newEntity(array $data = [], $associations = null);
@@ -16,13 +16,14 @@
*/
namespace Cake\ORM;
use Cake\Datasource\EntityInterface;
use Cake\Datasource\EntityTrait;
/**
* An entity represents a single result row from a repository. It exposes the
* methods for retrieving and storing properties associated in this row.
*/
class Entity implements \ArrayAccess, \JsonSerializable {
class Entity implements EntityInterface {
use EntityTrait;
@@ -27,7 +27,7 @@
use Cake\ORM\Association\HasMany;
use Cake\ORM\Association\HasOne;
use Cake\ORM\BehaviorRegistry;
use Cake\ORM\Entity;
use Cake\Datasource\EntityInterface;
use Cake\ORM\Error\MissingEntityException;
use Cake\ORM\Error\RecordNotFoundException;
use Cake\ORM\Marshaller;
@@ -1080,7 +1080,7 @@ public function exists(array $conditions) {
* }}}
*
*/
public function save(Entity $entity, array $options = []) {
public function save(EntityInterface $entity, array $options = []) {
$options = new \ArrayObject($options + [
'atomic' => true,
'validate' => true,
@@ -1106,9 +1106,9 @@ public function save(Entity $entity, array $options = []) {
/**
* Performs the actual saving of an entity based on the passed options.
*
* @param \Cake\ORM\Entity the entity to be saved
* @param \Cake\Datasource\EntityInterface the entity to be saved
* @param array $options
* @return \Cake\ORM\Entity|boolean
* @return \Cake\Datasource\EntityInterface|boolean
*/
protected function _processSave($entity, $options) {
$primary = $entity->extract((array)$this->primaryKey());
@@ -1185,9 +1185,9 @@ protected function _processSave($entity, $options) {
/**
* Auxiliary function to handle the insert of an entity's data in the table
*
* @param \Cake\ORM\Entity the subject entity from were $data was extracted
* @param \Cake\Datasource\EntityInterface the subject entity from were $data was extracted
* @param array $data The actual data that needs to be saved
* @return \Cake\ORM\Entity|boolean
* @return \Cake\Datasource\EntityInterface|boolean
* @throws \RuntimeException if not all the primary keys where supplied or could
* be generated when the table has composite primary keys
*/
@@ -1259,9 +1259,9 @@ protected function _newId($primary) {
/**
* Auxiliary function to handle the update of an entity's data in the table
*
* @param \Cake\ORM\Entity the subject entity from were $data was extracted
* @param \Cake\Datasource\EntityInterface the subject entity from were $data was extracted
* @param array $data The actual data that needs to be saved
* @return \Cake\ORM\Entity|boolean
* @return \Cake\Datasource\EntityInterface|boolean
* @throws \InvalidArgumentException When primary key data is missing.
*/
protected function _update($entity, $data) {
@@ -1316,7 +1316,7 @@ protected function _update($entity, $data) {
* the options used in the delete operation.
*
*/
public function delete(Entity $entity, array $options = []) {
public function delete(EntityInterface $entity, array $options = []) {
$options = new \ArrayObject($options + ['atomic' => true]);
$process = function() use ($entity, $options) {
@@ -1335,7 +1335,7 @@ public function delete(Entity $entity, array $options = []) {
* Will delete the entity provided. Will remove rows from any
* dependent associations, and clear out join tables for BelongsToMany associations.
*
* @param Entity $entity The entity to delete.
* @param \Cake\ORM\EntityInterface $entity The entity to delete.
* @param ArrayObject $options The options for the delete.
* @throws \InvalidArgumentException if there are no primary key values of the
* passed entity
@@ -1605,7 +1605,7 @@ public function newEntities(array $data, $associations = null) {
* ]);
* }}}
*
* @param \Cake\ORM\Entity $entity The entity to be validated
* @param \Cake\Datasource\EntityInterface $entity The entity to be validated
* @param array $options A list of options to use while validating, the following
* keys are accepted:
* - validate: The name of the validation set to use

0 comments on commit 9e3ffba

Please sign in to comment.
You can’t perform that action at this time.