closes #1145 - deprecated current "copy constructor" for all entities and implemented a clone method. The clone copies over all metadata but not annotations and private settings. It sets the guid to 0 so saving the cloned entity creates a new database record. The ownership/access of metadata is set during the save and will be the same as that of the entity.

git-svn-id: http://code.elgg.org/elgg/trunk@3802 36083f99-b078-4883-b0ff-0f9b5a30f544

6 files changed, 56 insertions, 7 deletions

diff --git a/engine/lib/entities.php b/engine/lib/entities.php
index 1c833ab29..7b5cd22a3 100644
--- a/engine/lib/entities.php
+++ b/engine/lib/entities.php
@@ -124,6 +124,47 @@ abstract class ElggEntity implements
 	}
 
 	/**
+	 * Clone an entity 
+	 * 
+	 * Resets the guid so that the entity can be saved as a distinct entity from 
+	 * the original. Creation time will be set when this new entity is saved. 
+	 * The owner and container guids come from the original entity. The clone 
+	 * method copies metadata but does not copy over annotations, or private settings.
+	 * 
+	 * Note: metadata will have its owner and access id set when the entity is saved
+	 * and it will be the same as that off the entity.
+	 */
+	public function __clone() {
+		
+		$orig_entity = get_entity($this->guid);
+		if (!$orig_entity) {
+			elgg_log("Failed to clone entity with GUID $this->guid", "ERROR");
+			return;
+		}
+		
+		$metadata_array = get_metadata_for_entity($this->guid);
+
+		$this->attributes['guid'] = "";
+
+		// copy metadata over to new entity - slightly convoluted due to
+		// handling of metadata arrays
+		if (is_array($metadata_array)) {
+			// create list of metadata names
+			$metadata_names = array();
+			foreach ($metadata_array as $metadata) {
+				$metadata_names[] = $metadata['name'];
+			}
+			// arrays are stored with multiple enties per name
+			$metadata_names = array_unique($metadata_names);
+			
+			// move the metadata over
+			foreach ($metadata_names as $name) {
+				$this->set($name, $orig_entity->$name);
+			}
+		}
+	}
+	
+	/**
 	 * Return the value of a given key.
 	 * If $name is a key field (as defined in $this->attributes) that value is returned, otherwise it will
 	 * then look to see if the value is in this object's metadata.
@@ -265,10 +306,10 @@ abstract class ElggEntity implements
 	/**
 	 * Set a piece of metadata.
 	 *
-	 * @param string $name
-	 * @param mixed $value
-	 * @param string $value_type
-	 * @param bool $multiple
+	 * @param string $name Name of the metadata
+	 * @param mixed $value Value of the metadata
+	 * @param string $value_type Types supported: integer and string. Will auto-identify if not set
+	 * @param bool $multiple 
 	 * @return bool
 	 */
 	public function setMetaData($name, $value, $value_type = "", $multiple = false) {
diff --git a/engine/lib/group.php b/engine/lib/group.php
index 589e664d1..cbc34b71b 100644
--- a/engine/lib/group.php
+++ b/engine/lib/group.php
@@ -48,6 +48,8 @@ class ElggGroup extends ElggEntity
 			}
 			// Is $guid is an ElggGroup? Use a copy constructor
 			else if ($guid instanceof ElggGroup) {
+				elgg_log('This type of usage of the ElggGroup constructor was deprecated in 1.7. Please use the clone method.', 'WARNING');
+				
 				foreach ($guid->attributes as $key => $value) {
 					$this->attributes[$key] = $value;
 				}
diff --git a/engine/lib/metadata.php b/engine/lib/metadata.php
index dbe021414..955939e42 100644
--- a/engine/lib/metadata.php
+++ b/engine/lib/metadata.php
@@ -183,9 +183,9 @@ function remove_metadata($entity_guid, $name, $value = "") {
 /**
  * Create a new metadata object, or update an existing one.
  *
- * @param int $entity_guid
- * @param string $name
- * @param string $value
+ * @param int $entity_guid The entity to attach the metadata to
+ * @param string $name Name of the metadata
+ * @param string $value Value of the metadata (cannot be associative array)
  * @param string $value_type
  * @param int $owner_guid
  * @param int $access_id
diff --git a/engine/lib/objects.php b/engine/lib/objects.php
index e4c3128b9..f2faf0d10 100644
--- a/engine/lib/objects.php
+++ b/engine/lib/objects.php
@@ -54,6 +54,8 @@ class ElggObject extends ElggEntity {
 
 			// Is $guid is an ElggObject? Use a copy constructor
 			else if ($guid instanceof ElggObject) {
+				elgg_log('This type of usage of the ElggObject constructor was deprecated in 1.7. Please use the clone method.', 'WARNING');
+				
 				foreach ($guid->attributes as $key => $value) {
 					$this->attributes[$key] = $value;
 				}
diff --git a/engine/lib/sites.php b/engine/lib/sites.php
index d38113d27..0892f2963 100644
--- a/engine/lib/sites.php
+++ b/engine/lib/sites.php
@@ -54,6 +54,8 @@ class ElggSite extends ElggEntity {
 
 			// Is $guid is an ElggSite? Use a copy constructor
 			else if ($guid instanceof ElggSite) {
+				elgg_log('This type of usage of the ElggSite constructor was deprecated in 1.7. Please use the clone method.', 'WARNING');
+				
 				foreach ($guid->attributes as $key => $value) {
 					$this->attributes[$key] = $value;
 				}
diff --git a/engine/lib/users.php b/engine/lib/users.php
index 7ef9e2fda..512b8a6e6 100644
--- a/engine/lib/users.php
+++ b/engine/lib/users.php
@@ -75,6 +75,8 @@ class ElggUser extends ElggEntity
 
 			// Is $guid is an ElggUser? Use a copy constructor
 			else if ($guid instanceof ElggUser) {
+				elgg_log('This type of usage of the ElggUser constructor was deprecated in 1.7. Please use the clone method.', 'WARNING');
+				
 				foreach ($guid->attributes as $key => $value) {
 					$this->attributes[$key] = $value;
 				}