aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorbrettp <brettp@36083f99-b078-4883-b0ff-0f9b5a30f544>2010-09-22 15:53:43 +0000
committerbrettp <brettp@36083f99-b078-4883-b0ff-0f9b5a30f544>2010-09-22 15:53:43 +0000
commit6a49dcf1082e3047d3c92a3b3b3bb43efa2b2c74 (patch)
treefaa6d5bcf64637fa2a7ab700c33b2a8eaeff44fa
parent433569d138df777798381970fb21208020c41267 (diff)
downloadelgg-6a49dcf1082e3047d3c92a3b3b3bb43efa2b2c74.tar.gz
elgg-6a49dcf1082e3047d3c92a3b3b3bb43efa2b2c74.tar.bz2
Refs #2450: Documented ElggObject.
git-svn-id: http://code.elgg.org/elgg/trunk@6955 36083f99-b078-4883-b0ff-0f9b5a30f544
-rw-r--r--engine/classes/ElggObject.php75
1 files changed, 48 insertions, 27 deletions
diff --git a/engine/classes/ElggObject.php b/engine/classes/ElggObject.php
index af67ef3f6..0bdfb064f 100644
--- a/engine/classes/ElggObject.php
+++ b/engine/classes/ElggObject.php
@@ -1,18 +1,24 @@
<?php
-
/**
- * ElggObject
- * Representation of an "object" in the system.
+ * Elgg Object
+ *
+ * Elgg objects are the most common means of storing information in the database.
+ * They are a child class of ElggEntity, so receive all the benefits of the Entities,
+ * but also include a title and description field.
+ *
+ * An ElggObject represents a row from the objects_entity table, as well
+ * as the related row in the entities table as represented by the parent
+ * ElggEntity object.
+ *
+ * @internal Title and description are stored in the objects_entity table.
*
- * @package Elgg
- * @subpackage Core
+ * @package Elgg.Core
+ * @subpackage DataModel.Object
*/
class ElggObject extends ElggEntity {
/**
- * Initialise the attributes array.
- * This is vital to distinguish between metadata and base parameters.
- *
- * Place your base parameters here.
+ * Initialise the attributes array to include the type,
+ * title, and description.
*/
protected function initialise_attributes() {
parent::initialise_attributes();
@@ -24,11 +30,16 @@ class ElggObject extends ElggEntity {
}
/**
- * Construct a new object entity, optionally from a given id value.
+ * Load or create a new ElggObject.
+ *
+ * If no arguments are passed, create a new entity.
+ * If an argument is passed as an int, attempt to load that object by guid.
+ * If an argument is passed as an object, assume that it is as database result object and attempt to load
+ * by $obj->guid.
*
- * @param mixed $guid If an int, load that GUID.
- * If a db row then will attempt to load the rest of the data.
- * @throws Exception if there was a problem creating the object.
+ * @param mixed $guid If an int, load that GUID. If a db row then will attempt to load the rest of the data.
+ * @throws IOException If passed an incorrect guid
+ * @throws InvalidParameterException If passed an Elgg* Entity that isn't an ElggObject
*/
function __construct($guid = null) {
$this->initialise_attributes();
@@ -70,12 +81,11 @@ class ElggObject extends ElggEntity {
}
/**
- * Override the load function.
- * This function will ensure that all data is loaded (were possible), so
- * if only part of the ElggObject is loaded, it'll load the rest.
+ * Loads the full ElggObject when given a guid.
*
* @param int $guid
- * @return true|false
+ * @return bool
+ * @throws InvalidClassException
*/
protected function load($guid) {
// Test to see if we have the generic stuff
@@ -105,35 +115,42 @@ class ElggObject extends ElggEntity {
}
/**
- * Override the save function.
- * @return true|false
+ * Saves object-specific attributes.
+ *
+ * @internal Object attributes are saved in the objects_entity table.
+ *
+ * @return bool
*/
public function save() {
- // Save generic stuff
+ // Save ElggEntity attributes
if (!parent::save()) {
return false;
}
- // Now save specific stuff
+ // Save ElggObject-specific attributes
return create_object_entity($this->get('guid'), $this->get('title'), $this->get('description'), $this->get('container_guid'));
}
/**
- * Get sites that this object is a member of
+ * Return sites that this object is a member of
+ *
+ * Site membership is determined by relationships and not site_guid.d
*
* @param string $subtype Optionally, the subtype of result we want to limit to
* @param int $limit The number of results to return
* @param int $offset Any indexing offset
+ * @todo This should be moved to ElggEntity
+ * @todo Unimplemented
*/
function getSites($subtype="", $limit = 10, $offset = 0) {
return get_site_objects($this->getGUID(), $subtype, $limit, $offset);
}
/**
- * Add this object to a particular site
+ * Add this object to a site
*
* @param int $site_guid The guid of the site to add it to
- * @return true|false
+ * @return bool
*/
function addToSite($site_guid) {
return add_site_object($this->getGUID(), $site_guid);
@@ -152,7 +169,7 @@ class ElggObject extends ElggEntity {
}
/**
- * Return the container GUID of this object.
+ * Returns the container GUID of this object.
*
* @return int
*/
@@ -161,7 +178,7 @@ class ElggObject extends ElggEntity {
}
/**
- * As getContainer(), but returns the whole entity.
+ * Returns the contain entity for this object.
*
* @return mixed ElggGroup object or false.
*/
@@ -185,10 +202,14 @@ class ElggObject extends ElggEntity {
*/
//public function getCollections($subtype="", $limit = 10, $offset = 0) { get_object_collections($this->getGUID(), $subtype, $limit, $offset); }
- // EXPORTABLE INTERFACE ////////////////////////////////////////////////////////////
+ /*
+ * EXPORTABLE INTERFACE
+ */
/**
* Return an array of fields which can be exported.
+ *
+ * @return array
*/
public function getExportableValues() {
return array_merge(parent::getExportableValues(), array(