Extracting the EntityInterface, this will help with other datasources…

… that require their own special classes to be saved

src/Datasource/EntityInterface.php

@@ -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);
+
+}

src/Datasource/EntityTrait.php

@@ -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)) {

src/Datasource/RepositoryInterface.php

@@ -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);
 

src/ORM/Entity.php

@@ -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;
 

src/ORM/Table.php

@@ -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