diff options
| author | brettp <brettp@36083f99-b078-4883-b0ff-0f9b5a30f544> | 2010-10-28 19:17:36 +0000 |
|---|---|---|
| committer | brettp <brettp@36083f99-b078-4883-b0ff-0f9b5a30f544> | 2010-10-28 19:17:36 +0000 |
| commit | 7ddd9521b3f3a397da3b0a6b56238d31414eb4be (patch) | |
| tree | 6eb6a9a51db5fa0f5d3cc2ec6de29b9e258b12a1 /engine/classes | |
| parent | bd3484417d170e62bc94e9db81d4ad37e8ddee6a (diff) | |
| download | elgg-7ddd9521b3f3a397da3b0a6b56238d31414eb4be.tar.gz elgg-7ddd9521b3f3a397da3b0a6b56238d31414eb4be.tar.bz2 | |
Standardized code in all of core, not including language files, tests, or core mods.
git-svn-id: http://code.elgg.org/elgg/trunk@7124 36083f99-b078-4883-b0ff-0f9b5a30f544
Diffstat (limited to 'engine/classes')
67 files changed, 2222 insertions, 775 deletions
diff --git a/engine/classes/APIException.php b/engine/classes/APIException.php index a16ea3e62..377538c36 100644 --- a/engine/classes/APIException.php +++ b/engine/classes/APIException.php @@ -1,10 +1,11 @@ <?php + /** * API Exception Stub * * Generic parent class for API exceptions. * - * @package Elgg.Core + * @package Elgg.Core * @subpackage Exceptions.Stub */ class APIException extends Exception {}
\ No newline at end of file diff --git a/engine/classes/CallException.php b/engine/classes/CallException.php index e39703454..02c580a52 100644 --- a/engine/classes/CallException.php +++ b/engine/classes/CallException.php @@ -4,7 +4,7 @@ * * Generic parent class for Call exceptions * - * @package Elgg.Core + * @package Elgg.Core * @subpackage Exceptions.Stub */ class CallException extends Exception {}
\ No newline at end of file diff --git a/engine/classes/ClassException.php b/engine/classes/ClassException.php index db510a68d..7544f0ec9 100644 --- a/engine/classes/ClassException.php +++ b/engine/classes/ClassException.php @@ -4,7 +4,7 @@ * * A generic parent class for Class exceptions * - * @package Elgg.Core + * @package Elgg.Core * @subpackage Exceptions.Stub */ class ClassException extends Exception {} diff --git a/engine/classes/ClassNotFoundException.php b/engine/classes/ClassNotFoundException.php index a24034054..5170b5333 100644 --- a/engine/classes/ClassNotFoundException.php +++ b/engine/classes/ClassNotFoundException.php @@ -4,7 +4,7 @@ * * Thrown when trying to load a class that doesn't exist. * - * @package Elgg.Core + * @package Elgg.Core * @subpackage Exceptions */ class ClassNotFoundException extends ClassException {}
\ No newline at end of file diff --git a/engine/classes/ConfigurationException.php b/engine/classes/ConfigurationException.php index 8fb861062..3ace5dd4b 100644 --- a/engine/classes/ConfigurationException.php +++ b/engine/classes/ConfigurationException.php @@ -4,7 +4,7 @@ * * A generic parent class for Configuration exceptions * - * @package Elgg + * @package Elgg * @subpackage Exceptions.Stub */ class ConfigurationException extends Exception {} diff --git a/engine/classes/CronException.php b/engine/classes/CronException.php index 164170daf..3604c21b9 100644 --- a/engine/classes/CronException.php +++ b/engine/classes/CronException.php @@ -4,7 +4,7 @@ * * A generic parent class for cron exceptions * - * @package Elgg + * @package Elgg * @subpackage Exceptions.Stub */ class CronException extends Exception {}
\ No newline at end of file diff --git a/engine/classes/DataFormatException.php b/engine/classes/DataFormatException.php index 50d25f56f..0f28a0902 100644 --- a/engine/classes/DataFormatException.php +++ b/engine/classes/DataFormatException.php @@ -3,7 +3,7 @@ * Data format exception * An exception thrown when there is a problem in the format of some data. * - * @package Elgg.Core + * @package Elgg.Core * @subpackage Exceptions.Stub */ class DataFormatException extends Exception {} diff --git a/engine/classes/DatabaseException.php b/engine/classes/DatabaseException.php index 011492417..6c8f57d7d 100644 --- a/engine/classes/DatabaseException.php +++ b/engine/classes/DatabaseException.php @@ -4,7 +4,7 @@ * * A generic parent class for database exceptions * - * @package Elgg.Core + * @package Elgg.Core * @subpackage Exceptions.Stub */ class DatabaseException extends Exception {} diff --git a/engine/classes/ElggAccess.php b/engine/classes/ElggAccess.php index eee5ec963..9fc63866a 100644 --- a/engine/classes/ElggAccess.php +++ b/engine/classes/ElggAccess.php @@ -2,11 +2,12 @@ /** * Class used to determin if access is being ignored. * - * @access private - * @todo I don't remember why this was required beyond scope concerns. - * @see elgg_get_ignore_access() - * @package Elgg.Core + * @package Elgg.Core * @subpackage Access + * @access private + * @see elgg_get_ignore_access() + * + * @todo I don't remember why this was required beyond scope concerns. */ class ElggAccess { /** @@ -17,19 +18,46 @@ class ElggAccess { /** * Get current ignore access setting. + * * @return bool + * @deprecated 1.8 Use ElggAccess::getIgnoreAccess() */ public function get_ignore_access() { + elgg_deprecated_notice('ElggAccess::get_ignore_access() is deprecated by ElggAccess::getIgnoreAccess()', 1.8); + return $this->getIgnoreAccess(); + } + + /** + * Get current ignore access setting. + * + * @return bool + */ + public function getIgnoreAccess() { return $this->ignore_access; } /** * Set ignore access. * - * @param $ignore bool true || false to ignore + * @param bool $ignore Ignore access + * * @return bool Previous setting + * + * @deprecated 1.8 Use ElggAccess:setIgnoreAccess() */ public function set_ignore_access($ignore = true) { + elgg_deprecated_notice('ElggAccess::set_ignore_access() is deprecated by ElggAccess::setIgnoreAccess()', 1.8); + return $this->setIgnoreAccess($ignore); + } + + /** + * Set ignore access. + * + * @param bool $ignore Ignore access + * + * @return bool Previous setting + */ + public function setIgnoreAccess($ignore = true) { $prev = $this->ignore_access; $this->ignore_access = $ignore; diff --git a/engine/classes/ElggAnnotation.php b/engine/classes/ElggAnnotation.php index ec2cedfe5..cdcfe363f 100644 --- a/engine/classes/ElggAnnotation.php +++ b/engine/classes/ElggAnnotation.php @@ -8,16 +8,16 @@ * * @internal Annotations are stored in the annotations table. * - * @package Elgg.Core + * @package Elgg.Core * @subpackage DataModel.Annotations - * @link http://docs.elgg.org/DataModel/Annotations + * @link http://docs.elgg.org/DataModel/Annotations */ class ElggAnnotation extends ElggExtender { /** * Construct a new annotation, optionally from a given id value or db object. * - * @param mixed $id + * @param mixed $id The annotation ID */ function __construct($id = null) { $this->attributes = array(); @@ -32,7 +32,7 @@ class ElggAnnotation extends ElggExtender { if ($annotation) { $objarray = (array) $annotation; - foreach($objarray as $key => $value) { + foreach ($objarray as $key => $value) { $this->attributes[$key] = $value; } @@ -44,7 +44,8 @@ class ElggAnnotation extends ElggExtender { /** * Class member get overloading * - * @param string $name + * @param string $name The name of the value to get + * * @return mixed */ function __get($name) { @@ -54,9 +55,10 @@ class ElggAnnotation extends ElggExtender { /** * Class member set overloading * - * @param string $name - * @param mixed $value - * @return void + * @param string $name The name of the value to set + * @param mixed $value The value to set + * + * @return mixed */ function __set($name, $value) { return $this->set($name, $value); @@ -69,7 +71,8 @@ class ElggAnnotation extends ElggExtender { */ function save() { if ($this->id > 0) { - return update_annotation($this->id, $this->name, $this->value, $this->value_type, $this->owner_guid, $this->access_id); + return update_annotation($this->id, $this->name, $this->value, $this->value_type, + $this->owner_guid, $this->access_id); } else { $this->id = create_annotation($this->entity_guid, $this->name, $this->value, $this->value_type, $this->owner_guid, $this->access_id); @@ -83,6 +86,8 @@ class ElggAnnotation extends ElggExtender { /** * Delete the annotation. + * + * @return bool */ function delete() { return delete_annotation($this->id); @@ -97,12 +102,16 @@ class ElggAnnotation extends ElggExtender { return get_annotation_url($this->id); } - // SYSTEM LOG INTERFACE //////////////////////////////////////////////////////////// + // SYSTEM LOG INTERFACE /** * For a given ID, return the object associated with it. * This is used by the river functionality primarily. * This is useful for checking access permissions etc on objects. + * + * @param int $id An annotation ID. + * + * @return ElggAnnotation */ public function getObjectFromID($id) { return get_annotation($id); diff --git a/engine/classes/ElggCache.php b/engine/classes/ElggCache.php index a494471b9..549772d6d 100644 --- a/engine/classes/ElggCache.php +++ b/engine/classes/ElggCache.php @@ -3,7 +3,7 @@ * ElggCache The elgg cache superclass. * This defines the interface for a cache (wherever that cache is stored). * - * @package Elgg.Core + * @package Elgg.Core * @subpackage Cache */ abstract class ElggCache implements @@ -26,10 +26,27 @@ abstract class ElggCache implements /** * Set a cache variable. * - * @param string $variable - * @param string $value + * @param string $variable Name + * @param string $value Value + * + * @return void + * + * @deprecated 1.8 Use ElggAccess:setVariable() */ public function set_variable($variable, $value) { + elgg_deprecated_notice('ElggCache::set_variable() is deprecated by ElggCache::setVariable()', 1.8); + $this->setVariable($variable, $value); + } + + /** + * Set a cache variable. + * + * @param string $variable Name + * @param string $value Value + * + * @return void + */ + public function setVariable($variable, $value) { if (!is_array($this->variables)) { $this->variables = array(); } @@ -40,10 +57,25 @@ abstract class ElggCache implements /** * Get variables for this cache. * - * @param string $variable - * @return mixed The variable or null; + * @param string $variable Name + * + * @return mixed The value or null; + * + * @deprecated 1.8 Use ElggCache::getVariable() */ public function get_variable($variable) { + elgg_deprecated_notice('ElggCache::get_variable() is deprecated by ElggCache::getVariable()', 1.8); + return $this->getVariable($variable); + } + + /** + * Get variables for this cache. + * + * @param string $variable Name + * + * @return mixed The variable or null; + */ + public function getVariable($variable) { if (isset($this->variables[$variable])) { return $this->variables[$variable]; } @@ -54,7 +86,8 @@ abstract class ElggCache implements /** * Class member get overloading, returning key using $this->load defaults. * - * @param string $key + * @param string $key Name + * * @return mixed */ function __get($key) { @@ -64,8 +97,9 @@ abstract class ElggCache implements /** * Class member set overloading, setting a key using $this->save defaults. * - * @param string $key - * @param mixed $value + * @param string $key Name + * @param mixed $value Value + * * @return mixed */ function __set($key, $value) { @@ -76,6 +110,7 @@ abstract class ElggCache implements * Supporting isset, using $this->load() with default values. * * @param string $key The name of the attribute or metadata. + * * @return bool */ function __isset($key) { @@ -86,6 +121,8 @@ abstract class ElggCache implements * Supporting unsetting of magic attributes. * * @param string $key The name of the attribute or metadata. + * + * @return bool */ function __unset($key) { return $this->delete($key); @@ -94,8 +131,9 @@ abstract class ElggCache implements /** * Save data in a cache. * - * @param string $key - * @param string $data + * @param string $key Name + * @param string $data Value + * * @return bool */ abstract public function save($key, $data); @@ -103,9 +141,10 @@ abstract class ElggCache implements /** * Load data from the cache using a given key. * - * @param string $key - * @param int $offset - * @param int $limit + * @param string $key Name + * @param int $offset Offset + * @param int $limit Limit + * * @return mixed The stored data or false. */ abstract public function load($key, $offset = 0, $limit = null); @@ -113,7 +152,8 @@ abstract class ElggCache implements /** * Invalidate a key * - * @param string $key + * @param string $key Name + * * @return bool */ abstract public function delete($key); @@ -121,16 +161,18 @@ abstract class ElggCache implements /** * Clear out all the contents of the cache. * + * @return bool */ abstract public function clear(); /** * Add a key only if it doesn't already exist. - * Implemented simply here, if you extend this class and your caching engine provides a better way then - * override this accordingly. + * Implemented simply here, if you extend this class and your caching engine + * provides a better way then override this accordingly. + * + * @param string $key Name + * @param string $data Value * - * @param string $key - * @param string $data * @return bool */ public function add($key, $data) { @@ -142,20 +184,58 @@ abstract class ElggCache implements } // ARRAY ACCESS INTERFACE ////////////////////////////////////////////////////////// + + /** + * Set offset + * + * @see ArrayAccess::offsetSet() + * + * @param mixed $key Name + * @param mixed $value Value + * + * @return void + */ function offsetSet($key, $value) { $this->save($key, $value); } + /** + * Get offset + * + * @see ArrayAccess::offsetGet() + * + * @param mixed $key Name + * + * @return void + */ function offsetGet($key) { return $this->load($key); } + /** + * Unsets offset + * + * @see ArrayAccess::offsetUnset() + * + * @param mixed $key Name + * + * @return void + */ function offsetUnset($key) { - if ( isset($this->key) ) { + if (isset($this->key)) { unset($this->key); } } + /** + * Does offset exist + * + * @see ArrayAccess::offsetExists() + * + * @param mixed $offset Offset + * + * @return void + */ function offsetExists($offset) { return isset($this->$offset); } diff --git a/engine/classes/ElggDiskFilestore.php b/engine/classes/ElggDiskFilestore.php index b0924fbe7..4f9aae1af 100644 --- a/engine/classes/ElggDiskFilestore.php +++ b/engine/classes/ElggDiskFilestore.php @@ -5,9 +5,9 @@ * @warning This should be used by a wrapper class * like {@link ElggFile}. * - * @package Elgg.Core + * @package Elgg.Core * @subpackage FileStore.Disk - * @link http://docs.elgg.org/DataModel/FileStore/Disk + * @link http://docs.elgg.org/DataModel/FileStore/Disk */ class ElggDiskFilestore extends ElggFilestore { /** @@ -42,8 +42,9 @@ class ElggDiskFilestore extends ElggFilestore { * @warning This will try to create the a directory if it doesn't exist, * even in read-only mode. * - * @param ElggFile $file - * @param string $mode read, write, or append. + * @param ElggFile $file The file to open + * @param string $mode read, write, or append. + * * @throws InvalidParameterException * @return resource File pointer resource * @todo This really shouldn't try to create directories if not writing. @@ -52,8 +53,8 @@ class ElggDiskFilestore extends ElggFilestore { $fullname = $this->getFilenameOnFilestore($file); // Split into path and name - $ls = strrpos($fullname,"/"); - if ($ls===false) { + $ls = strrpos($fullname, "/"); + if ($ls === false) { $ls = 0; } @@ -67,7 +68,7 @@ class ElggDiskFilestore extends ElggFilestore { } - if (($mode!='write') && (!file_exists($fullname))) { + if (($mode != 'write') && (!file_exists($fullname))) { return false; } @@ -82,7 +83,8 @@ class ElggDiskFilestore extends ElggFilestore { $mode = "a+b"; break; default: - throw new InvalidParameterException(sprintf(elgg_echo('InvalidParameterException:UnrecognisedFileMode'), $mode)); + $msg = sprintf(elgg_echo('InvalidParameterException:UnrecognisedFileMode'), $mode); + throw new InvalidParameterException($msg); } return fopen($fullname, $mode); @@ -92,8 +94,9 @@ class ElggDiskFilestore extends ElggFilestore { /** * Write data to a file. * - * @param resource $f File pointer resource - * @param mixed $data The data to write. + * @param resource $f File pointer resource + * @param mixed $data The data to write. + * * @return bool */ public function write($f, $data) { @@ -103,9 +106,10 @@ class ElggDiskFilestore extends ElggFilestore { /** * Read data from a file. * - * @param resource $f File pointer resource - * @param int $length The number of bytes to read - * @param inf $offset The number of bytes to start after + * @param resource $f File pointer resource + * @param int $length The number of bytes to read + * @param inf $offset The number of bytes to start after + * * @return mixed Contents of file or false on fail. */ public function read($f, $length, $offset = 0) { @@ -120,6 +124,7 @@ class ElggDiskFilestore extends ElggFilestore { * Close a file pointer * * @param resource $f A file pointer resource + * * @return bool */ public function close($f) { @@ -130,6 +135,7 @@ class ElggDiskFilestore extends ElggFilestore { * Delete an ElggFile file. * * @param ElggFile $file File to delete + * * @return bool */ public function delete(ElggFile $file) { @@ -144,8 +150,10 @@ class ElggDiskFilestore extends ElggFilestore { /** * Seek to the specified position. * - * @param resource $f File resource - * @param int $position Position in bytes + * @param resource $f File resource + * @param int $position Position in bytes + * + * @return bool */ public function seek($f, $position) { return fseek($f, $position); @@ -155,6 +163,8 @@ class ElggDiskFilestore extends ElggFilestore { * Return the current location of the internal pointer * * @param resource $f File pointer resource + * + * @return int|false */ public function tell($f) { return ftell($f); @@ -162,7 +172,10 @@ class ElggDiskFilestore extends ElggFilestore { /** * Tests for end of file on a file pointer + * * @param resource $f File pointer resource + * + * @return bool */ public function eof($f) { return feof($f); @@ -171,7 +184,8 @@ class ElggDiskFilestore extends ElggFilestore { /** * Returns the file size of an ElggFile file. * - * @param ElggFile $file + * @param ElggFile $file File object + * * @return int The file size */ public function getFileSize(ElggFile $file) { @@ -181,7 +195,8 @@ class ElggDiskFilestore extends ElggFilestore { /** * Returns the filename as saved on disk for an ElggFile object * - * @param ElggFile $file + * @param ElggFile $file File object + * * @return string The full path of where the file is stored */ public function getFilenameOnFilestore(ElggFile $file) { @@ -191,7 +206,9 @@ class ElggDiskFilestore extends ElggFilestore { } if ((!$owner) || (!$owner->username)) { - throw new InvalidParameterException(sprintf(elgg_echo('InvalidParameterException:MissingOwner'), $file->getFilename(), $file->guid)); + $msg = sprintf(elgg_echo('InvalidParameterException:MissingOwner'), + $file->getFilename(), $file->guid); + throw new InvalidParameterException($msg); } return $this->dir_root . $this->make_file_matrix($owner->guid) . $file->getFilename(); @@ -200,7 +217,8 @@ class ElggDiskFilestore extends ElggFilestore { /** * Returns the contents of the ElggFile file. * - * @param ElggFile $file + * @param ElggFile $file File object + * * @return mixed */ public function grabFile(ElggFile $file) { @@ -210,7 +228,8 @@ class ElggDiskFilestore extends ElggFilestore { /** * Tests if an ElggFile file exists. * - * @param ElggFile $file + * @param ElggFile $file File object + * * @return bool */ public function exists(ElggFile $file) { @@ -220,8 +239,9 @@ class ElggDiskFilestore extends ElggFilestore { /** * Returns the size of all data stored under a directory in the disk store. * - * @param string $prefix Optional/ The prefix to check under. + * @param string $prefix Optional/ The prefix to check under. * @param string $container_guid The guid of the entity whose data you want to check. + * * @return int|false */ public function getSize($prefix = '', $container_guid) { @@ -236,10 +256,26 @@ class ElggDiskFilestore extends ElggFilestore { * Create a directory $dirroot * * @param string $dirroot The full path of the directory to create + * * @throws IOException * @return true + * @deprecated 1.8 Use ElggDiskFilestore::makeDirectoryRoot() */ protected function make_directory_root($dirroot) { + elgg_deprecated_notice('ElggDiskFilestore::make_directory_root() is deprecated by ::makeDirectoryRoot()', 1.8); + + return $this->makeDirectoryRoot($dirroot); + } + + /** + * Create a directory $dirroot + * + * @param string $dirroot The full path of the directory to create + * + * @throws IOException + * @return true + */ + protected function makeDirectoryRoot($dirroot) { if (!file_exists($dirroot)) { if (!@mkdir($dirroot, 0700, true)) { throw new IOException(sprintf(elgg_echo('IOException:CouldNotMake'), $dirroot)); @@ -252,15 +288,18 @@ class ElggDiskFilestore extends ElggFilestore { /** * Multibyte string tokeniser. * - * Splits a string into an array. Will fail safely if mbstring is not installed (although this may still - * not handle . + * Splits a string into an array. Will fail safely if mbstring is + * not installed. * - * @param string $string String + * @param string $string String * @param string $charset The charset, defaults to UTF8 + * * @return array - * @todo Can be deprecated since we no long split on usernames + * @deprecated 1.8 Files are stored by date and guid; no need for this. */ private function mb_str_split($string, $charset = 'UTF8') { + elgg_deprecated_notice('ElggDiskFilestore::mb_str_split() is deprecated.', 1.8); + if (is_callable('mb_substr')) { $length = mb_strlen($string); $array = array(); @@ -283,15 +322,34 @@ class ElggDiskFilestore extends ElggFilestore { /** * Construct a file path matrix for an entity. * - * @param int The guide of the entity to store the data under. + * @param int $identifier The guide of the entity to store the data under. + * * @return str The path where the entity's data will be stored. + * @deprecated 1.8 Use ElggDiskFilestore::makeFileMatrix() */ protected function make_file_matrix($identifier) { - if (is_numeric($identifier)) { - return $this->user_file_matrix($identifier); + elgg_deprecated_notice('ElggDiskFilestore::make_file_matrix() is deprecated by ::makeFileMatrix()', 1.8); + + return $this->makefileMatrix($identifier); + } + + /** + * Construct a file path matrix for an entity. + * + * @param int $guid The guide of the entity to store the data under. + * + * @return str The path where the entity's data will be stored. + */ + protected function makeFileMatrix($guid) { + $entity = get_entity($guid); + + if (!($entity instanceof ElggEntity) || !$entity->time_created) { + return false; } - return $this->deprecated_file_matrix($identifier); + $time_created = date('Y/m/d', $entity->time_created); + + return "$time_created/$entity->guid/"; } /** @@ -304,45 +362,13 @@ class ElggDiskFilestore extends ElggFilestore { * YYYY/MM/DD/guid/ * * @param int $guid The entity to contrust a matrix for + * * @return str The - * @todo This would work with non-users. Why is it restricted to only users? */ protected function user_file_matrix($guid) { - // lookup the entity - $user = get_entity($guid); - if ($user->type != 'user') { - // only to be used for user directories - return FALSE; - } - - if (!$user->time_created) { - // fall back to deprecated method - return $this->deprecated_file_matrix($user->username); - } - - $time_created = date('Y/m/d', $user->time_created); - return "$time_created/$user->guid/"; - } + elgg_deprecated_notice('ElggDiskFilestore::user_file_matrix() is deprecated by ::makeFileMatrix()', 1.8); - /** - * Construct the filename matrix using a string - * - * Particularly, this is used with a username to generate the file storage - * location. - * - * @deprecated for user directories: use user_file_matrix() instead. - * - * @param str $filename - * @return str - */ - protected function deprecated_file_matrix($filename) { - // throw a warning for using deprecated method - $error = 'Deprecated use of ElggDiskFilestore::make_file_matrix. '; - $error .= 'Username passed instead of guid.'; - elgg_log($error, WARNING); - - $user = new ElggUser($filename); - return $this->user_file_matrix($user->guid); + return $this->makeFileMatrix($guid); } /** @@ -358,7 +384,9 @@ class ElggDiskFilestore extends ElggFilestore { /** * Sets parameters that should be saved to database. * - * return bool + * @param array $parameters Set parameters to save to DB for this filestore. + * + * @return bool */ public function setParameters(array $parameters) { if (isset($parameters['dir_root'])) { diff --git a/engine/classes/ElggEntity.php b/engine/classes/ElggEntity.php index 80617936e..95b141d45 100644 --- a/engine/classes/ElggEntity.php +++ b/engine/classes/ElggEntity.php @@ -22,9 +22,9 @@ * @tip Most plugin authors will want to extend the ElggObject class * instead of this class. * - * @package Elgg.Core + * @package Elgg.Core * @subpackage DataMode.Entities - * @link http://docs.elgg.org/DataModel/ElggEntity + * @link http://docs.elgg.org/DataModel/ElggEntity */ abstract class ElggEntity implements Notable, // Calendar interface @@ -54,12 +54,14 @@ abstract class ElggEntity implements protected $icon_override; /** - * Holds metadata until entity is saved. Once the entity is saved, metadata are written immediately to the database. + * Holds metadata until entity is saved. Once the entity is saved, + * metadata are written immediately to the database. */ protected $temp_metadata; /** - * Holds annotations until entity is saved. Once the entity is saved, annotations are written immediately to the database. + * Holds annotations until entity is saved. Once the entity is saved, + * annotations are written immediately to the database. */ protected $temp_annotations; @@ -76,8 +78,22 @@ abstract class ElggEntity implements * This is vital to distinguish between metadata and base parameters. * * @return void + * @deprecated 1.8 Use initializeAttributes() */ protected function initialise_attributes() { + elgg_deprecated_notice('ElggEntity::initialise_attributes() is deprecated by ::initializeAttributes()', 1.8); + + $this->initializeAttributes(); + } + + /** + * Initialize the attributes array. + * + * This is vital to distinguish between metadata and base parameters. + * + * @return void + */ + protected function initializeAttributes() { initialise_entity_cache(); // Create attributes array if not already created @@ -109,12 +125,16 @@ abstract class ElggEntity implements $this->attributes['enabled'] = "yes"; // There now follows a bit of a hack - /* Problem: To speed things up, some objects are split over several tables, this means that it requires - * n number of database reads to fully populate an entity. This causes problems for caching and create events + /* Problem: To speed things up, some objects are split over several tables, + * this means that it requires n number of database reads to fully populate + * an entity. This causes problems for caching and create events * since it is not possible to tell whether a subclassed entity is complete. - * Solution: We have two counters, one 'tables_split' which tells whatever is interested how many tables - * are going to need to be searched in order to fully populate this object, and 'tables_loaded' which is how - * many have been loaded thus far. + * + * Solution: We have two counters, one 'tables_split' which tells whatever is + * interested how many tables are going to need to be searched in order to fully + * populate this object, and 'tables_loaded' which is how many have been + * loaded thus far. + * * If the two are the same then this object is complete. * * Use: isFullyLoaded() to check @@ -133,6 +153,8 @@ abstract class ElggEntity implements * * @note metadata will have its owner and access id set when the entity is saved * and it will be the same as that of the entity. + * + * @return void */ public function __clone() { $orig_entity = get_entity($this->guid); @@ -174,12 +196,14 @@ abstract class ElggEntity implements * Q: Why are we not using __get overload here? * A: Because overload operators cause problems during subclassing, so we put the code here and * create overloads in subclasses. + * * @todo What problems are these? * * @warning Subtype is returned as an id rather than the subtype string. Use getSubtype() * to get the subtype string. * - * @param string $name + * @param string $name Name + * * @return mixed Returns the value of a given value, or null. */ public function get($name) { @@ -201,16 +225,19 @@ abstract class ElggEntity implements * If $name is defined in $this->attributes that value is set, otherwise it will * set the appropriate item of metadata. * - * @warning It is important that your class populates $this->attributes with keys for all base attributes, anything - * not in their gets set as METADATA. + * @warning It is important that your class populates $this->attributes with keys + * for all base attributes, anything not in their gets set as METADATA. * * Q: Why are we not using __set overload here? * A: Because overload operators cause problems during subclassing, so we put the code here and * create overloads in subclasses. + * * @todo What problems? * - * @param string $name - * @param mixed $value + * @param string $name Name + * @param mixed $value Value + * + * @return bool */ public function set($name, $value) { if (array_key_exists($name, $this->attributes)) { @@ -236,7 +263,8 @@ abstract class ElggEntity implements /** * Return the value of a piece of metadata. * - * @param string $name + * @param string $name Name + * * @return mixed The value, or NULL if not found. */ public function getMetaData($name) { @@ -260,7 +288,8 @@ abstract class ElggEntity implements /** * Return an attribute or a piece of metadata. * - * @param string $name + * @param string $name Name + * * @return mixed */ function __get($name) { @@ -270,8 +299,9 @@ abstract class ElggEntity implements /** * Set an attribute or a piece of metadata. * - * @param string $name - * @param mixed $value + * @param string $name Name + * @param mixed $value Value + * * @return mixed */ function __set($name, $value) { @@ -284,6 +314,7 @@ abstract class ElggEntity implements * @tip Use isset($entity->property) * * @param string $name The name of the attribute or metadata. + * * @return bool */ function __isset($name) { @@ -296,12 +327,13 @@ abstract class ElggEntity implements * @warning If you use this to unset an attribute, you must save the object! * * @param string $name The name of the attribute or metadata. + * + * @return void */ function __unset($name) { if (array_key_exists($name, $this->attributes)) { $this->attributes[$name] = ""; - } - else { + } else { $this->clearMetaData($name); } } @@ -312,10 +344,12 @@ abstract class ElggEntity implements * @tip Plugin authors should use the magic methods. * * @access private - * @param string $name Name of the metadata - * @param mixed $value Value of the metadata + * + * @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 (does not support associative arrays) + * @param bool $multiple Allow multiple values for a single name (doesn't support assoc arrays) + * * @return bool */ public function setMetaData($name, $value, $value_type = "", $multiple = false) { @@ -338,8 +372,7 @@ abstract class ElggEntity implements } $this->temp_metadata[$name][] = $value; - } - else { + } else { $this->temp_metadata[$name] = $value; } } @@ -349,7 +382,8 @@ abstract class ElggEntity implements } else { unset($this->temp_metadata[$name]); if ((int) $this->guid > 0) { - $result = create_metadata($this->getGUID(), $name, $value, $value_type, $this->getOwner(), $this->getAccessID(), $multiple); + $result = create_metadata($this->getGUID(), $name, $value, $value_type, + $this->getOwner(), $this->getAccessID(), $multiple); return (bool)$result; } else { if (($multiple) && (isset($this->temp_metadata[$name]))) { @@ -360,8 +394,7 @@ abstract class ElggEntity implements } $this->temp_metadata[$name][] = $value; - } - else { + } else { $this->temp_metadata[$name] = $value; } @@ -374,8 +407,10 @@ abstract class ElggEntity implements * Remove metadata * * @warning Calling this with no or empty arguments will clear all metadata on the entity. - * @param string The name of the metadata to clear - * @return mixed The n + * + * @param string $name The name of the metadata to clear + * + * @return mixed bool */ public function clearMetaData($name = "") { if (empty($name)) { @@ -390,6 +425,7 @@ abstract class ElggEntity implements * Get a piece of volatile (non-persisted) data on this entity. * * @param string $name The name of the volatile data + * * @return mixed The value or NULL if not found. */ public function getVolatileData($name) { @@ -408,8 +444,10 @@ abstract class ElggEntity implements /** * Set a piece of volatile (non-persisted) data on this entity * - * @param string $name - * @param mixed $value + * @param string $name Name + * @param mixed $value Value + * + * @return void */ public function setVolatileData($name, $value) { if (!is_array($this->volatile)) { @@ -439,8 +477,9 @@ abstract class ElggEntity implements * * @tip Read the relationship like "$guid is a $relationship of this entity." * - * @param int $guid Entity to link to. + * @param int $guid Entity to link to. * @param string $relationship The type of relationship. + * * @return bool * @see ElggEntity::removeRelationship() * @see ElggEntity::clearRelationships() @@ -452,8 +491,9 @@ abstract class ElggEntity implements /** * Remove a relationship * - * @param int $guid - * @param str $relationship + * @param int $guid GUID of the entity to make a relationship with + * @param str $relationship Name of relationship + * * @return bool * @see ElggEntity::addRelationship() * @see ElggEntity::clearRelationships() @@ -468,8 +508,9 @@ abstract class ElggEntity implements * Private settings are similar to metadata but will not * be searched and there are fewer helper functions for them. * - * @param $name - * @param $value + * @param string $name Name of private setting + * @param mixed $value Value of private setting + * * @return bool * @link http://docs.elgg.org/DataModel/Entities/PrivateSettings */ @@ -480,7 +521,8 @@ abstract class ElggEntity implements /** * Returns a private setting value * - * @param $name + * @param string $name Name of the private setting + * * @return mixed */ function getPrivateSetting($name) { @@ -490,7 +532,8 @@ abstract class ElggEntity implements /** * Removes private setting * - * @param $name + * @param string $name Name of the private setting + * * @return bool */ function removePrivateSetting($name) { @@ -502,11 +545,14 @@ abstract class ElggEntity implements * * @warning By default, annotations are private. * - * @param string $name - * @param mixed $value - * @param int $access_id - * @param int $owner_id - * @param string $vartype + * @param string $name Annotation name + * @param mixed $value Annotation value + * @param int $access_id Access ID + * @param int $owner_id GUID of the annotation owner + * @param string $vartype The type of annotation value + * + * @return bool + * * @link http://docs.elgg.org/DataModel/Annotations */ function annotate($name, $value, $access_id = ACCESS_PRIVATE, $owner_id = 0, $vartype = "") { @@ -521,13 +567,14 @@ abstract class ElggEntity implements /** * Returns an array of annotations. * - * @param string $name - * @param int $limit - * @param int $offset - * @param string $order asc or desc + * @param string $name Annotation name + * @param int $limit Limit + * @param int $offset Offset + * @param string $order asc or desc + * * @return array */ - function getAnnotations($name, $limit = 50, $offset = 0, $order="asc") { + function getAnnotations($name, $limit = 50, $offset = 0, $order = "asc") { if ((int) ($this->guid) > 0) { return get_annotations($this->getGUID(), "", "", $name, "", 0, $limit, $offset, $order); } else { @@ -538,9 +585,11 @@ abstract class ElggEntity implements /** * Remove an annotation or all annotations for this entity. * - * @warning Calling this method with no or an empty argument will remove all annotations on the entity. + * @warning Calling this method with no or an empty argument will remove + * all annotations on the entity. + * + * @param string $name Annotation name * - * @param string $name * @return bool */ function clearAnnotations($name = "") { @@ -551,6 +600,7 @@ abstract class ElggEntity implements * Count annotations. * * @param string $name The type of annotation. + * * @return int */ function countAnnotations($name = "") { @@ -560,7 +610,8 @@ abstract class ElggEntity implements /** * Get the average of an integer type annotation. * - * @param string $name + * @param string $name Annotation name + * * @return int */ function getAnnotationsAvg($name) { @@ -570,7 +621,8 @@ abstract class ElggEntity implements /** * Get the sum of integer type annotations of a given name. * - * @param string $name + * @param string $name Annotation name + * * @return int */ function getAnnotationsSum($name) { @@ -580,7 +632,8 @@ abstract class ElggEntity implements /** * Get the minimum of integer type annotations of given name. * - * @param string $name + * @param string $name Annotation name + * * @return int */ function getAnnotationsMin($name) { @@ -590,7 +643,8 @@ abstract class ElggEntity implements /** * Get the maximum of integer type annotations of a given name. * - * @param string $name + * @param string $name Annotation name + * * @return int */ function getAnnotationsMax($name) { @@ -601,9 +655,10 @@ abstract class ElggEntity implements * Gets an array of entities with a relationship to this entity. * * @param string $relationship Relationship type (eg "friends") - * @param true|false $inverse Is this an inverse relationship? - * @param int $limit Number of elements to return - * @param int $offset Indexing offset + * @param bool $inverse Is this an inverse relationship? + * @param int $limit Number of elements to return + * @param int $offset Indexing offset + * * @return array|false An array of entities or false on failure */ function getEntitiesFromRelationship($relationship, $inverse = false, $limit = 50, $offset = 0) { @@ -619,8 +674,9 @@ abstract class ElggEntity implements /** * Gets the number of of entities from a specific relationship type * - * @param string $relationship Relationship type (eg "friends") - * @param bool $inverse_relationship + * @param string $relationship Relationship type (eg "friends") + * @param bool $inverse_relationship Invert relationship + * * @return int|false The number of entities or false on failure */ function countEntitiesFromRelationship($relationship, $inverse_relationship = FALSE) { @@ -635,8 +691,9 @@ abstract class ElggEntity implements /** * Can a user edit this entity. * - * @param int $user_guid The user GUID, optionally (defaults to the currently logged in user) - * @return true|false + * @param int $user_guid The user GUID, optionally (default: logged in user) + * + * @return bool */ function canEdit($user_guid = 0) { return can_edit_entity($this->getGUID(), $user_guid); @@ -645,8 +702,9 @@ abstract class ElggEntity implements /** * Can a user edit metadata on this entity * - * @param ElggMetadata $metadata The piece of metadata to specifically check - * @param int $user_guid The user GUID, optionally (defaults to the currently logged in user) + * @param ElggMetadata $metadata The piece of metadata to specifically check + * @param int $user_guid The user GUID, optionally (default: logged in user) + * * @return true|false */ function canEditMetadata($metadata = null, $user_guid = 0) { @@ -657,6 +715,7 @@ abstract class ElggEntity implements * Can a user write to this entity's container. * * @param int $user_guid The user. + * * @return bool */ public function canWriteToContainer($user_guid = 0) { @@ -762,6 +821,7 @@ abstract class ElggEntity implements * @warning This override exists only for the life of the object. * * @param string $url The new item URL + * * @return string The URL */ public function setURL($url) { @@ -773,6 +833,7 @@ abstract class ElggEntity implements * Returns a URL for the entity's icon. * * @param string $size Either 'large', 'medium', 'small' or 'tiny' + * * @return string The url or false if no url could be worked out. * @see get_entity_icon_url() */ @@ -788,8 +849,9 @@ abstract class ElggEntity implements * * @warning This override exists only for the life of the object. * - * @param string $url The url of the icon. + * @param string $url The url of the icon. * @param string $size The size its for. + * * @return bool */ public function setIcon($url, $size = 'medium') { @@ -831,8 +893,13 @@ abstract class ElggEntity implements $this->get('container_guid') ); } else { - // Create a new entity (nb: using attribute array directly 'cos set function does something special!) - $this->attributes['guid'] = create_entity($this->attributes['type'], $this->attributes['subtype'], $this->attributes['owner_guid'], $this->attributes['access_id'], $this->attributes['site_guid'], $this->attributes['container_guid']); + // Create a new entity (nb: using attribute array directly + // 'cos set function does something special!) + $this->attributes['guid'] = create_entity($this->attributes['type'], + $this->attributes['subtype'], $this->attributes['owner_guid'], + $this->attributes['access_id'], $this->attributes['site_guid'], + $this->attributes['container_guid']); + if (!$this->attributes['guid']) { throw new IOException(elgg_echo('IOException:BaseEntitySaveFailed')); } @@ -840,7 +907,7 @@ abstract class ElggEntity implements // Save any unsaved metadata // @todo How to capture extra information (access id etc) if (sizeof($this->temp_metadata) > 0) { - foreach($this->temp_metadata as $name => $value) { + foreach ($this->temp_metadata as $name => $value) { $this->$name = $value; unset($this->temp_metadata[$name]); } @@ -849,14 +916,15 @@ abstract class ElggEntity implements // Save any unsaved annotations metadata. // @todo How to capture extra information (access id etc) if (sizeof($this->temp_annotations) > 0) { - foreach($this->temp_annotations as $name => $value) { + foreach ($this->temp_annotations as $name => $value) { $this->annotate($name, $value); unset($this->temp_annotations[$name]); } } // set the subtype to id now rather than a string - $this->attributes['subtype'] = get_subtype_id($this->attributes['type'], $this->attributes['subtype']); + $this->attributes['subtype'] = get_subtype_id($this->attributes['type'], + $this->attributes['subtype']); // Cache object handle if ($this->attributes['guid']) { @@ -870,7 +938,8 @@ abstract class ElggEntity implements /** * Loads attributes from the entities table into the object. * - * @param int $guid + * @param int $guid GUID of Entity + * * @return bool */ protected function load($guid) { @@ -884,7 +953,7 @@ abstract class ElggEntity implements // Now put these into the attributes array as core values $objarray = (array) $row; - foreach($objarray as $key => $value) { + foreach ($objarray as $key => $value) { $this->attributes[$key] = $value; } @@ -915,8 +984,9 @@ abstract class ElggEntity implements * * @internal Disabling an entity sets the 'enabled' column to 'no'. * - * @param string $reason Optional reason - * @param bool $recursive Recursively disable all contained entities? + * @param string $reason Optional reason + * @param bool $recursive Recursively disable all contained entities? + * * @return bool * @see enable_entity() * @see ElggEntity::enable() @@ -977,7 +1047,9 @@ abstract class ElggEntity implements * Sets the 'location' metadata for the entity * * @todo Unimplemented - * @param string $location + * + * @param string $location String representation of the location + * * @return true */ public function setLocation($location) { @@ -991,8 +1063,9 @@ abstract class ElggEntity implements /** * Set latitude and longitude metadata tags for a given entity. * - * @param float $lat - * @param float $long + * @param float $lat Latitude + * @param float $long Longitude + * * @return true * @todo Unimplemented */ @@ -1041,21 +1114,24 @@ abstract class ElggEntity implements /** * Set the time and duration of an object * - * @param int $hour If ommitted, now is assumed. - * @param int $minute If ommitted, now is assumed. - * @param int $second If ommitted, now is assumed. - * @param int $day If ommitted, now is assumed. - * @param int $month If ommitted, now is assumed. - * @param int $year If ommitted, now is assumed. + * @param int $hour If ommitted, now is assumed. + * @param int $minute If ommitted, now is assumed. + * @param int $second If ommitted, now is assumed. + * @param int $day If ommitted, now is assumed. + * @param int $month If ommitted, now is assumed. + * @param int $year If ommitted, now is assumed. * @param int $duration Duration of event, remainder of the day is assumed. + * * @return true * @todo Unimplemented */ - public function setCalendarTimeAndDuration($hour = NULL, $minute = NULL, $second = NULL, $day = NULL, $month = NULL, $year = NULL, $duration = NULL) { + public function setCalendarTimeAndDuration($hour = NULL, $minute = NULL, $second = NULL, + $day = NULL, $month = NULL, $year = NULL, $duration = NULL) { + $start = mktime($hour, $minute, $second, $month, $day, $year); $end = $start + abs($duration); if (!$duration) { - $end = get_day_end($day,$month,$year); + $end = get_day_end($day, $month, $year); } $this->calendar_start = $start; @@ -1078,6 +1154,8 @@ abstract class ElggEntity implements * Returns the end timestamp. * * @todo Unimplemented + * + * @return int */ public function getCalendarEndTime() { return (int)$this->calendar_end; @@ -1107,7 +1185,8 @@ abstract class ElggEntity implements /** * Export this class into an array of ODD Elements containing all necessary fields. - * Override if you wish to return more information than can be found in $this->attributes (shouldn't happen) + * Override if you wish to return more information than can be found in + * $this->attributes (shouldn't happen) * * @return array */ @@ -1167,7 +1246,7 @@ abstract class ElggEntity implements // set the time of any metadata created if ($meta) { - $meta->setAttribute('published', date("r",$this->time_created)); + $meta->setAttribute('published', date("r", $this->time_created)); $tmp[] = $meta; } } @@ -1182,7 +1261,8 @@ abstract class ElggEntity implements $view = elgg_view_entity($this, true); elgg_set_viewtype(); - $tmp[] = new ODDMetaData($uuid . "volatile/renderedentity/", $uuid, 'renderedentity', $view , 'volatile'); + $tmp[] = new ODDMetaData($uuid . "volatile/renderedentity/", $uuid, + 'renderedentity', $view, 'volatile'); return $tmp; } @@ -1194,8 +1274,8 @@ abstract class ElggEntity implements /** * Import data from an parsed ODD xml data array. * - * @param array $data - * @param int $version + * @param array $data XML data + * * @return true */ public function import(ODD $data) { @@ -1233,6 +1313,8 @@ abstract class ElggEntity implements /** * Return the class name of the object. + * + * @return string */ public function getClassName() { return get_class($this); @@ -1243,7 +1325,13 @@ abstract class ElggEntity implements * This is used by the river functionality primarily. * * This is useful for checking access permissions etc on objects. - * @return guid + * + * @param int $id GUID. + * + * @todo How is this any different or more useful than get_entity($guid) + * or new ElggEntity($guid)? + * + * @return int GUID */ public function getObjectFromID($id) { return get_entity($id); @@ -1264,6 +1352,7 @@ abstract class ElggEntity implements * @warning Tags must be registered by {@link elgg_register_tag_metadata_name()}. * * @param array $tag_names Optionally restrict by tag metadata names. + * * @return array */ public function getTags($tag_names = NULL) { @@ -1305,22 +1394,57 @@ abstract class ElggEntity implements */ private $valid = FALSE; + /** + * Iterator interface + * + * @see Iterator::rewind() + * + * @return void + */ function rewind() { $this->valid = (FALSE !== reset($this->attributes)); } + /** + * Iterator interface + * + * @see Iterator::current() + * + * @return void + */ function current() { return current($this->attributes); } + /** + * Iterator interface + * + * @see Iterator::key() + * + * @return void + */ function key() { return key($this->attributes); } + /** + * Iterator interface + * + * @see Iterator::next() + * + * @return void + */ function next() { $this->valid = (FALSE !== next($this->attributes)); } + /** + * Iterator interface + * + * @see Iterator::valid() + * + * @return void + */ function valid() { return $this->valid; } @@ -1333,24 +1457,63 @@ abstract class ElggEntity implements * This lets an entity's attributes be accessed like an associative array. * Example: http://www.sitepoint.com/print/php5-standard-library */ + + /** + * Array access interface + * + * @see ArrayAccess::offsetSet() + * + * @param mixed $key Name + * @param mixed $value Value + * + * @return void + */ function offsetSet($key, $value) { - if ( array_key_exists($key, $this->attributes) ) { + if (array_key_exists($key, $this->attributes)) { $this->attributes[$key] = $value; } } + /** + * Array access interface + * + * @see ArrayAccess::offsetGet() + * + * @param mixed $key Name + * + * @return void + */ function offsetGet($key) { - if ( array_key_exists($key, $this->attributes) ) { + if (array_key_exists($key, $this->attributes)) { return $this->attributes[$key]; } } + /** + * Array access interface + * + * @see ArrayAccess::offsetUnset() + * + * @param mixed $key Name + * + * @return void + */ function offsetUnset($key) { - if ( array_key_exists($key, $this->attributes) ) { - $this->attributes[$key] = ""; // Full unsetting is dangerious for our objects + if (array_key_exists($key, $this->attributes)) { + // Full unsetting is dangerous for our objects + $this->attributes[$key] = ""; } } + /** + * Array access interface + * + * @see ArrayAccess::offsetExists() + * + * @param int $offset Offset + * + * @return int + */ function offsetExists($offset) { return array_key_exists($offset, $this->attributes); } diff --git a/engine/classes/ElggExtender.php b/engine/classes/ElggExtender.php index 577207c06..cfc8fbf68 100644 --- a/engine/classes/ElggExtender.php +++ b/engine/classes/ElggExtender.php @@ -11,11 +11,11 @@ * @tip Plugin authors would probably want to extend either ElggAnnotation * or ElggMetadata instead of this class. * - * @package Elgg.Core + * @package Elgg.Core * @subpackage DataModel.Extender - * @see ElggAnnotation - * @see ElggMetadata - * @link http://docs.elgg.org/DataModel/Extenders + * @link http://docs.elgg.org/DataModel/Extenders + * @see ElggAnnotation + * @see ElggMetadata */ abstract class ElggExtender implements Exportable, @@ -33,24 +33,31 @@ abstract class ElggExtender implements /** * Returns an attribute * - * @param string $name + * @param string $name Name + * * @return mixed */ protected function get($name) { if (isset($this->attributes[$name])) { // Sanitise value if necessary - if ($name=='value') { + if ($name == 'value') { switch ($this->attributes['value_type']) { case 'integer' : return (int)$this->attributes['value']; + break; //case 'tag' : //case 'file' : case 'text' : return ($this->attributes['value']); + break; default : - throw new InstallationException(sprintf(elgg_echo('InstallationException:TypeNotSupported'), $this->attributes['value_type'])); + $msg = sprintf(elgg_echo('InstallationException:TypeNotSupported'), + $this->attributes['value_type']); + + throw new InstallationException($msg); + break; } } @@ -62,9 +69,10 @@ abstract class ElggExtender implements /** * Set an attribute * - * @param string $name - * @param mixed $value - * @param string $value_type + * @param string $name Name + * @param mixed $value Value + * @param string $value_type Value type + * * @return boolean */ protected function set($name, $value, $value_type = "") { @@ -106,11 +114,15 @@ abstract class ElggExtender implements /** * Save this data to the appropriate database table. + * + * @return bool */ abstract public function save(); /** * Delete this data. + * + * @return bool */ abstract public function delete(); @@ -118,10 +130,11 @@ abstract class ElggExtender implements * Returns if a user can edit this extended data. * * @param int $user_guid The GUID of the user (defaults to currently logged in user) + * * @return bool */ public function canEdit($user_guid = 0) { - return can_edit_extender($this->id,$this->type,$user_guid); + return can_edit_extender($this->id, $this->type, $user_guid); } /** @@ -160,7 +173,8 @@ abstract class ElggExtender implements public function export() { $uuid = get_uuid_from_object($this); - $meta = new ODDMetadata($uuid, guid_to_uuid($this->entity_guid), $this->attributes['name'], $this->attributes['value'], $this->attributes['type'], guid_to_uuid($this->owner_guid)); + $meta = new ODDMetadata($uuid, guid_to_uuid($this->entity_guid), $this->attributes['name'], + $this->attributes['value'], $this->attributes['type'], guid_to_uuid($this->owner_guid)); $meta->setAttribute('published', date("r", $this->time_created)); return $meta; @@ -228,22 +242,57 @@ abstract class ElggExtender implements */ private $valid = FALSE; + /** + * Iterator interface + * + * @see Iterator::rewind() + * + * @return void + */ function rewind() { $this->valid = (FALSE !== reset($this->attributes)); } + /** + * Iterator interface + * + * @see Iterator::current() + * + * @return void + */ function current() { return current($this->attributes); } + /** + * Iterator interface + * + * @see Iterator::key() + * + * @return void + */ function key() { return key($this->attributes); } + /** + * Iterator interface + * + * @see Iterator::next() + * + * @return void + */ function next() { $this->valid = (FALSE !== next($this->attributes)); } + /** + * Iterator interface + * + * @see Iterator::valid() + * + * @return void + */ function valid() { return $this->valid; } @@ -256,25 +305,63 @@ abstract class ElggExtender implements * This lets an entity's attributes be accessed like an associative array. * Example: http://www.sitepoint.com/print/php5-standard-library */ + + /** + * Array access interface + * + * @see ArrayAccess::offsetSet() + * + * @param mixed $key Name + * @param mixed $value Value + * + * @return void + */ function offsetSet($key, $value) { - if ( array_key_exists($key, $this->attributes) ) { + if (array_key_exists($key, $this->attributes)) { $this->attributes[$key] = $value; } } + /** + * Array access interface + * + * @see ArrayAccess::offsetGet() + * + * @param mixed $key Name + * + * @return void + */ function offsetGet($key) { - if ( array_key_exists($key, $this->attributes) ) { + if (array_key_exists($key, $this->attributes)) { return $this->attributes[$key]; } } + /** + * Array access interface + * + * @see ArrayAccess::offsetUnset() + * + * @param mixed $key Name + * + * @return void + */ function offsetUnset($key) { - if ( array_key_exists($key, $this->attributes) ) { + if (array_key_exists($key, $this->attributes)) { // Full unsetting is dangerious for our objects $this->attributes[$key] = ""; } } + /** + * Array access interface + * + * @see ArrayAccess::offsetExists() + * + * @param int $offset Offset + * + * @return int + */ function offsetExists($offset) { return array_key_exists($offset, $this->attributes); } diff --git a/engine/classes/ElggFile.php b/engine/classes/ElggFile.php index a1bc81118..bf6732ca4 100644 --- a/engine/classes/ElggFile.php +++ b/engine/classes/ElggFile.php @@ -1,20 +1,24 @@ <?php /** - * @class ElggFile * This class represents a physical file. * - * Usage: - * Create a new ElggFile object and specify a filename, and optionally a FileStore (if one isn't specified - * then the default is assumed. + * Create a new ElggFile object and specify a filename, and optionally a + * FileStore (if one isn't specified then the default is assumed.) * - * Open the file using the appropriate mode, and you will be able to read and write to the file. + * Open the file using the appropriate mode, and you will be able to + * read and write to the file. * - * Optionally, you can also call the file's save() method, this will turn the file into an entity in the - * system and permit you to do things like attach tags to the file etc. This is not done automatically since - * there are many occasions where you may want access to file data on datastores using the ElggFile interface - * but do not want to create an Entity reference to it in the system (temporary files for example). + * Optionally, you can also call the file's save() method, this will + * turn the file into an entity in the system and permit you to do + * things like attach tags to the file etc. This is not done automatically + * since there are many occasions where you may want access to file data + * on datastores using the ElggFile interface but do not want to create + * an Entity reference to it in the system (temporary files for example). * + * @class ElggFile + * @package Elgg.Core + * @subpackage DataModel.File */ class ElggFile extends ElggObject { /** Filestore */ @@ -23,12 +27,33 @@ class ElggFile extends ElggObject { /** File handle used to identify this file in a filestore. Created by open. */ private $handle; + /** + * Set subtype to 'file'. + * + * @return void + * + * @deprecated 1.8 Use initializeAttributes() + */ protected function initialise_attributes() { - parent::initialise_attributes(); + elgg_deprecated_notice('ElggFile::initialise_attributes() is deprecated by ::initializeAttributes()', 1.8); + } + + /** + * Set subtype to 'file'. + * + * @return void + */ + protected function initializeAttributes() { + parent::initializeAttributes(); $this->attributes['subtype'] = "file"; } + /** + * Loads an ElggFile entity. + * + * @param int $guid GUID of the ElggFile object + */ public function __construct($guid = null) { parent::__construct($guid); @@ -40,6 +65,8 @@ class ElggFile extends ElggObject { * Set the filename of this file. * * @param string $name The filename. + * + * @return void */ public function setFilename($name) { $this->filename = $name; @@ -47,33 +74,43 @@ class ElggFile extends ElggObject { /** * Return the filename. + * + * @return string */ public function getFilename() { return $this->filename; } /** - * Return the filename of this file as it is/will be stored on the filestore, which may be different - * to the filename. + * Return the filename of this file as it is/will be stored on the + * filestore, which may be different to the filename. + * + * @return string */ public function getFilenameOnFilestore() { return $this->filestore->getFilenameOnFilestore($this); } - /* + /** * Return the size of the filestore associated with this file * + * @param string $prefix Storage prefix + * @param int $container_guid The container GUID of the checked filestore + * + * @return int */ - public function getFilestoreSize($prefix='',$container_guid=0) { + public function getFilestoreSize($prefix = '', $container_guid = 0) { if (!$container_guid) { $container_guid = $this->container_guid; } $fs = $this->getFilestore(); - return $fs->getSize($prefix,$container_guid); + return $fs->getSize($prefix, $container_guid); } /** * Get the mime type of the file. + * + * @return string */ public function getMimeType() { if ($this->mimetype) { @@ -86,7 +123,9 @@ class ElggFile extends ElggObject { /** * Set the mime type of the file. * - * @param $mimetype The mimetype + * @param string $mimetype The mimetype + * + * @return bool */ public function setMimeType($mimetype) { return $this->mimetype = $mimetype; @@ -96,6 +135,8 @@ class ElggFile extends ElggObject { * Set the optional file description. * * @param string $description The description. + * + * @return bool */ public function setDescription($description) { $this->description = $description; @@ -105,6 +146,8 @@ class ElggFile extends ElggObject { * Open the file with the given mode * * @param string $mode Either read/write/append + * + * @return resource File handler */ public function open($mode) { if (!$this->getFilename()) { @@ -116,11 +159,12 @@ class ElggFile extends ElggObject { // Sanity check if ( - ($mode!="read") && - ($mode!="write") && - ($mode!="append") + ($mode != "read") && + ($mode != "write") && + ($mode != "append") ) { - throw new InvalidParameterException(sprintf(elgg_echo('InvalidParameterException:UnrecognisedFileMode'), $mode)); + $msg = sprintf(elgg_echo('InvalidParameterException:UnrecognisedFileMode'), $mode); + throw new InvalidParameterException($msg); } // Get the filestore @@ -136,9 +180,11 @@ class ElggFile extends ElggObject { } /** - * Write some data. + * Write data. * * @param string $data The data + * + * @return bool */ public function write($data) { $fs = $this->getFilestore(); @@ -147,10 +193,12 @@ class ElggFile extends ElggObject { } /** - * Read some data. + * Read data. * * @param int $length Amount to read. * @param int $offset The offset to start from. + * + * @return mixed Data or false */ public function read($length, $offset = 0) { $fs = $this->getFilestore(); @@ -170,6 +218,8 @@ class ElggFile extends ElggObject { /** * Close the file and commit changes + * + * @return bool */ public function close() { $fs = $this->getFilestore(); @@ -185,6 +235,8 @@ class ElggFile extends ElggObject { /** * Delete this file. + * + * @return bool */ public function delete() { $fs = $this->getFilestore(); @@ -196,7 +248,9 @@ class ElggFile extends ElggObject { /** * Seek a position in the file. * - * @param int $position + * @param int $position Position in bytes + * + * @return bool */ public function seek($position) { $fs = $this->getFilestore(); @@ -217,6 +271,8 @@ class ElggFile extends ElggObject { /** * Return the size of the file in bytes. + * + * @return int */ public function size() { return $this->filestore->getFileSize($this); @@ -224,6 +280,8 @@ class ElggFile extends ElggObject { /** * Return a boolean value whether the file handle is at the end of the file + * + * @return bool */ public function eof() { $fs = $this->getFilestore(); @@ -231,6 +289,11 @@ class ElggFile extends ElggObject { return $fs->eof($this->handle); } + /** + * Returns if the file exists + * + * @return bool + */ public function exists() { $fs = $this->getFilestore(); @@ -241,6 +304,8 @@ class ElggFile extends ElggObject { * Set a filestore. * * @param ElggFilestore $filestore The file store. + * + * @return void */ public function setFilestore(ElggFilestore $filestore) { $this->filestore = $filestore; @@ -250,6 +315,8 @@ class ElggFile extends ElggObject { * Return a filestore suitable for saving this file. * This filestore is either a pre-registered filestore, a filestore loaded from metatags saved * along side this file, or the system default. + * + * @return ElggFilestore */ protected function getFilestore() { // Short circuit if already set. @@ -263,7 +330,7 @@ class ElggFile extends ElggObject { $parameters = array(); if (is_array($metas)) { foreach ($metas as $meta) { - if (strpos($meta->name, "filestore::")!==false) { + if (strpos($meta->name, "filestore::") !== false) { // Filestore parameter tag $comp = explode("::", $meta->name); $name = $comp[1]; @@ -298,6 +365,16 @@ class ElggFile extends ElggObject { return $this->filestore; } + /** + * Save the file + * + * Write the file's data to the filestore and save + * the corresponding entity. + * + * @see ElggObject::save() + * + * @return bool + */ public function save() { if (!parent::save()) { return false; diff --git a/engine/classes/ElggFileCache.php b/engine/classes/ElggFileCache.php index f386b7466..2072af620 100644 --- a/engine/classes/ElggFileCache.php +++ b/engine/classes/ElggFileCache.php @@ -3,23 +3,23 @@ * ElggFileCache * Store cached data in a file store. * - * @package Elgg - * @subpackage API + * @package Elgg.Core + * @subpackage Caches */ class ElggFileCache extends ElggCache { /** * Set the Elgg cache. * * @param string $cache_path The cache path. - * @param int $max_age Maximum age in seconds, 0 if no limit. - * @param int $max_size Maximum size of cache in seconds, 0 if no limit. + * @param int $max_age Maximum age in seconds, 0 if no limit. + * @param int $max_size Maximum size of cache in seconds, 0 if no limit. */ function __construct($cache_path, $max_age = 0, $max_size = 0) { - $this->set_variable("cache_path", $cache_path); - $this->set_variable("max_age", $max_age); - $this->set_variable("max_size", $max_size); + $this->setVariable("cache_path", $cache_path); + $this->setVariable("max_age", $max_age); + $this->setVariable("max_size", $max_size); - if ($cache_path=="") { + if ($cache_path == "") { throw new ConfigurationException(elgg_echo('ConfigurationException:NoCachePath')); } } @@ -27,10 +27,28 @@ class ElggFileCache extends ElggCache { /** * Create and return a handle to a file. * - * @param string $filename - * @param string $rw + * @deprecated 1.8 Use ElggFileCache::createFile() + * + * @param string $filename Filename to save as + * @param string $rw Write mode + * + * @return mixed */ protected function create_file($filename, $rw = "rb") { + elgg_deprecated_notice('ElggFileCache::create_file() is deprecated by ::createFile()', 1.8); + + return $this->createFile($filename, $rw); + } + + /** + * Create and return a handle to a file. + * + * @param string $filename Filename to save as + * @param string $rw Write mode + * + * @return mixed + */ + protected function createFile($filename, $rw = "rb") { // Create a filename matrix $matrix = ""; $depth = strlen($filename); @@ -39,13 +57,13 @@ class ElggFileCache extends ElggCache { } // Create full path - $path = $this->get_variable("cache_path") . $matrix; + $path = $this->getVariable("cache_path") . $matrix; if (!is_dir($path)) { mkdir($path, 0700, true); } // Open the file - if ((!file_exists($path . $filename)) && ($rw=="rb")) { + if ((!file_exists($path . $filename)) && ($rw == "rb")) { return false; } @@ -55,7 +73,11 @@ class ElggFileCache extends ElggCache { /** * Create a sanitised filename for the file. * - * @param string $filename + * @deprecated 1.8 Use ElggFileCache::sanitizeFilename() + * + * @param string $filename The filename + * + * @return string */ protected function sanitise_filename($filename) { // @todo : Writeme @@ -64,14 +86,28 @@ class ElggFileCache extends ElggCache { } /** + * Create a sanitised filename for the file. + * + * @param string $filename The filename + * + * @return string + */ + protected function sanitizeFilename($filename) { + // @todo : Writeme + + return $filename; + } + + /** * Save a key * - * @param string $key - * @param string $data + * @param string $key Name + * @param string $data Value + * * @return boolean */ public function save($key, $data) { - $f = $this->create_file($this->sanitise_filename($key), "wb"); + $f = $this->createFile($this->sanitizeFilename($key), "wb"); if ($f) { $result = fwrite($f, $data); fclose($f); @@ -85,18 +121,19 @@ class ElggFileCache extends ElggCache { /** * Load a key * - * @param string $key - * @param int $offset - * @param int $limit + * @param string $key Name + * @param int $offset Offset + * @param int $limit Limit + * * @return string */ public function load($key, $offset = 0, $limit = null) { - $f = $this->create_file($this->sanitise_filename($key)); + $f = $this->createFile($this->sanitizeFilename($key)); if ($f) { - //fseek($f, $offset); if (!$limit) { $limit = -1; } + $data = stream_get_contents($f, $limit, $offset); fclose($f); @@ -110,29 +147,40 @@ class ElggFileCache extends ElggCache { /** * Invalidate a given key. * - * @param string $key + * @param string $key Name + * * @return bool */ public function delete($key) { - $dir = $this->get_variable("cache_path"); - - if (file_exists($dir.$key)) { - return unlink($dir.$key); + $dir = $this->getVariable("cache_path"); + + if (file_exists($dir . $key)) { + return unlink($dir . $key); } return TRUE; } + /** + * This was probably meant to delete everything? + * + * @return void + */ public function clear() { // @todo writeme } + /** + * Preform cleanup and invalidates cache upon object destruction + * + * @throws IOException + */ public function __destruct() { // @todo Check size and age, clean up accordingly $size = 0; - $dir = $this->get_variable("cache_path"); + $dir = $this->getVariable("cache_path"); // Short circuit if both size and age are unlimited - if (($this->get_variable("max_age")==0) && ($this->get_variable("max_size")==0)) { + if (($this->getVariable("max_age") == 0) && ($this->getVariable("max_size") == 0)) { return; } @@ -146,14 +194,14 @@ class ElggFileCache extends ElggCache { // Perform cleanup foreach ($files as $f) { if (!in_array($f, $exclude)) { - $stat = stat($dir.$f); + $stat = stat($dir . $f); // Add size $size .= $stat['size']; // Is this older than my maximum date? - if (($this->get_variable("max_age")>0) && (time() - $stat['mtime'] > $this->get_variable("max_age"))) { - unlink($dir.$f); + if (($this->getVariable("max_age") > 0) && (time() - $stat['mtime'] > $this->getVariable("max_age"))) { + unlink($dir . $f); } // @todo Size diff --git a/engine/classes/ElggFilestore.php b/engine/classes/ElggFilestore.php index 11775c9b8..61ce167d0 100644 --- a/engine/classes/ElggFilestore.php +++ b/engine/classes/ElggFilestore.php @@ -1,14 +1,18 @@ <?php /** - * @class ElggFilestore * This class defines the interface for all elgg data repositories. + * + * @package Elgg.Core + * @subpackage DataStorage + * @class ElggFilestore */ abstract class ElggFilestore { /** * Attempt to open the file $file for storage or writing. * - * @param ElggFile $file - * @param string $mode "read", "write", "append" + * @param ElggFile $file A file + * @param string $mode "read", "write", "append" + * * @return mixed A handle to the opened file or false on error. */ abstract public function open(ElggFile $file, $mode); @@ -16,8 +20,9 @@ abstract class ElggFilestore { /** * Write data to a given file handle. * - * @param mixed $f The file handle - exactly what this is depends on the file system + * @param mixed $f The file handle - exactly what this is depends on the file system * @param string $data The binary string of data to write + * * @return int Number of bytes written. */ abstract public function write($f, $data); @@ -25,9 +30,10 @@ abstract class ElggFilestore { /** * Read data from a filestore. * - * @param mixed $f The file handle - * @param int $length Length in bytes to read. - * @param int $offset The optional offset. + * @param mixed $f The file handle + * @param int $length Length in bytes to read. + * @param int $offset The optional offset. + * * @return mixed String of data or false on error. */ abstract public function read($f, $length, $offset = 0); @@ -35,8 +41,10 @@ abstract class ElggFilestore { /** * Seek a given position within a file handle. * - * @param mixed $f The file handle. - * @param int $position The position. + * @param mixed $f The file handle. + * @param int $position The position. + * + * @return void */ abstract public function seek($f, $position); @@ -44,6 +52,7 @@ abstract class ElggFilestore { * Return a whether the end of a file has been reached. * * @param mixed $f The file handle. + * * @return boolean */ abstract public function eof($f); @@ -52,6 +61,7 @@ abstract class ElggFilestore { * Return the current position in an open file. * * @param mixed $f The file handle. + * * @return int */ abstract public function tell($f); @@ -59,28 +69,36 @@ abstract class ElggFilestore { /** * Close a given file handle. * - * @param mixed $f + * @param mixed $f The file handle + * + * @return bool */ abstract public function close($f); /** * Delete the file associated with a given file handle. * - * @param ElggFile $file + * @param ElggFile $file The file + * + * @return bool */ abstract public function delete(ElggFile $file); /** * Return the size in bytes for a given file. * - * @param ElggFile $file + * @param ElggFile $file The file + * + * @return int */ abstract public function getFileSize(ElggFile $file); /** * Return the filename of a given file as stored on the filestore. * - * @param ElggFile $file + * @param ElggFile $file The file + * + * @return string */ abstract public function getFilenameOnFilestore(ElggFile $file); @@ -94,6 +112,10 @@ abstract class ElggFilestore { /** * Set the parameters from the associative array produced by $this->getParameters(). + * + * @param array $parameters A list of parameters + * + * @return bool */ abstract public function setParameters(array $parameters); @@ -101,6 +123,7 @@ abstract class ElggFilestore { * Get the contents of the whole file. * * @param mixed $file The file handle. + * * @return mixed The file contents. */ abstract public function grabFile(ElggFile $file); @@ -108,7 +131,9 @@ abstract class ElggFilestore { /** * Return whether a file physically exists or not. * - * @param ElggFile $file + * @param ElggFile $file The file + * + * @return bool */ abstract public function exists(ElggFile $file); }
\ No newline at end of file diff --git a/engine/classes/ElggGroup.php b/engine/classes/ElggGroup.php index 4dea2bcd6..8721f931b 100644 --- a/engine/classes/ElggGroup.php +++ b/engine/classes/ElggGroup.php @@ -1,13 +1,36 @@ <?php /** - * @class ElggGroup Class representing a container for other elgg entities. + * Class representing a container for other elgg entities. + * + * @package Elgg.Core + * @subpackage Groups */ class ElggGroup extends ElggEntity implements Friendable { + + /** + * Sets the type to group. + * + * @return void + * + * @see ElggEntity::initialise_attributes() + */ protected function initialise_attributes() { - parent::initialise_attributes(); + elgg_deprecated_notice('ElggGroup::initialise_attributes() is deprecated by ::initializeAttributes()', 1.8); + return $this->initializeAttributes(); + } + + /** + * Sets the type to group. + * + * @return void + * + * @see ElggEntity::initialise_attributes() + */ + protected function initializeAttributes() { + parent::initializeAttributes(); $this->attributes['type'] = "group"; $this->attributes['name'] = ""; @@ -20,6 +43,7 @@ class ElggGroup extends ElggEntity * * @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 user. */ function __construct($guid = null) { @@ -30,29 +54,28 @@ class ElggGroup extends ElggEntity if ($guid instanceof stdClass) { // Load the rest if (!$this->load($guid->guid)) { - throw new IOException(sprintf(elgg_echo('IOException:FailedToLoadGUID'), get_class(), $guid->guid)); + $msg = sprintf(elgg_echo('IOException:FailedToLoadGUID'), get_class(), $guid->guid); + throw new IOException($msg); } - } - // Is $guid is an ElggGroup? Use a copy constructor - else if ($guid instanceof ElggGroup) { + + // Is $guid is an ElggGroup? Use a copy constructor + } else if ($guid instanceof ElggGroup) { elgg_deprecated_notice('This type of usage of the ElggGroup constructor was deprecated. Please use the clone method.', 1.7); foreach ($guid->attributes as $key => $value) { $this->attributes[$key] = $value; } - } - // Is this is an ElggEntity but not an ElggGroup = ERROR! - else if ($guid instanceof ElggEntity) { + + // Is this is an ElggEntity but not an ElggGroup = ERROR! + } else if ($guid instanceof ElggEntity) { throw new InvalidParameterException(elgg_echo('InvalidParameterException:NonElggGroup')); - } - // We assume if we have got this far, $guid is an int - else if (is_numeric($guid)) { + + // We assume if we have got this far, $guid is an int + } else if (is_numeric($guid)) { if (!$this->load($guid)) { throw new IOException(sprintf(elgg_echo('IOException:FailedToLoadGUID'), get_class(), $guid)); } - } - - else { + } else { throw new InvalidParameterException(elgg_echo('InvalidParameterException:UnrecognisedValue')); } } @@ -62,6 +85,7 @@ class ElggGroup extends ElggEntity * Add an ElggObject to this group. * * @param ElggObject $object The object. + * * @return bool */ public function addObjectToGroup(ElggObject $object) { @@ -72,12 +96,22 @@ class ElggGroup extends ElggEntity * Remove an object from the containing group. * * @param int $guid The guid of the object. + * * @return bool */ public function removeObjectFromGroup($guid) { return remove_object_from_group($this->getGUID(), $guid); } + /** + * Returns an attribute or metadata. + * + * @see ElggEntity::get() + * + * @param string $name Name + * + * @return mixed + */ public function get($name) { if ($name == 'username') { return 'group:' . $this->getGUID(); @@ -85,23 +119,29 @@ class ElggGroup extends ElggEntity return parent::get($name); } -/** - * Start friendable compatibility block: - * - * public function addFriend($friend_guid); - public function removeFriend($friend_guid); - public function isFriend(); - public function isFriendsWith($user_guid); - public function isFriendOf($user_guid); - public function getFriends($subtype = "", $limit = 10, $offset = 0); - public function getFriendsOf($subtype = "", $limit = 10, $offset = 0); - public function getObjects($subtype="", $limit = 10, $offset = 0); - public function getFriendsObjects($subtype = "", $limit = 10, $offset = 0); - public function countObjects($subtype = ""); - */ + /** + * Start friendable compatibility block: + * + * public function addFriend($friend_guid); + public function removeFriend($friend_guid); + public function isFriend(); + public function isFriendsWith($user_guid); + public function isFriendOf($user_guid); + public function getFriends($subtype = "", $limit = 10, $offset = 0); + public function getFriendsOf($subtype = "", $limit = 10, $offset = 0); + public function getObjects($subtype="", $limit = 10, $offset = 0); + public function getFriendsObjects($subtype = "", $limit = 10, $offset = 0); + public function countObjects($subtype = ""); + */ /** - * For compatibility with Friendable + * For compatibility with Friendable. + * + * Join a group when you friend ElggGroup. + * + * @param int $friend_guid The GUID of the user joining the group. + * + * @return bool */ public function addFriend($friend_guid) { return $this->join(get_entity($friend_guid)); @@ -109,6 +149,12 @@ class ElggGroup extends ElggEntity /** * For compatibility with Friendable + * + * Leave group when you unfriend ElggGroup. + * + * @param int $friend_guid The GUID of the user leaving. + * + * @return bool */ public function removeFriend($friend_guid) { return $this->leave(get_entity($friend_guid)); @@ -116,6 +162,10 @@ class ElggGroup extends ElggEntity /** * For compatibility with Friendable + * + * Friending a group adds you as a member + * + * @return bool */ public function isFriend() { return $this->isMember(); @@ -123,6 +173,10 @@ class ElggGroup extends ElggEntity /** * For compatibility with Friendable + * + * @param int $user_guid The GUID of a user to check. + * + * @return bool */ public function isFriendsWith($user_guid) { return $this->isMember($user_guid); @@ -130,6 +184,10 @@ class ElggGroup extends ElggEntity /** * For compatibility with Friendable + * + * @param int $user_guid The GUID of a user to check. + * + * @return bool */ public function isFriendOf($user_guid) { return $this->isMember($user_guid); @@ -137,6 +195,12 @@ class ElggGroup extends ElggEntity /** * For compatibility with Friendable + * + * @param string $subtype The GUID of a user to check. + * @param int $limit Limit + * @param int $offset Offset + * + * @return bool */ public function getFriends($subtype = "", $limit = 10, $offset = 0) { return get_group_members($this->getGUID(), $limit, $offset); @@ -144,6 +208,12 @@ class ElggGroup extends ElggEntity /** * For compatibility with Friendable + * + * @param string $subtype The GUID of a user to check. + * @param int $limit Limit + * @param int $offset Offset + * + * @return bool */ public function getFriendsOf($subtype = "", $limit = 10, $offset = 0) { return get_group_members($this->getGUID(), $limit, $offset); @@ -152,17 +222,24 @@ class ElggGroup extends ElggEntity /** * Get objects contained in this group. * - * @param string $subtype - * @param int $limit - * @param int $offset - * @return mixed + * @param string $subtype Entity subtype + * @param int $limit Limit + * @param int $offset Offset + * + * @return array|false */ - public function getObjects($subtype="", $limit = 10, $offset = 0) { + public function getObjects($subtype = "", $limit = 10, $offset = 0) { return get_objects_in_group($this->getGUID(), $subtype, 0, 0, "", $limit, $offset, false); } /** * For compatibility with Friendable + * + * @param string $subtype Entity subtype + * @param int $limit Limit + * @param int $offset Offset + * + * @return array|false */ public function getFriendsObjects($subtype = "", $limit = 10, $offset = 0) { return get_objects_in_group($this->getGUID(), $subtype, 0, 0, "", $limit, $offset, false); @@ -170,28 +247,35 @@ class ElggGroup extends ElggEntity /** * For compatibility with Friendable + * + * @param string $subtype Subtype of entities + * + * @return array|false */ public function countObjects($subtype = "") { return get_objects_in_group($this->getGUID(), $subtype, 0, 0, "", 10, 0, true); } -/** - * End friendable compatibility block - */ + /** + * End friendable compatibility block + */ /** * Get a list of group members. * - * @param int $limit - * @param int $offset + * @param int $limit Limit + * @param int $offset Offset + * @param bool $count Count + * * @return mixed */ public function getMembers($limit = 10, $offset = 0, $count = false) { - return get_group_members($this->getGUID(), $limit, $offset, 0 , $count); + return get_group_members($this->getGUID(), $limit, $offset, 0, $count); } /** * Returns whether the current group is public membership or not. + * * @return bool */ public function isPublicMembership() { @@ -206,6 +290,7 @@ class ElggGroup extends ElggEntity * Return whether a given user is a member of this group or not. * * @param ElggUser $user The user + * * @return bool */ public function isMember($user = 0) { @@ -221,7 +306,8 @@ class ElggGroup extends ElggEntity /** * Join an elgg user to this group. * - * @param ElggUser $user + * @param ElggUser $user User + * * @return bool */ public function join(ElggUser $user) { @@ -231,7 +317,9 @@ class ElggGroup extends ElggEntity /** * Remove a user from the group. * - * @param ElggUser $user + * @param ElggUser $user User + * + * @return void */ public function leave(ElggUser $user) { return leave_group($this->getGUID(), $user->getGUID()); @@ -242,7 +330,9 @@ class ElggGroup extends ElggEntity * This function will ensure that all data is loaded (were possible), so * if only part of the ElggGroup is loaded, it'll load the rest. * - * @param int $guid + * @param int $guid GUID of an ElggGroup entity + * + * @return true */ protected function load($guid) { // Test to see if we have the generic stuff @@ -251,8 +341,9 @@ class ElggGroup extends ElggEntity } // Check the type - if ($this->attributes['type']!='group') { - throw new InvalidClassException(sprintf(elgg_echo('InvalidClassException:NotValidElggStar'), $guid, get_class())); + if ($this->attributes['type'] != 'group') { + $msg = sprintf(elgg_echo('InvalidClassException:NotValidElggStar'), $guid, get_class()); + throw new InvalidClassException($msg); } // Load missing data @@ -264,7 +355,7 @@ class ElggGroup extends ElggEntity // Now put these into the attributes array as core values $objarray = (array) $row; - foreach($objarray as $key => $value) { + foreach ($objarray as $key => $value) { $this->attributes[$key] = $value; } @@ -273,6 +364,8 @@ class ElggGroup extends ElggEntity /** * Override the save function. + * + * @return bool */ public function save() { // Save generic stuff @@ -288,6 +381,8 @@ class ElggGroup extends ElggEntity /** * Return an array of fields which can be exported. + * + * @return array */ public function getExportableValues() { return array_merge(parent::getExportableValues(), array( diff --git a/engine/classes/ElggHMACCache.php b/engine/classes/ElggHMACCache.php index 551e798f5..8d994d013 100644 --- a/engine/classes/ElggHMACCache.php +++ b/engine/classes/ElggHMACCache.php @@ -3,8 +3,8 @@ * ElggHMACCache * Store cached data in a temporary database, only used by the HMAC stuff. * - * @package Elgg - * @subpackage API + * @package Elgg.Core + * @subpackage HMAC */ class ElggHMACCache extends ElggCache { /** @@ -13,14 +13,15 @@ class ElggHMACCache extends ElggCache { * @param int $max_age Maximum age in seconds, 0 if no limit. */ function __construct($max_age = 0) { - $this->set_variable("max_age", $max_age); + $this->setVariable("max_age", $max_age); } /** * Save a key * - * @param string $key - * @param string $data + * @param string $key Name + * @param string $data Value + * * @return boolean */ public function save($key, $data) { @@ -29,15 +30,17 @@ class ElggHMACCache extends ElggCache { $key = sanitise_string($key); $time = time(); - return insert_data("INSERT into {$CONFIG->dbprefix}hmac_cache (hmac, ts) VALUES ('$key', '$time')"); + $query = "INSERT into {$CONFIG->dbprefix}hmac_cache (hmac, ts) VALUES ('$key', '$time')"; + return insert_data($query); } /** * Load a key * - * @param string $key - * @param int $offset - * @param int $limit + * @param string $key Name + * @param int $offset Offset + * @param int $limit Limit + * * @return string */ public function load($key, $offset = 0, $limit = null) { @@ -56,7 +59,8 @@ class ElggHMACCache extends ElggCache { /** * Invalidate a given key. * - * @param string $key + * @param string $key Name + * * @return bool */ public function delete($key) { @@ -71,6 +75,8 @@ class ElggHMACCache extends ElggCache { * Clear out all the contents of the cache. * * Not currently implemented in this cache type. + * + * @return true */ public function clear() { return true; @@ -84,9 +90,9 @@ class ElggHMACCache extends ElggCache { global $CONFIG; $time = time(); - $age = (int)$this->get_variable("max_age"); + $age = (int)$this->getVariable("max_age"); - $expires = $time-$age; + $expires = $time - $age; delete_data("DELETE from {$CONFIG->dbprefix}hmac_cache where ts<$expires"); } diff --git a/engine/classes/ElggMemcache.php b/engine/classes/ElggMemcache.php index 070100586..e0d8e7bee 100644 --- a/engine/classes/ElggMemcache.php +++ b/engine/classes/ElggMemcache.php @@ -1,6 +1,9 @@ <?php /** * Memcache wrapper class. + * + * @package Elgg.Core + * @subpackage Memcache */ class ElggMemcache extends ElggSharedMemoryCache { /** @@ -27,7 +30,8 @@ class ElggMemcache extends ElggSharedMemoryCache { /** * Connect to memcache. * - * @param string $cache_id The namespace for this cache to write to - note, namespaces of the same name are shared! + * @param string $namespace The namespace for this cache to write to - + * note, namespaces of the same name are shared! */ function __construct($namespace = 'default') { global $CONFIG; @@ -81,7 +85,12 @@ class ElggMemcache extends ElggSharedMemoryCache { // Get version $this->version = $this->memcache->getVersion(); if (version_compare($this->version, ElggMemcache::$MINSERVERVERSION, '<')) { - throw new ConfigurationException(sprintf(elgg_echo('memcache:versiontoolow'), ElggMemcache::$MINSERVERVERSION, $this->version)); + $msg = sprintf(elgg_echo('memcache:versiontoolow'), + ElggMemcache::$MINSERVERVERSION, + $this->version + ); + + throw new ConfigurationException($msg); } // Set some defaults @@ -94,6 +103,8 @@ class ElggMemcache extends ElggSharedMemoryCache { * Set the default expiry. * * @param int $expires The lifetime as a unix timestamp or time from now. Defaults forever. + * + * @return void */ public function setDefaultExpiry($expires = 0) { $this->expires = $expires; @@ -103,21 +114,46 @@ class ElggMemcache extends ElggSharedMemoryCache { * Combine a key with the namespace. * Memcache can only accept <250 char key. If the given key is too long it is shortened. * + * @deprecated 1.8 Use ElggMemcache::_makeMemcacheKey() + * * @param string $key The key + * * @return string The new key. */ private function make_memcache_key($key) { + elgg_deprecated_notice('ElggMemcache::make_memcache_key() is deprecated by ::_makeMemcacheKey()', 1.8); + + return $this->_makeMemcacheKey($key); + } + + /** + * Combine a key with the namespace. + * Memcache can only accept <250 char key. If the given key is too long it is shortened. + * + * @param string $key The key + * + * @return string The new key. + */ + private function _makeMemcacheKey($key) { $prefix = $this->getNamespace() . ":"; - if (strlen($prefix.$key)> 250) { + if (strlen($prefix . $key) > 250) { $key = md5($key); } - return $prefix.$key; + return $prefix . $key; } + /** + * Saves a name and value to the cache + * + * @param string $key Name + * @param string $data Value + * + * @return bool + */ public function save($key, $data) { - $key = $this->make_memcache_key($key); + $key = $this->_makeMemcacheKey($key); $result = $this->memcache->set($key, $data, null, $this->expires); if (!$result) { @@ -127,8 +163,17 @@ class ElggMemcache extends ElggSharedMemoryCache { return $result; } + /** + * Retrieves data. + * + * @param string $key Name of data to retrieve + * @param int $offset Offset + * @param int $limit Limit + * + * @return mixed + */ public function load($key, $offset = 0, $limit = null) { - $key = $this->make_memcache_key($key); + $key = $this->_makeMemcacheKey($key); $result = $this->memcache->get($key); if (!$result) { @@ -138,12 +183,26 @@ class ElggMemcache extends ElggSharedMemoryCache { return $result; } + /** + * Delete data + * + * @param string $key Name of data + * + * @return bool + */ public function delete($key) { - $key = $this->make_memcache_key($key); + $key = $this->_makeMemcacheKey($key); return $this->memcache->delete($key, 0); } + /** + * Clears the entire cache? + * + * @todo write or remove. + * + * @return true + */ public function clear() { // DISABLE clearing for now - you must use delete on a specific key. return true; diff --git a/engine/classes/ElggMetadata.php b/engine/classes/ElggMetadata.php index fe8bb4959..851397a93 100644 --- a/engine/classes/ElggMetadata.php +++ b/engine/classes/ElggMetadata.php @@ -4,14 +4,16 @@ * ElggMetadata * This class describes metadata that can be attached to ElggEntities. * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage Metadata */ class ElggMetadata extends ElggExtender { /** * Construct a new site object, optionally from a given id value or row. * - * @param mixed $id + * @param mixed $id ID of metadata from DB + * + * @return void */ function __construct($id = null) { $this->attributes = array(); @@ -26,7 +28,7 @@ class ElggMetadata extends ElggExtender { if ($metadata) { $objarray = (array) $metadata; - foreach($objarray as $key => $value) { + foreach ($objarray as $key => $value) { $this->attributes[$key] = $value; } $this->attributes['type'] = "metadata"; @@ -37,7 +39,8 @@ class ElggMetadata extends ElggExtender { /** * Class member get overloading * - * @param string $name + * @param string $name Name + * * @return mixed */ function __get($name) { @@ -47,8 +50,9 @@ class ElggMetadata extends ElggExtender { /** * Class member set overloading * - * @param string $name - * @param mixed $value + * @param string $name Name + * @param mixed $value Value + * * @return mixed */ function __set($name, $value) { @@ -74,9 +78,12 @@ class ElggMetadata extends ElggExtender { */ function save() { if ($this->id > 0) { - return update_metadata($this->id, $this->name, $this->value, $this->value_type, $this->owner_guid, $this->access_id); + return update_metadata($this->id, $this->name, $this->value, + $this->value_type, $this->owner_guid, $this->access_id); } else { - $this->id = create_metadata($this->entity_guid, $this->name, $this->value, $this->value_type, $this->owner_guid, $this->access_id); + $this->id = create_metadata($this->entity_guid, $this->name, $this->value, + $this->value_type, $this->owner_guid, $this->access_id); + if (!$this->id) { throw new IOException(sprintf(elgg_echo('IOException:UnableToSaveNew'), get_class())); } @@ -86,6 +93,8 @@ class ElggMetadata extends ElggExtender { /** * Delete a given metadata. + * + * @return bool */ function delete() { return delete_metadata($this->id); @@ -106,6 +115,10 @@ class ElggMetadata extends ElggExtender { * For a given ID, return the object associated with it. * This is used by the river functionality primarily. * This is useful for checking access permissions etc on objects. + * + * @param int $id Metadata ID + * + * @return ElggMetadata */ public function getObjectFromID($id) { return get_metadata($id); diff --git a/engine/classes/ElggObject.php b/engine/classes/ElggObject.php index d19e1c844..d2e3f14e4 100644 --- a/engine/classes/ElggObject.php +++ b/engine/classes/ElggObject.php @@ -12,16 +12,32 @@ * * @internal Title and description are stored in the objects_entity table. * - * @package Elgg.Core + * @package Elgg.Core * @subpackage DataModel.Object */ class ElggObject extends ElggEntity { /** * Initialise the attributes array to include the type, * title, and description. + * + * @deprecated 1.8 use ElggEntity::initializeAttributes() + * + * @return void */ protected function initialise_attributes() { - parent::initialise_attributes(); + elgg_deprecated_notice('ElggObject::initialise_attributes() is deprecated by ::initializeAttributes()', 1.8); + + return $this->initializeAttributes(); + } + + /** + * Initialise the attributes array to include the type, + * title, and description. + * + * @return void + */ + protected function initializeAttributes() { + parent::initializeAttributes(); $this->attributes['type'] = "object"; $this->attributes['title'] = ""; @@ -39,7 +55,9 @@ class ElggObject extends ElggEntity { * - The GUID of an object entity. * - A DB result object with a guid property * - * @param mixed $guid If an int, load that GUID. If a db row then will attempt to load the rest of the data. + * @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 */ @@ -51,32 +69,28 @@ class ElggObject extends ElggEntity { if ($guid instanceof stdClass) { // Load the rest if (!$this->load($guid->guid)) { - throw new IOException(sprintf(elgg_echo('IOException:FailedToLoadGUID'), get_class(), $guid->guid)); + $msg = sprintf(elgg_echo('IOException:FailedToLoadGUID'), get_class(), $guid->guid); + throw new IOException($msg); } - } - // Is $guid is an ElggObject? Use a copy constructor - else if ($guid instanceof ElggObject) { + // Is $guid is an ElggObject? Use a copy constructor + } else if ($guid instanceof ElggObject) { elgg_deprecated_notice('This type of usage of the ElggObject constructor was deprecated. Please use the clone method.', 1.7); foreach ($guid->attributes as $key => $value) { $this->attributes[$key] = $value; } - } - // Is this is an ElggEntity but not an ElggObject = ERROR! - else if ($guid instanceof ElggEntity) { + // Is this is an ElggEntity but not an ElggObject = ERROR! + } else if ($guid instanceof ElggEntity) { throw new InvalidParameterException(elgg_echo('InvalidParameterException:NonElggObject')); - } - // We assume if we have got this far, $guid is an int - else if (is_numeric($guid)) { + // We assume if we have got this far, $guid is an int + } else if (is_numeric($guid)) { if (!$this->load($guid)) { throw new IOException(sprintf(elgg_echo('IOException:FailedToLoadGUID'), get_class(), $guid)); } - } - - else { + } else { throw new InvalidParameterException(elgg_echo('InvalidParameterException:UnrecognisedValue')); } } @@ -85,7 +99,8 @@ class ElggObject extends ElggEntity { /** * Loads the full ElggObject when given a guid. * - * @param int $guid + * @param int $guid Guid of an ElggObject + * * @return bool * @throws InvalidClassException */ @@ -96,8 +111,9 @@ class ElggObject extends ElggEntity { } // Check the type - if ($this->attributes['type']!='object') { - throw new InvalidClassException(sprintf(elgg_echo('InvalidClassException:NotValidElggStar'), $guid, get_class())); + if ($this->attributes['type'] != 'object') { + $msg = sprintf(elgg_echo('InvalidClassException:NotValidElggStar'), $guid, get_class()); + throw new InvalidClassException($msg); } // Load missing data @@ -109,7 +125,7 @@ class ElggObject extends ElggEntity { // Now put these into the attributes array as core values $objarray = (array) $row; - foreach($objarray as $key => $value) { + foreach ($objarray as $key => $value) { $this->attributes[$key] = $value; } @@ -130,7 +146,8 @@ class ElggObject extends ElggEntity { } // Save ElggObject-specific attributes - return create_object_entity($this->get('guid'), $this->get('title'), $this->get('description'), $this->get('container_guid')); + return create_object_entity($this->get('guid'), $this->get('title'), + $this->get('description'), $this->get('container_guid')); } /** @@ -138,13 +155,16 @@ class ElggObject extends ElggEntity { * * 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 + * + * @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 + * + * @return array|false */ - function getSites($subtype="", $limit = 10, $offset = 0) { + function getSites($subtype = "", $limit = 10, $offset = 0) { return get_site_objects($this->getGUID(), $subtype, $limit, $offset); } @@ -152,6 +172,7 @@ class ElggObject extends ElggEntity { * Add this object to a site * * @param int $site_guid The guid of the site to add it to + * * @return bool */ function addToSite($site_guid) { @@ -162,6 +183,7 @@ class ElggObject extends ElggEntity { * Set the container for this object. * * @param int $container_guid The ID of the container. + * * @return bool */ function setContainer($container_guid) { @@ -194,16 +216,6 @@ class ElggObject extends ElggEntity { return false; } - /** - * Get the collections associated with a object. - * - * @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 - * @return unknown - */ - //public function getCollections($subtype="", $limit = 10, $offset = 0) { get_object_collections($this->getGUID(), $subtype, $limit, $offset); } - /* * EXPORTABLE INTERFACE */ diff --git a/engine/classes/ElggPlugin.php b/engine/classes/ElggPlugin.php index 3bbbc02fe..0ea7fdf61 100644 --- a/engine/classes/ElggPlugin.php +++ b/engine/classes/ElggPlugin.php @@ -5,24 +5,37 @@ * This class is currently a stub, allowing a plugin to * save settings in an object's private settings for each site. * - * @package Elgg.Core + * @package Elgg.Core * @subpackage Plugins.Settings */ class ElggPlugin extends ElggObject { - protected function initialise_attributes() { - parent::initialise_attributes(); - $this->attributes['subtype'] = "plugin"; + /** + * Set subtype to 'plugin' + * + * @return void + */ + protected function initialise_attributes() { + elgg_deprecated_notice('ElggPlugin::initialise_attributes() is deprecated by ::initializeAttributes()', 1.8); + return $this->initializeAttributes(); } - public function __construct($guid = null) { - parent::__construct($guid); + /** + * Set subtype to 'plugin' + * + * @return void + */ + protected function initializeAttributes() { + parent::initializeAttributes(); + + $this->attributes['subtype'] = "plugin"; } /** * Get a value from private settings. * - * @param string $name + * @param string $name Name + * * @return mixed */ public function get($name) { @@ -46,13 +59,15 @@ class ElggPlugin extends ElggObject { /** * Save a value to private settings. * - * @param string $name - * @param mixed $value + * @param string $name Name + * @param mixed $value Value + * + * @return bool */ public function set($name, $value) { if (array_key_exists($name, $this->attributes)) { // Check that we're not trying to change the guid! - if ((array_key_exists('guid', $this->attributes)) && ($name=='guid')) { + if ((array_key_exists('guid', $this->attributes)) && ($name == 'guid')) { return false; } diff --git a/engine/classes/ElggRelationship.php b/engine/classes/ElggRelationship.php index f90c1bb50..847dfa8e9 100644 --- a/engine/classes/ElggRelationship.php +++ b/engine/classes/ElggRelationship.php @@ -2,7 +2,7 @@ /** * Relationship class. * - * @package Elgg.Core + * @package Elgg.Core * @subpackage Core */ class ElggRelationship implements @@ -21,7 +21,7 @@ class ElggRelationship implements /** * Construct a new site object, optionally from a given id value or row. * - * @param mixed $id + * @param mixed $id ElggRelationship id */ function __construct($id = null) { $this->attributes = array(); @@ -35,7 +35,7 @@ class ElggRelationship implements if ($relationship) { $objarray = (array) $relationship; - foreach($objarray as $key => $value) { + foreach ($objarray as $key => $value) { $this->attributes[$key] = $value; } } @@ -45,7 +45,8 @@ class ElggRelationship implements /** * Class member get overloading * - * @param string $name + * @param string $name Name + * * @return mixed */ function __get($name) { @@ -59,8 +60,9 @@ class ElggRelationship implements /** * Class member set overloading * - * @param string $name - * @param mixed $value + * @param string $name Name + * @param mixed $value Value + * * @return mixed */ function __set($name, $value) { @@ -88,6 +90,8 @@ class ElggRelationship implements /** * Delete a given relationship. + * + * @return bool */ public function delete() { return delete_relationship($this->id); @@ -106,6 +110,8 @@ class ElggRelationship implements /** * Return an array of fields which can be exported. + * + * @return array */ public function getExportableValues() { return array( @@ -139,9 +145,10 @@ class ElggRelationship implements /** * Import a relationship * - * @param array $data - * @param int $version + * @param array $data ODD data + * * @return ElggRelationship + * * @throws ImportException */ public function import(ODD $data) { @@ -192,6 +199,8 @@ class ElggRelationship implements /** * Return the class name of the object. + * + * @return string */ public function getClassName() { return get_class($this); @@ -201,6 +210,10 @@ class ElggRelationship implements * For a given ID, return the object associated with it. * This is used by the river functionality primarily. * This is useful for checking access permissions etc on objects. + * + * @param int $id ID + * + * @return ElggRelationship */ public function getObjectFromID($id) { return get_relationship($id); @@ -208,6 +221,8 @@ class ElggRelationship implements /** * Return the GUID of the owner of this object. + * + * @return int */ public function getObjectOwnerGUID() { return $this->owner_guid; @@ -215,13 +230,18 @@ class ElggRelationship implements /** * Return a type of the object - eg. object, group, user, relationship, metadata, annotation etc + * + * @return string 'relationship' */ public function getType() { return 'relationship'; } /** - * Return a subtype. For metadata & annotations this is the 'name' and for relationship this is the relationship type. + * Return a subtype. For metadata & annotations this is the 'name' and for relationship this + * is the relationship type. + * + * @return string */ public function getSubtype() { return $this->relationship; @@ -235,22 +255,58 @@ class ElggRelationship implements private $valid = FALSE; + /** + * Iterator interface + * + * @see Iterator::rewind() + * + * @return void + */ function rewind() { $this->valid = (FALSE !== reset($this->attributes)); } + /** + * Iterator interface + * + * @see Iterator::current() + * + * @return void + */ function current() { return current($this->attributes); } + /** + * Iterator interface + * + * @see Iterator::key() + * + * @return void + */ function key() { return key($this->attributes); } + /** + * Iterator interface + * + * @see Iterator::next() + * + * @return void + */ function next() { $this->valid = (FALSE !== next($this->attributes)); } + + /** + * Iterator interface + * + * @see Iterator::valid() + * + * @return void + */ function valid() { return $this->valid; } @@ -261,24 +317,61 @@ class ElggRelationship implements * Example: http://www.sitepoint.com/print/php5-standard-library */ + /** + * Array access interface + * + * @see ArrayAccess::offsetSet() + * + * @param mixed $key Name + * @param mixed $value Value + * + * @return void + */ function offsetSet($key, $value) { - if ( array_key_exists($key, $this->attributes) ) { + if (array_key_exists($key, $this->attributes)) { $this->attributes[$key] = $value; } } + /** + * Array access interface + * + * @see ArrayAccess::offsetGet() + * + * @param mixed $key Name + * + * @return void + */ function offsetGet($key) { - if ( array_key_exists($key, $this->attributes) ) { + if (array_key_exists($key, $this->attributes)) { return $this->attributes[$key]; } } + /** + * Array access interface + * + * @see ArrayAccess::offsetUnset() + * + * @param mixed $key Name + * + * @return void + */ function offsetUnset($key) { - if ( array_key_exists($key, $this->attributes) ) { + if (array_key_exists($key, $this->attributes)) { $this->attributes[$key] = ""; // Full unsetting is dangerious for our objects } } + /** + * Array access interface + * + * @see ArrayAccess::offsetExists() + * + * @param int $offset Offset + * + * @return int + */ function offsetExists($offset) { return array_key_exists($offset, $this->attributes); } diff --git a/engine/classes/ElggSession.php b/engine/classes/ElggSession.php index e34f7a961..1d59aaacc 100644 --- a/engine/classes/ElggSession.php +++ b/engine/classes/ElggSession.php @@ -4,34 +4,57 @@ * This class is intended to extend the $_SESSION magic variable by providing an API hook * to plug in other values. * - * Primarily this is intended to provide a way of supplying "logged in user" details without touching the session - * (which can cause problems when accessed server side). + * Primarily this is intended to provide a way of supplying "logged in user" + * details without touching the session (which can cause problems when + * accessed server side). * - * If a value is present in the session then that value is returned, otherwise a plugin hook 'session:get', '$var' is called, - * where $var is the variable being requested. + * If a value is present in the session then that value is returned, otherwise + * a plugin hook 'session:get', '$var' is called, where $var is the variable + * being requested. * * Setting values will store variables in the session in the normal way. * * LIMITATIONS: You can not access multidimensional arrays * - * This is EXPERIMENTAL. + * @package Elgg.Core + * @subpackage Sessions */ class ElggSession implements ArrayAccess { /** Local cache of trigger retrieved variables */ private static $__localcache; + /** + * Test if property is set either as an attribute or metadata. + * + * @param string $key The name of the attribute or metadata. + * + * @return bool + */ function __isset($key) { return $this->offsetExists($key); } - /** Set a value, go straight to session. */ + /** + * Set a value, go straight to session. + * + * @param string $key Name + * @param mixed $value Value + * + * @return void + */ function offsetSet($key, $value) { $_SESSION[$key] = $value; } /** - * Get a variable from either the session, or if its not in the session attempt to get it from - * an api call. + * Get a variable from either the session, or if its not in the session + * attempt to get it from an api call. + * + * @see ArrayAccess::offsetGet() + * + * @param mixed $key Name + * + * @return void */ function offsetGet($key) { if (!ElggSession::$__localcache) { @@ -55,16 +78,28 @@ class ElggSession implements ArrayAccess { } /** - * Unset a value from the cache and the session. - */ + * Unset a value from the cache and the session. + * + * @see ArrayAccess::offsetUnset() + * + * @param mixed $key Name + * + * @return void + */ function offsetUnset($key) { unset(ElggSession::$__localcache[$key]); unset($_SESSION[$key]); } /** - * Return whether the value is set in either the session or the cache. - */ + * Return whether the value is set in either the session or the cache. + * + * @see ArrayAccess::offsetExists() + * + * @param int $offset Offset + * + * @return int + */ function offsetExists($offset) { if (isset(ElggSession::$__localcache[$offset])) { return true; @@ -74,21 +109,42 @@ class ElggSession implements ArrayAccess { return true; } - if ($this->offsetGet($offset)){ + if ($this->offsetGet($offset)) { return true; } } - // Alias functions + /** + * Alias to ::offsetGet() + * + * @param string $key Name + * + * @return mixed + */ function get($key) { return $this->offsetGet($key); } + /** + * Alias to ::offsetSet() + * + * @param string $key Name + * @param mixed $value Value + * + * @return mixed + */ function set($key, $value) { return $this->offsetSet($key, $value); } + /** + * Alias to offsetUnset() + * + * @param string $key Name + * + * @return bool + */ function del($key) { return $this->offsetUnset($key); } diff --git a/engine/classes/ElggSharedMemoryCache.php b/engine/classes/ElggSharedMemoryCache.php index 82c9c571a..6d6a3d625 100644 --- a/engine/classes/ElggSharedMemoryCache.php +++ b/engine/classes/ElggSharedMemoryCache.php @@ -1,7 +1,11 @@ <?php /** * Shared memory cache description. - * Extends ElggCache with functions useful to shared memory style caches (static variables, memcache etc) + * Extends ElggCache with functions useful to shared memory + * style caches (static variables, memcache etc) + * + * @package Elgg.Core + * @subpackage Cache */ abstract class ElggSharedMemoryCache extends ElggCache { /** @@ -17,7 +21,9 @@ abstract class ElggSharedMemoryCache extends ElggCache { * This is useful for cache types (like memcache or static variables) where there is one large * flat area of memory shared across all instances of the cache. * - * @param string $namespace + * @param string $namespace Namespace for cache + * + * @return void */ public function setNamespace($namespace = "default") { $this->namespace = $namespace; diff --git a/engine/classes/ElggSite.php b/engine/classes/ElggSite.php index e71f3ca25..6f4abf18c 100644 --- a/engine/classes/ElggSite.php +++ b/engine/classes/ElggSite.php @@ -18,9 +18,9 @@ * * @warning Multiple site support isn't fully developed. * - * @package Elgg.Core + * @package Elgg.Core * @subpackage DataMode.Site - * @link http://docs.elgg.org/DataModel/Sites + * @link http://docs.elgg.org/DataModel/Sites */ class ElggSite extends ElggEntity { /** @@ -28,9 +28,27 @@ class ElggSite extends ElggEntity { * This is vital to distinguish between metadata and base parameters. * * Place your base parameters here. + * + * @deprecated 1.8 Use ElggSite::initializeAttributes() + * + * @return void */ protected function initialise_attributes() { - parent::initialise_attributes(); + elgg_deprecated_notice('ElggSite::initialise_attributes() is deprecated by ::initializeAttributes()', 1.8); + + return $this->initializeAttributes(); + } + + /** + * Initialise the attributes array. + * This is vital to distinguish between metadata and base parameters. + * + * Place your base parameters here. + * + * @return void + */ + protected function initializeAttributes() { + parent::initializeAttributes(); $this->attributes['type'] = "site"; $this->attributes['name'] = ""; @@ -50,52 +68,49 @@ class ElggSite extends ElggEntity { * - A URL as stored in ElggSite->url * - A DB result object with a guid property * - * @param mixed $guid If an int, load that GUID. If a db row then will attempt to load the rest of the data. + * @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 ElggSite */ function __construct($guid = null) { - $this->initialise_attributes(); + $this->initializeAttributes(); if (!empty($guid)) { // Is $guid is a DB row - either a entity row, or a site table row. if ($guid instanceof stdClass) { // Load the rest if (!$this->load($guid->guid)) { - throw new IOException(sprintf(elgg_echo('IOException:FailedToLoadGUID'), get_class(), $guid->guid)); + $msg = sprintf(elgg_echo('IOException:FailedToLoadGUID'), get_class(), $guid->guid); + throw new IOException($msg); } - } - // Is $guid is an ElggSite? Use a copy constructor - else if ($guid instanceof ElggSite) { + // Is $guid is an ElggSite? Use a copy constructor + } else if ($guid instanceof ElggSite) { elgg_deprecated_notice('This type of usage of the ElggSite constructor was deprecated. Please use the clone method.', 1.7); foreach ($guid->attributes as $key => $value) { $this->attributes[$key] = $value; } - } - // Is this is an ElggEntity but not an ElggSite = ERROR! - else if ($guid instanceof ElggEntity) { + // Is this is an ElggEntity but not an ElggSite = ERROR! + } else if ($guid instanceof ElggEntity) { throw new InvalidParameterException(elgg_echo('InvalidParameterException:NonElggSite')); - } - // See if this is a URL - else if (strpos($guid, "http") !== false) { + // See if this is a URL + } else if (strpos($guid, "http") !== false) { $guid = get_site_by_url($guid); foreach ($guid->attributes as $key => $value) { $this->attributes[$key] = $value; } - } - // We assume if we have got this far, $guid is an int - else if (is_numeric($guid)) { + // We assume if we have got this far, $guid is an int + } else if (is_numeric($guid)) { if (!$this->load($guid)) { throw new IOException(sprintf(elgg_echo('IOException:FailedToLoadGUID'), get_class(), $guid)); } - } - - else { + } else { throw new InvalidParameterException(elgg_echo('InvalidParameterException:UnrecognisedValue')); } } @@ -104,7 +119,8 @@ class ElggSite extends ElggEntity { /** * Loads the full ElggSite when given a guid. * - * @param int $guid + * @param int $guid Guid of ElggSite entity + * * @return bool * @throws InvalidClassException */ @@ -115,8 +131,9 @@ class ElggSite extends ElggEntity { } // Check the type - if ($this->attributes['type']!='site') { - throw new InvalidClassException(sprintf(elgg_echo('InvalidClassException:NotValidElggStar'), $guid, get_class())); + if ($this->attributes['type'] != 'site') { + $msg = sprintf(elgg_echo('InvalidClassException:NotValidElggStar'), $guid, get_class()); + throw new InvalidClassException($msg); } // Load missing data @@ -128,7 +145,7 @@ class ElggSite extends ElggEntity { // Now put these into the attributes array as core values $objarray = (array) $row; - foreach($objarray as $key => $value) { + foreach ($objarray as $key => $value) { $this->attributes[$key] = $value; } @@ -149,7 +166,8 @@ class ElggSite extends ElggEntity { } // Now save specific stuff - return create_site_entity($this->get('guid'), $this->get('name'), $this->get('description'), $this->get('url')); + return create_site_entity($this->get('guid'), $this->get('name'), + $this->get('description'), $this->get('url')); } /** @@ -174,7 +192,8 @@ class ElggSite extends ElggEntity { * * @note You cannot disable the current site. * - * @param string $reason + * @param string $reason Optional reason for disabling + * * @return bool * @throws SecurityException */ @@ -191,8 +210,9 @@ class ElggSite extends ElggEntity { /** * Returns an array of ElggUser entities who are members of the site. * - * @param int $limit - * @param int $offset + * @param int $limit Limit + * @param int $offset Offset + * * @return array of ElggUsers */ public function getMembers($limit = 10, $offset = 0) { @@ -202,7 +222,8 @@ class ElggSite extends ElggEntity { /** * Adds a user to the site. * - * @param int $user_guid + * @param int $user_guid GUID + * * @return bool */ public function addUser($user_guid) { @@ -212,7 +233,8 @@ class ElggSite extends ElggEntity { /** * Removes a user from the site. * - * @param int $user_guid + * @param int $user_guid GUID + * * @return bool */ public function removeUser($user_guid) { @@ -222,19 +244,21 @@ class ElggSite extends ElggEntity { /** * Returns an array of ElggObject entities that belong to the site. * - * @param string $subtype - * @param int $limit - * @param int $offset + * @param string $subtype Entity subtype + * @param int $limit Limit + * @param int $offset Offset + * * @return array */ - public function getObjects($subtype="", $limit = 10, $offset = 0) { + public function getObjects($subtype = "", $limit = 10, $offset = 0) { get_site_objects($this->getGUID(), $subtype, $limit, $offset); } /** * Adds an object to the site. * - * @param int $object_guid + * @param int $object_guid GUID + * * @return bool */ public function addObject($object_guid) { @@ -244,7 +268,8 @@ class ElggSite extends ElggEntity { /** * Remvoes an object from the site. * - * @param int $object_guid + * @param int $object_guid GUID + * * @return bool */ public function removeObject($object_guid) { @@ -254,13 +279,14 @@ class ElggSite extends ElggEntity { /** * Get the collections associated with a site. * - * @param string $type - * @param int $limit - * @param int $offset + * @param string $subtype Subtype + * @param int $limit Limit + * @param int $offset Offset + * * @return unknown * @todo Unimplemented */ - public function getCollections($subtype="", $limit = 10, $offset = 0) { + public function getCollections($subtype = "", $limit = 10, $offset = 0) { get_site_collections($this->getGUID(), $subtype, $limit, $offset); } @@ -287,8 +313,10 @@ class ElggSite extends ElggEntity { * and the URL is not a public page. * * @link http://docs.elgg.org/Tutorials/WalledGarden + * + * @return void */ - public function check_walled_garden() { + public function checkWalledGarden() { global $CONFIG; if ($CONFIG->walled_garden && !isloggedin()) { @@ -308,9 +336,10 @@ class ElggSite extends ElggEntity { * Pages are registered to be public by {@elgg_plugin_hook public_pages walled_garden}. * * @param string $url Defaults to the current URL. + * * @return bool */ - public function is_public_page($url='') { + public function isPublicPage($url = '') { global $CONFIG; if (empty($url)) { diff --git a/engine/classes/ElggStaticVariableCache.php b/engine/classes/ElggStaticVariableCache.php index 85facf7a7..a846ab60f 100644 --- a/engine/classes/ElggStaticVariableCache.php +++ b/engine/classes/ElggStaticVariableCache.php @@ -1,11 +1,11 @@ <?php /** * ElggStaticVariableCache - * Dummy cache which stores values in a static array. Using this makes future replacements to other caching back - * ends (eg memcache) much easier. + * Dummy cache which stores values in a static array. Using this makes future + * replacements to other caching back ends (eg memcache) much easier. * - * @package Elgg - * @subpackage API + * @package Elgg.Core + * @subpackage Cache */ class ElggStaticVariableCache extends ElggSharedMemoryCache { /** @@ -18,15 +18,25 @@ class ElggStaticVariableCache extends ElggSharedMemoryCache { /** * Create the variable cache. * - * This function creates a variable cache in a static variable in memory, optionally with a given namespace (to avoid overlap). + * This function creates a variable cache in a static variable in + * memory, optionally with a given namespace (to avoid overlap). * - * @param string $namespace The namespace for this cache to write to - note, namespaces of the same name are shared! + * @param string $namespace The namespace for this cache to write to + * note, namespaces of the same name are shared! */ function __construct($namespace = 'default') { $this->setNamespace($namespace); $this->clear(); } + /** + * Save a key + * + * @param string $key Name + * @param string $data Value + * + * @return boolean + */ public function save($key, $data) { $namespace = $this->getNamespace(); @@ -35,6 +45,15 @@ class ElggStaticVariableCache extends ElggSharedMemoryCache { return true; } + /** + * Load a key + * + * @param string $key Name + * @param int $offset Offset + * @param int $limit Limit + * + * @return string + */ public function load($key, $offset = 0, $limit = null) { $namespace = $this->getNamespace(); @@ -45,6 +64,13 @@ class ElggStaticVariableCache extends ElggSharedMemoryCache { return false; } + /** + * Invalidate a given key. + * + * @param string $key Name + * + * @return bool + */ public function delete($key) { $namespace = $this->getNamespace(); @@ -53,6 +79,11 @@ class ElggStaticVariableCache extends ElggSharedMemoryCache { return true; } + /** + * This was probably meant to delete everything? + * + * @return void + */ public function clear() { $namespace = $this->getNamespace(); diff --git a/engine/classes/ElggUser.php b/engine/classes/ElggUser.php index 3bd93bba2..380fc4e8b 100644 --- a/engine/classes/ElggUser.php +++ b/engine/classes/ElggUser.php @@ -4,8 +4,8 @@ * * Representation of a "user" in the system. * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage DataModel.User */ class ElggUser extends ElggEntity implements Friendable { @@ -14,9 +14,27 @@ class ElggUser extends ElggEntity * This is vital to distinguish between metadata and base parameters. * * Place your base parameters here. + * + * @deprecated 1.8 Use ElggUser::initializeAttributes() + * + * @return void */ protected function initialise_attributes() { - parent::initialise_attributes(); + elgg_deprecated_notice('ElggUser::initialise_attributes() is deprecated by ::initializeAttributes()', 1.8); + + return $this->initializeAttributes(); + } + + /** + * Initialise the attributes array. + * This is vital to distinguish between metadata and base parameters. + * + * Place your base parameters here. + * + * @return void + */ + protected function initializeAttributes() { + parent::initializeAttributes(); $this->attributes['type'] = "user"; $this->attributes['name'] = ""; @@ -36,6 +54,7 @@ class ElggUser extends ElggEntity * * @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 user. */ function __construct($guid = null) { @@ -46,40 +65,35 @@ class ElggUser extends ElggEntity if ($guid instanceof stdClass) { // Load the rest if (!$this->load($guid->guid)) { - throw new IOException(sprintf(elgg_echo('IOException:FailedToLoadGUID'), get_class(), $guid->guid)); + $msg = sprintf(elgg_echo('IOException:FailedToLoadGUID'), get_class(), $guid->guid); + throw new IOException($msg); } - } - // See if this is a username - else if (is_string($guid)) { + // See if this is a username + } else if (is_string($guid)) { $guid = get_user_by_username($guid); foreach ($guid->attributes as $key => $value) { $this->attributes[$key] = $value; } - } - // Is $guid is an ElggUser? Use a copy constructor - else if ($guid instanceof ElggUser) { + // Is $guid is an ElggUser? Use a copy constructor + } else if ($guid instanceof ElggUser) { elgg_deprecated_notice('This type of usage of the ElggUser constructor was deprecated. Please use the clone method.', 1.7); foreach ($guid->attributes as $key => $value) { $this->attributes[$key] = $value; } - } - // Is this is an ElggEntity but not an ElggUser = ERROR! - else if ($guid instanceof ElggEntity) { + // Is this is an ElggEntity but not an ElggUser = ERROR! + } else if ($guid instanceof ElggEntity) { throw new InvalidParameterException(elgg_echo('InvalidParameterException:NonElggUser')); - } - // We assume if we have got this far, $guid is an int - else if (is_numeric($guid)) { + // We assume if we have got this far, $guid is an int + } else if (is_numeric($guid)) { if (!$this->load($guid)) { throw new IOException(sprintf(elgg_echo('IOException:FailedToLoadGUID'), get_class(), $guid)); } - } - - else { + } else { throw new InvalidParameterException(elgg_echo('InvalidParameterException:UnrecognisedValue')); } } @@ -90,7 +104,8 @@ class ElggUser extends ElggEntity * This function will ensure that all data is loaded (were possible), so * if only part of the ElggUser is loaded, it'll load the rest. * - * @param int $guid + * @param int $guid ElggUser GUID + * * @return true|false */ protected function load($guid) { @@ -100,8 +115,9 @@ class ElggUser extends ElggEntity } // Check the type - if ($this->attributes['type']!='user') { - throw new InvalidClassException(sprintf(elgg_echo('InvalidClassException:NotValidElggStar'), $guid, get_class())); + if ($this->attributes['type'] != 'user') { + $msg = sprintf(elgg_echo('InvalidClassException:NotValidElggStar'), $guid, get_class()); + throw new InvalidClassException($msg); } // Load missing data @@ -113,7 +129,7 @@ class ElggUser extends ElggEntity // Now put these into the attributes array as core values $objarray = (array) $row; - foreach($objarray as $key => $value) { + foreach ($objarray as $key => $value) { $this->attributes[$key] = $value; } @@ -122,6 +138,7 @@ class ElggUser extends ElggEntity /** * Saves this user to the database. + * * @return true|false */ public function save() { @@ -131,7 +148,9 @@ class ElggUser extends ElggEntity } // Now save specific stuff - return create_user_entity($this->get('guid'), $this->get('name'), $this->get('username'), $this->get('password'), $this->get('salt'), $this->get('email'), $this->get('language'), $this->get('code')); + return create_user_entity($this->get('guid'), $this->get('name'), $this->get('username'), + $this->get('password'), $this->get('salt'), $this->get('email'), $this->get('language'), + $this->get('code')); } /** @@ -163,6 +182,8 @@ class ElggUser extends ElggEntity * Ban this user. * * @param string $reason Optional reason + * + * @return bool */ public function ban($reason = "") { return ban_user($this->guid, $reason); @@ -170,8 +191,10 @@ class ElggUser extends ElggEntity /** * Unban this user. + * + * @return bool */ - public function unban() { + public function unban() { return unban_user($this->guid); } @@ -236,11 +259,12 @@ class ElggUser extends ElggEntity * Get sites that this user is a member of * * @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 + * @param int $limit The number of results to return + * @param int $offset Any indexing offset + * + * @return bool */ - function getSites($subtype="", $limit = 10, $offset = 0) { - // return get_site_users($this->getGUID(), $subtype, $limit, $offset); + function getSites($subtype = "", $limit = 10, $offset = 0) { return get_user_sites($this->getGUID(), $subtype, $limit, $offset); } @@ -248,10 +272,10 @@ class ElggUser extends ElggEntity * Add this user to a particular site * * @param int $site_guid The guid of the site to add it to + * * @return true|false */ function addToSite($site_guid) { - // return add_site_user($this->getGUID(), $site_guid); return add_site_user($site_guid, $this->getGUID()); } @@ -259,10 +283,10 @@ class ElggUser extends ElggEntity * Remove this user from a particular site * * @param int $site_guid The guid of the site to remove it from + * * @return true|false */ function removeFromSite($site_guid) { - //return remove_site_user($this->getGUID(), $site_guid); return remove_site_user($site_guid, $this->getGUID()); } @@ -270,6 +294,7 @@ class ElggUser extends ElggEntity * Adds a user to this user's friends list * * @param int $friend_guid The GUID of the user to add + * * @return true|false Depending on success */ function addFriend($friend_guid) { @@ -280,6 +305,7 @@ class ElggUser extends ElggEntity * Removes a user from this user's friends list * * @param int $friend_guid The GUID of the user to remove + * * @return true|false Depending on success */ function removeFriend($friend_guid) { @@ -299,6 +325,7 @@ class ElggUser extends ElggEntity * Determines whether this user is friends with another user * * @param int $user_guid The GUID of the user to check is on this user's friends list + * * @return true|false */ function isFriendsWith($user_guid) { @@ -309,6 +336,7 @@ class ElggUser extends ElggEntity * Determines whether or not this user is on another user's friends list * * @param int $user_guid The GUID of the user to check against + * * @return true|false */ function isFriendOf($user_guid) { @@ -319,8 +347,9 @@ class ElggUser extends ElggEntity * Retrieves a list of this user's friends * * @param string $subtype Optionally, the subtype of user to filter to (leave blank for all) - * @param int $limit The number of users to retrieve - * @param int $offset Indexing offset, if any + * @param int $limit The number of users to retrieve + * @param int $offset Indexing offset, if any + * * @return array|false Array of ElggUsers, or false, depending on success */ function getFriends($subtype = "", $limit = 10, $offset = 0) { @@ -331,8 +360,9 @@ class ElggUser extends ElggEntity * Retrieves a list of people who have made this user a friend * * @param string $subtype Optionally, the subtype of user to filter to (leave blank for all) - * @param int $limit The number of users to retrieve - * @param int $offset Indexing offset, if any + * @param int $limit The number of users to retrieve + * @param int $offset Indexing offset, if any + * * @return array|false Array of ElggUsers, or false, depending on success */ function getFriendsOf($subtype = "", $limit = 10, $offset = 0) { @@ -343,10 +373,12 @@ class ElggUser extends ElggEntity * Get an array of ElggObjects owned by this user. * * @param string $subtype The subtype of the objects, if any - * @param int $limit Number of results to return - * @param int $offset Any indexing offset + * @param int $limit Number of results to return + * @param int $offset Any indexing offset + * + * @return array|false */ - public function getObjects($subtype="", $limit = 10, $offset = 0) { + public function getObjects($subtype = "", $limit = 10, $offset = 0) { return get_user_objects($this->getGUID(), $subtype, $limit, $offset); } @@ -354,8 +386,10 @@ class ElggUser extends ElggEntity * Get an array of ElggObjects owned by this user's friends. * * @param string $subtype The subtype of the objects, if any - * @param int $limit Number of results to return - * @param int $offset Any indexing offset + * @param int $limit Number of results to return + * @param int $offset Any indexing offset + * + * @return array|false */ public function getFriendsObjects($subtype = "", $limit = 10, $offset = 0) { return get_user_friends_objects($this->getGUID(), $subtype, $limit, $offset); @@ -365,6 +399,7 @@ class ElggUser extends ElggEntity * Counts the number of ElggObjects owned by this user * * @param string $subtype The subtypes of the objects, if any + * * @return int The number of ElggObjects */ public function countObjects($subtype = "") { @@ -375,11 +410,12 @@ class ElggUser extends ElggEntity * Get the collections associated with a user. * * @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 - * @return unknown + * @param int $limit The number of results to return + * @param int $offset Any indexing offset + * + * @return array|false */ - public function getCollections($subtype="", $limit = 10, $offset = 0) { + public function getCollections($subtype = "", $limit = 10, $offset = 0) { return get_user_collections($this->getGUID(), $subtype, $limit, $offset); } @@ -400,6 +436,8 @@ class ElggUser extends ElggEntity /** * Return an array of fields which can be exported. + * + * @return array */ public function getExportableValues() { return array_merge(parent::getExportableValues(), array( @@ -409,8 +447,14 @@ class ElggUser extends ElggEntity )); } - // backward compatibility with admin flag - // remove for 1.9 + /** + * Need to catch attempts to make a user an admin. Remove for 1.9 + * + * @param string $name Name + * @param mixed $value Value + * + * @return bool + */ public function __set($name, $value) { if ($name == 'admin' || $name == 'siteadmin') { elgg_deprecated_notice('The admin/siteadmin metadata are not longer used. Use ElggUser->makeAdmin() and ElggUser->removeAdmin().', '1.7.1'); @@ -424,6 +468,13 @@ class ElggUser extends ElggEntity return parent::__set($name, $value); } + /** + * Need to catch attempts to test user for admin. Remove for 1.9 + * + * @param string $name Name + * + * @return bool + */ public function __get($name) { if ($name == 'admin' || $name == 'siteadmin') { elgg_deprecated_notice('The admin/siteadmin metadata are not longer used. Use ElggUser->isAdmin().', '1.7.1'); diff --git a/engine/classes/ElggWidget.php b/engine/classes/ElggWidget.php index 30cbc7dc2..c9a65967c 100644 --- a/engine/classes/ElggWidget.php +++ b/engine/classes/ElggWidget.php @@ -2,20 +2,42 @@ /** * Override ElggObject in order to store widget data in ultra-private stores. + * + * @package Elgg.Core + * @subpackage Widgets */ class ElggWidget extends ElggObject { + + /** + * Set subtype to widget. + * + * @deprecated 1.8 use ElggWidget::initializeAttributes() + * + * @return void + */ protected function initialise_attributes() { - parent::initialise_attributes(); + elgg_deprecated_notice('ElggWidget::initialise_attributes() is deprecated by ::initializeAttributes()', 1.8); - $this->attributes['subtype'] = "widget"; + return $this->initializeAttributes(); } - public function __construct($guid = null) { - parent::__construct($guid); + /** + * Set subtype to widget. + * + * @return void + */ + protected function initializeAttributes() { + parent::initializeAttributes(); + + $this->attributes['subtype'] = "widget"; } /** * Override entity get and sets in order to save data to private data store. + * + * @param string $name Name + * + * @return mixed */ public function get($name) { // See if its in our base attribute @@ -35,11 +57,16 @@ class ElggWidget extends ElggObject { /** * Override entity get and sets in order to save data to private data store. + * + * @param string $name Name + * @param string $value Value + * + * @return bool */ public function set($name, $value) { if (array_key_exists($name, $this->attributes)) { // Check that we're not trying to change the guid! - if ((array_key_exists('guid', $this->attributes)) && ($name=='guid')) { + if ((array_key_exists('guid', $this->attributes)) && ($name == 'guid')) { return false; } diff --git a/engine/classes/ErrorResult.php b/engine/classes/ErrorResult.php index 739101dbb..8dbb7c13f 100644 --- a/engine/classes/ErrorResult.php +++ b/engine/classes/ErrorResult.php @@ -3,8 +3,8 @@ * ErrorResult * The error result class. * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage WebServicesAPI */ class ErrorResult extends GenericResult { // Fail with no specific code @@ -17,12 +17,21 @@ class ErrorResult extends GenericResult { // Invalid, expired or missing auth token public static $RESULT_FAIL_AUTHTOKEN = -20; + /** + * A new error result + * + * @param string $message Message + * @param int $code Error Code + * @param Exception $exception Exception object + * + * @return void + */ public function ErrorResult($message, $code = "", Exception $exception = NULL) { if ($code == "") { $code = ErrorResult::$RESULT_FAIL; } - if ($exception!=NULL) { + if ($exception != NULL) { $this->setResult($exception->__toString()); } @@ -32,9 +41,11 @@ class ErrorResult extends GenericResult { /** * Get a new instance of the ErrorResult. * - * @param string $message - * @param int $code + * @param string $message Message + * @param int $code Code * @param Exception $exception Optional exception for generating a stack trace. + * + * @return ErrorResult */ public static function getInstance($message, $code = "", Exception $exception = NULL) { // Return a new error object. diff --git a/engine/classes/ExportException.php b/engine/classes/ExportException.php index 53bf58cec..11781d91b 100644 --- a/engine/classes/ExportException.php +++ b/engine/classes/ExportException.php @@ -2,8 +2,8 @@ /** * Export exception * - * @package Elgg - * @subpackage Exceptions + * @package Elgg.Core + * @subpackage Exception * */ class ExportException extends DataFormatException {}
\ No newline at end of file diff --git a/engine/classes/Exportable.php b/engine/classes/Exportable.php index c8bc3bcd7..1adcd781e 100644 --- a/engine/classes/Exportable.php +++ b/engine/classes/Exportable.php @@ -2,12 +2,13 @@ /** * Define an interface for all ODD exportable objects. * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage ODD */ interface Exportable { /** * This must take the contents of the object and convert it to exportable ODD + * * @return object or array of objects. */ public function export(); @@ -15,6 +16,8 @@ interface Exportable { /** * Return a list of all fields that can be exported. * This should be used as the basis for the values returned by export() + * + * @return array */ public function getExportableValues(); }
\ No newline at end of file diff --git a/engine/classes/Friendable.php b/engine/classes/Friendable.php index d400bd092..588f9ec5a 100644 --- a/engine/classes/Friendable.php +++ b/engine/classes/Friendable.php @@ -2,12 +2,16 @@ /** * An interface for objects that behave as elements within a social network that have a profile. * + * @package Elgg.Core + * @subpackage SocialModel.Friendable */ interface Friendable { /** * Adds a user as a friend * * @param int $friend_guid The GUID of the user to add + * + * @return bool */ public function addFriend($friend_guid); @@ -15,12 +19,15 @@ interface Friendable { * Removes a user as a friend * * @param int $friend_guid The GUID of the user to remove + * + * @return bool */ public function removeFriend($friend_guid); /** * Determines whether or not the current user is a friend of this entity * + * @return bool */ public function isFriend(); @@ -28,6 +35,8 @@ interface Friendable { * Determines whether or not this entity is friends with a particular entity * * @param int $user_guid The GUID of the entity this entity may or may not be friends with + * + * @return bool */ public function isFriendsWith($user_guid); @@ -35,6 +44,8 @@ interface Friendable { * Determines whether or not a foreign entity has made this one a friend * * @param int $user_guid The GUID of the foreign entity + * + * @return bool */ public function isFriendOf($user_guid); @@ -42,8 +53,10 @@ interface Friendable { * Returns this entity's friends * * @param string $subtype The subtype of entity to return - * @param int $limit The number of entities to return - * @param int $offset Indexing offset + * @param int $limit The number of entities to return + * @param int $offset Indexing offset + * + * @return array|false */ public function getFriends($subtype = "", $limit = 10, $offset = 0); @@ -51,8 +64,10 @@ interface Friendable { * Returns entities that have made this entity a friend * * @param string $subtype The subtype of entity to return - * @param int $limit The number of entities to return - * @param int $offset Indexing offset + * @param int $limit The number of entities to return + * @param int $offset Indexing offset + * + * @return array|false */ public function getFriendsOf($subtype = "", $limit = 10, $offset = 0); @@ -60,17 +75,21 @@ interface Friendable { * Returns objects in this entity's container * * @param string $subtype The subtype of entity to return - * @param int $limit The number of entities to return - * @param int $offset Indexing offset + * @param int $limit The number of entities to return + * @param int $offset Indexing offset + * + * @return array|false */ - public function getObjects($subtype="", $limit = 10, $offset = 0); + public function getObjects($subtype = "", $limit = 10, $offset = 0); /** * Returns objects in the containers of this entity's friends * * @param string $subtype The subtype of entity to return - * @param int $limit The number of entities to return - * @param int $offset Indexing offset + * @param int $limit The number of entities to return + * @param int $offset Indexing offset + * + * @return array|false */ public function getFriendsObjects($subtype = "", $limit = 10, $offset = 0); @@ -78,6 +97,8 @@ interface Friendable { * Returns the number of object entities in this entity's container * * @param string $subtype The subtype of entity to count + * + * @return int */ public function countObjects($subtype = ""); }
\ No newline at end of file diff --git a/engine/classes/GenericResult.php b/engine/classes/GenericResult.php index 746f0522a..bb8a7e76e 100644 --- a/engine/classes/GenericResult.php +++ b/engine/classes/GenericResult.php @@ -2,8 +2,8 @@ /** * GenericResult Result superclass. * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage WebServicesAPI */ abstract class GenericResult { /** @@ -30,8 +30,10 @@ abstract class GenericResult { /** * Set a status code and optional message. * - * @param int $status The status code. + * @param int $status The status code. * @param string $message The message. + * + * @return void */ protected function setStatusCode($status, $message = "") { $this->status_code = $status; @@ -41,20 +43,37 @@ abstract class GenericResult { /** * Set the result. * - * @param mixed $result + * @param mixed $result The result + * + * @return void */ protected function setResult($result) { $this->result = $result; } + /** + * Return the current status code + * + * @return string + */ protected function getStatusCode() { return $this->status_code; } + /** + * Return the current status message + * + * @return string + */ protected function getStatusMessage() { return $this->message; } + /** + * Return the current result + * + * @return string + */ protected function getResult() { return $this->result; } @@ -68,11 +87,11 @@ abstract class GenericResult { * * Therefore, I'm not bothering. * - * Override this to include any more specific information, however api results should be attached to the - * class using setResult(). + * Override this to include any more specific information, however api results + * should be attached to the class using setResult(). * - * if $CONFIG->debug is set then additional information about the runtime environment and authentication will be - * returned. + * if $CONFIG->debug is set then additional information about the runtime environment and + * authentication will be returned. * * @return stdClass Object containing the serialised result. */ @@ -82,7 +101,7 @@ abstract class GenericResult { $result = new stdClass; $result->status = $this->getStatusCode(); - if ($this->getStatusMessage()!="") { + if ($this->getStatusMessage() != "") { $result->message = $this->getStatusMessage(); } diff --git a/engine/classes/IOException.php b/engine/classes/IOException.php index 77641c421..57403f44c 100644 --- a/engine/classes/IOException.php +++ b/engine/classes/IOException.php @@ -3,7 +3,7 @@ * IOException * An IO Exception, throw when an IO Exception occurs. Subclass for specific IO Exceptions. * - * @package Elgg - * @subpackage Exceptions + * @package Elgg.Core + * @subpackage Exception */ class IOException extends Exception {} diff --git a/engine/classes/ImportException.php b/engine/classes/ImportException.php index 946652cb4..14287fdf2 100644 --- a/engine/classes/ImportException.php +++ b/engine/classes/ImportException.php @@ -2,7 +2,7 @@ /** * Import exception * - * @package Elgg - * @subpackage Exceptions + * @package Elgg.Core + * @subpackage Exception */ class ImportException extends DataFormatException {}
\ No newline at end of file diff --git a/engine/classes/Importable.php b/engine/classes/Importable.php index 7eb984815..23b2ce2c8 100644 --- a/engine/classes/Importable.php +++ b/engine/classes/Importable.php @@ -1,13 +1,17 @@ <?php /** * Define an interface for all ODD importable objects. + * + * @package Elgg.Core + * @subpackage DataModel.Importable */ interface Importable { /** * Accepts an array of data to import, this data is parsed from the XML produced by export. * The function should return the constructed object data, or NULL. * - * @param ODD $data + * @param ODD $data Data in ODD format + * * @return bool * @throws ImportException if there was a critical error importing data. */ diff --git a/engine/classes/InstallationException.php b/engine/classes/InstallationException.php index 4284b3a2d..1dad6c1e5 100644 --- a/engine/classes/InstallationException.php +++ b/engine/classes/InstallationException.php @@ -3,7 +3,7 @@ * InstallationException * Thrown when there is a major problem with the installation. * - * @package Elgg - * @subpackage Exceptions + * @package Elgg.Core + * @subpackage Exception */ class InstallationException extends ConfigurationException {} diff --git a/engine/classes/InvalidClassException.php b/engine/classes/InvalidClassException.php index 5ea347238..12f353b9a 100644 --- a/engine/classes/InvalidClassException.php +++ b/engine/classes/InvalidClassException.php @@ -3,7 +3,7 @@ * InvalidClassException * An invalid class Exception, throw when a class is invalid. * - * @package Elgg - * @subpackage Exceptions + * @package Elgg.Core + * @subpackage Exception */ class InvalidClassException extends ClassException {} diff --git a/engine/classes/InvalidParameterException.php b/engine/classes/InvalidParameterException.php index b7c778100..fbc9bffc9 100644 --- a/engine/classes/InvalidParameterException.php +++ b/engine/classes/InvalidParameterException.php @@ -3,7 +3,7 @@ * InvalidParameterException * A parameter is invalid. * - * @package Elgg - * @subpackage Exceptions + * @package Elgg.Core + * @subpackage Exception */ class InvalidParameterException extends CallException {} diff --git a/engine/classes/Locatable.php b/engine/classes/Locatable.php index de191ff43..980256cbb 100644 --- a/engine/classes/Locatable.php +++ b/engine/classes/Locatable.php @@ -3,34 +3,47 @@ /** * Define an interface for geo-tagging entities. * + * @package Elgg.Core + * @subpackage SocialModel.Locatable */ interface Locatable { - /** Set a location text */ + /** + * Set a location text + * + * @param string $location Textual representation of location + * + * @return bool + **/ public function setLocation($location); /** * Set latitude and longitude tags for a given entity. * - * @param float $lat - * @param float $long + * @param float $lat Latitude + * @param float $long Longitude + * + * @return bool */ public function setLatLong($lat, $long); /** * Get the contents of the ->geo:lat field. * + * @return int */ public function getLatitude(); /** * Get the contents of the ->geo:lat field. * + * @return int */ public function getLongitude(); /** * Get the ->location metadata. * + * @return string */ public function getLocation(); }
\ No newline at end of file diff --git a/engine/classes/Loggable.php b/engine/classes/Loggable.php index 6f9559849..98d131f38 100644 --- a/engine/classes/Loggable.php +++ b/engine/classes/Loggable.php @@ -3,11 +3,14 @@ * Interface that provides an interface which must be implemented by all objects wishing to be * recorded in the system log (and by extension the river). * - * This interface defines a set of methods that permit the system log functions to hook in and retrieve - * the necessary information and to identify what events can actually be logged. + * This interface defines a set of methods that permit the system log functions to + * hook in and retrieve the necessary information and to identify what events can + * actually be logged. * * To have events involving your object to be logged simply implement this interface. * + * @package Elgg.Core + * @subpackage DataModel.Loggable */ interface Loggable { /** @@ -21,16 +24,23 @@ interface Loggable { /** * Return the class name of the object. * Added as a function because get_class causes errors for some reason. + * + * @return string */ public function getClassName(); /** * Return the type of the object - eg. object, group, user, relationship, metadata, annotation etc + * + * @return string */ public function getType(); /** - * Return a subtype. For metadata & annotations this is the 'name' and for relationship this is the relationship type. + * Return a subtype. For metadata & annotations this is the 'name' and for relationship this is the + * relationship type. + * + * @return string */ public function getSubtype(); @@ -38,11 +48,17 @@ interface Loggable { * For a given ID, return the object associated with it. * This is used by the river functionality primarily. * This is useful for checking access permissions etc on objects. + * + * @param int $id GUID of an entity + * + * @return ElggEntity */ public function getObjectFromID($id); /** * Return the GUID of the owner of this object. + * + * @return int */ public function getObjectOwnerGUID(); }
\ No newline at end of file diff --git a/engine/classes/NotImplementedException.php b/engine/classes/NotImplementedException.php index 1937665e0..d1decf75c 100644 --- a/engine/classes/NotImplementedException.php +++ b/engine/classes/NotImplementedException.php @@ -1,10 +1,10 @@ <?php /** * NotImplementedException - * Thrown when a method or function has not been implemented, primarily used in development... you should - * not see these! + * Thrown when a method or function has not been implemented, primarily used + * in development... you should not see these! * - * @package Elgg - * @subpackage Exceptions + * @package Elgg.Core + * @subpackage Exception */ class NotImplementedException extends CallException {} diff --git a/engine/classes/Notable.php b/engine/classes/Notable.php index ae88b521f..e36699dfc 100644 --- a/engine/classes/Notable.php +++ b/engine/classes/Notable.php @@ -2,29 +2,40 @@ /** * Calendar interface for events. * + * @package Elgg.Core + * @subpackage DataModel.Notable + * + * @todo Implement or remove. */ interface Notable { /** * Calendar functionality. * This function sets the time of an object on a calendar listing. * - * @param int $hour If ommitted, now is assumed. - * @param int $minute If ommitted, now is assumed. - * @param int $second If ommitted, now is assumed. - * @param int $day If ommitted, now is assumed. - * @param int $month If ommitted, now is assumed. - * @param int $year If ommitted, now is assumed. + * @param int $hour If ommitted, now is assumed. + * @param int $minute If ommitted, now is assumed. + * @param int $second If ommitted, now is assumed. + * @param int $day If ommitted, now is assumed. + * @param int $month If ommitted, now is assumed. + * @param int $year If ommitted, now is assumed. * @param int $duration Duration of event, remainder of the day is assumed. + * + * @return bool */ - public function setCalendarTimeAndDuration($hour = NULL, $minute = NULL, $second = NULL, $day = NULL, $month = NULL, $year = NULL, $duration = NULL); + public function setCalendarTimeAndDuration($hour = NULL, $minute = NULL, $second = NULL, + $day = NULL, $month = NULL, $year = NULL, $duration = NULL); /** * Return the start timestamp. + * + * @return int */ public function getCalendarStartTime(); /** * Return the end timestamp. + * + * @return int */ public function getCalendarEndTime(); }
\ No newline at end of file diff --git a/engine/classes/NotificationException.php b/engine/classes/NotificationException.php index 7da062319..71c742f17 100644 --- a/engine/classes/NotificationException.php +++ b/engine/classes/NotificationException.php @@ -1,5 +1,8 @@ <?php /** * Notification exception. + * + * @package Elgg.Core + * @subpackage Exception */ class NotificationException extends Exception {} diff --git a/engine/classes/ODD.php b/engine/classes/ODD.php index 1d553c7c4..fa5b616fc 100644 --- a/engine/classes/ODD.php +++ b/engine/classes/ODD.php @@ -1,8 +1,9 @@ <?php /** * Open Data Definition (ODD) superclass. - * @package Elgg - * @subpackage Core + * + * @package Elgg.Core + * @subpackage ODD */ abstract class ODD { /** @@ -22,14 +23,34 @@ abstract class ODD { $this->body = ""; } + /** + * Returns an array of attributes + * + * @return array + */ public function getAttributes() { return $this->attributes; } + /** + * Sets an attribute + * + * @param string $key Name + * @param mixed $value Value + * + * @return void + */ public function setAttribute($key, $value) { $this->attributes[$key] = $value; } + /** + * Returns an attribute + * + * @param string $key Name + * + * @return mixed + */ public function getAttribute($key) { if (isset($this->attributes[$key])) { return $this->attributes[$key]; @@ -38,10 +59,22 @@ abstract class ODD { return NULL; } + /** + * Sets the body of the ODD. + * + * @param mixed $value Value + * + * @return void + */ public function setBody($value) { $this->body = $value; } + /** + * Gets the body of the ODD. + * + * @return mixed + */ public function getBody() { return $this->body; } @@ -50,6 +83,8 @@ abstract class ODD { * Set the published time. * * @param int $time Unix timestamp + * + * @return void */ public function setPublished($time) { $this->attributes['published'] = date("r", $time); @@ -66,25 +101,28 @@ abstract class ODD { /** * For serialisation, implement to return a string name of the tag eg "header" or "metadata". + * * @return string */ abstract protected function getTagName(); /** * Magic function to generate valid ODD XML for this item. + * + * @return string */ public function __toString() { // Construct attributes $attr = ""; foreach ($this->attributes as $k => $v) { - $attr .= ($v!="") ? "$k=\"$v\" " : ""; + $attr .= ($v != "") ? "$k=\"$v\" " : ""; } $body = $this->getBody(); $tag = $this->getTagName(); $end = "/>"; - if ($body!="") { + if ($body != "") { $end = "><![CDATA[$body]]></{$tag}>"; } diff --git a/engine/classes/ODDDocument.php b/engine/classes/ODDDocument.php index d5619ce46..4d185aba5 100644 --- a/engine/classes/ODDDocument.php +++ b/engine/classes/ODDDocument.php @@ -1,7 +1,9 @@ <?php /** - * @class ODDDocument ODD Document container. * This class is used during import and export to construct. + * + * @package Elgg.Core + * @subpackage ODD */ class ODDDocument implements Iterator { /** @@ -21,6 +23,13 @@ class ODDDocument implements Iterator { */ private $wrapperfactory; + /** + * Create a new ODD Document. + * + * @param array $elements Elements to add + * + * @return void + */ public function __construct(array $elements = NULL) { if ($elements) { if (is_array($elements)) { @@ -42,10 +51,22 @@ class ODDDocument implements Iterator { return $this->ODDSupportedVersion; } + /** + * Returns the number of elements + * + * @return int + */ public function getNumElements() { return count($this->elements); } + /** + * Add an element + * + * @param ODD $element An ODD element + * + * @return void + */ public function addElement(ODD $element) { if (!is_array($this->elements)) { $this->elements = array(); @@ -53,18 +74,34 @@ class ODDDocument implements Iterator { } } + /** + * Add multiple elements at once + * + * @param array $elements Array of ODD elements + * + * @return void + */ public function addElements(array $elements) { foreach ($elements as $element) { $this->addElement($element); } } + /** + * Return all elements + * + * @return array + */ public function getElements() { return $this->elements; } /** * Set an optional wrapper factory to optionally embed the ODD document in another format. + * + * @param ODDWrapperFactory $factory The factory + * + * @return void */ public function setWrapperFactory(ODDWrapperFactory $factory) { $this->wrapperfactory = $factory; @@ -72,6 +109,8 @@ class ODDDocument implements Iterator { /** * Magic function to generate valid ODD XML for this item. + * + * @return string */ public function __toString() { $xml = ""; @@ -106,22 +145,57 @@ class ODDDocument implements Iterator { private $valid = FALSE; + /** + * Iterator interface + * + * @see Iterator::rewind() + * + * @return void + */ function rewind() { $this->valid = (FALSE !== reset($this->elements)); } + /** + * Iterator interface + * + * @see Iterator::current() + * + * @return void + */ function current() { return current($this->elements); } + /** + * Iterator interface + * + * @see Iterator::key() + * + * @return void + */ function key() { return key($this->elements); } + /** + * Iterator interface + * + * @see Iterator::next() + * + * @return void + */ function next() { $this->valid = (FALSE !== next($this->elements)); } + /** + * Iterator interface + * + * @see Iterator::valid() + * + * @return void + */ function valid() { return $this->valid; } diff --git a/engine/classes/ODDEntity.php b/engine/classes/ODDEntity.php index 727c96733..acdfe2f71 100644 --- a/engine/classes/ODDEntity.php +++ b/engine/classes/ODDEntity.php @@ -2,10 +2,19 @@ /** * ODD Entity class. - * @package Elgg - * @subpackage Core + * + * @package Elgg.Core + * @subpackage ODD */ class ODDEntity extends ODD { + + /** + * New ODD Entity + * + * @param string $uuid A universally unique ID + * @param string $class Class + * @param string $subclass Subclass + */ function __construct($uuid, $class, $subclass = "") { parent::__construct(); @@ -14,15 +23,34 @@ class ODDEntity extends ODD { $this->setAttribute('subclass', $subclass); } - protected function getTagName() { return "entity"; } + /** + * Returns entity. + * + * @return 'entity' + */ + protected function getTagName() { + return "entity"; + } } /** * ODD Metadata class. - * @package Elgg - * @subpackage Core + * + * @package Elgg.Core + * @subpackage ODD */ class ODDMetaData extends ODD { + + /** + * New ODD metadata + * + * @param unknown_type $uuid Unique ID + * @param unknown_type $entity_uuid Another unique ID + * @param unknown_type $name Name + * @param unknown_type $value Value + * @param unknown_type $type Type + * @param unknown_type $owner_uuid Owner ID + */ function __construct($uuid, $entity_uuid, $name, $value, $type = "", $owner_uuid = "") { parent::__construct(); @@ -34,6 +62,11 @@ class ODDMetaData extends ODD { $this->setBody($value); } + /** + * Returns 'metadata' + * + * @return 'metadata' + */ protected function getTagName() { return "metadata"; } @@ -41,10 +74,19 @@ class ODDMetaData extends ODD { /** * ODD Relationship class. - * @package Elgg + * + * @package Elgg * @subpackage Core */ class ODDRelationship extends ODD { + + /** + * New ODD Relationship + * + * @param unknown_type $uuid1 First UUID + * @param unknown_type $type Type of telationship + * @param unknown_type $uuid2 Second UUId + */ function __construct($uuid1, $type, $uuid2) { parent::__construct(); @@ -53,5 +95,12 @@ class ODDRelationship extends ODD { $this->setAttribute('uuid2', $uuid2); } - protected function getTagName() { return "relationship"; } + /** + * Returns 'relationship' + * + * @return 'relationship' + */ + protected function getTagName() { + return "relationship"; + } }
\ No newline at end of file diff --git a/engine/classes/PluginException.php b/engine/classes/PluginException.php index d81a921a9..56cf29596 100644 --- a/engine/classes/PluginException.php +++ b/engine/classes/PluginException.php @@ -2,9 +2,10 @@ /** * PluginException * - * A plugin Exception, thrown when an Exception occurs relating to the plugin mechanism. Subclass for specific plugin Exceptions. + * A plugin Exception, thrown when an Exception occurs relating to the plugin mechanism. + * Subclass for specific plugin Exceptions. * - * @package Elgg - * @subpackage Exceptions + * @package Elgg.Core + * @subpackage Exception */ class PluginException extends Exception {}
\ No newline at end of file diff --git a/engine/classes/RegistrationException.php b/engine/classes/RegistrationException.php index df77df158..05af35a01 100644 --- a/engine/classes/RegistrationException.php +++ b/engine/classes/RegistrationException.php @@ -3,7 +3,7 @@ * RegistrationException * Could not register a new user for whatever reason. * - * @package Elgg + * @package Elgg.Core * @subpackage Exceptions */ class RegistrationException extends InstallationException {}
\ No newline at end of file diff --git a/engine/classes/SecurityException.php b/engine/classes/SecurityException.php index c38209de8..3b6382f9e 100644 --- a/engine/classes/SecurityException.php +++ b/engine/classes/SecurityException.php @@ -1,9 +1,10 @@ <?php /** * SecurityException - * An Security Exception, throw when a Security Exception occurs. Subclass for specific Security Execeptions (access problems etc) + * An Security Exception, throw when a Security Exception occurs. Subclass for + * specific Security Execeptions (access problems etc) * - * @package Elgg - * @subpackage Exceptions + * @package Elgg.Core + * @subpackage Exception */ class SecurityException extends Exception {} diff --git a/engine/classes/SuccessResult.php b/engine/classes/SuccessResult.php index a554d9b1b..f68ddd39e 100644 --- a/engine/classes/SuccessResult.php +++ b/engine/classes/SuccessResult.php @@ -3,17 +3,30 @@ * SuccessResult * Generic success result class, extend if you want to do something special. * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage WebServicesAPI */ class SuccessResult extends GenericResult { - public static $RESULT_SUCCESS = 0; // Do not change this from 0 + // Do not change this from 0 + public static $RESULT_SUCCESS = 0; + /** + * A new success result + * + * @param string $result The result + */ public function SuccessResult($result) { $this->setResult($result); $this->setStatusCode(SuccessResult::$RESULT_SUCCESS); } + /** + * Returns a new instance of this class + * + * @param unknown $result A result of some kind? + * + * @return SuccessResult + */ public static function getInstance($result) { // Return a new error object. return new SuccessResult($result); diff --git a/engine/classes/XMLRPCArrayParameter.php b/engine/classes/XMLRPCArrayParameter.php index 2d0a2b49a..c0d358d5a 100644 --- a/engine/classes/XMLRPCArrayParameter.php +++ b/engine/classes/XMLRPCArrayParameter.php @@ -1,47 +1,56 @@ <?php /** - * @class XMLRPCArrayParameter An array containing other XMLRPCParameter objects. + * An array containing other XMLRPCParameter objects. + * + * @package Elgg.Core + * @subpackage XMLRPC + * */ class XMLRPCArrayParameter extends XMLRPCParameter { /** * Construct an array. * - * @param array $parameters Optional array of parameters, if not provided then addField must be used. + * @param array $parameters Optional array of parameters, if not provided + * then addField must be used. */ - function __construct($parameters = NULL) - { + function __construct($parameters = NULL) { parent::__construct(); - - if (is_array($parameters)) - { - foreach ($parameters as $v) + + if (is_array($parameters)) { + foreach ($parameters as $v) { $this->addField($v); + } } } - + /** * Add a field to the container. * * @param XMLRPCParameter $value The value. + * + * @return void */ - public function addField(XMLRPCParameter $value) - { - if (!is_array($this->value)) + public function addField(XMLRPCParameter $value) { + if (!is_array($this->value)) { $this->value = array(); - + } + $this->value[] = $value; } - - function __toString() - { + + /** + * Converts XML array to string + * + * @return string + */ + function __toString() { $params = ""; - foreach ($this->value as $value) - { + foreach ($this->value as $value) { $params .= "$value"; } - + return "<array><data>$params</data></array>"; } }
\ No newline at end of file diff --git a/engine/classes/XMLRPCBase64Parameter.php b/engine/classes/XMLRPCBase64Parameter.php index 461c10959..eb82b24a8 100644 --- a/engine/classes/XMLRPCBase64Parameter.php +++ b/engine/classes/XMLRPCBase64Parameter.php @@ -1,23 +1,28 @@ <?php /** - * @class XMLRPCBase64Parameter A base 64 encoded blob of binary. + * A base 64 encoded blob of binary. + * + * @package Elgg.Core + * @subpackage XMLRPC */ -class XMLRPCBase64Parameter extends XMLRPCParameter -{ +class XMLRPCBase64Parameter extends XMLRPCParameter { /** * Construct a base64 encoded block * * @param string $blob Unencoded binary blob */ - function __construct($blob) - { + function __construct($blob) { parent::__construct(); - + $this->value = base64_encode($blob); } - - function __toString() - { + + /** + * Convert to string + * + * @return string + */ + function __toString() { return "<value><base64>{$value}</base64></value>"; } }
\ No newline at end of file diff --git a/engine/classes/XMLRPCBoolParameter.php b/engine/classes/XMLRPCBoolParameter.php index f9b3ec316..c53d9ad14 100644 --- a/engine/classes/XMLRPCBoolParameter.php +++ b/engine/classes/XMLRPCBoolParameter.php @@ -1,18 +1,29 @@ <?php /** - * @class XMLRPCBoolParameter A boolean. + * A boolean. + * + * @package Elgg.Core + * @subpackage XMLRPC */ -class XMLRPCBoolParameter extends XMLRPCParameter -{ - function __construct($value) - { +class XMLRPCBoolParameter extends XMLRPCParameter { + + /** + * New bool parameter + * + * @param bool $value Value + */ + function __construct($value) { parent::__construct(); - - $this->value = (bool)$value; + + $this->value = (bool)$value; } - - function __toString() - { + + /** + * Convert to string + * + * @return string + */ + function __toString() { $code = ($this->value) ? "1" : "0"; return "<value><boolean>{$code}</boolean></value>"; } diff --git a/engine/classes/XMLRPCCall.php b/engine/classes/XMLRPCCall.php index 047f36d7b..3b33f3cee 100644 --- a/engine/classes/XMLRPCCall.php +++ b/engine/classes/XMLRPCCall.php @@ -1,59 +1,62 @@ <?php /** - * @class XMLRPCCall - * This class represents + * An XMLRPC call + * + * @package Elgg.Core + * @subpackage XMLRPC */ -class XMLRPCCall -{ +class XMLRPCCall { /** Method name */ private $methodname; + /** Parameters */ private $params; - + /** * Construct a new XML RPC Call * - * @param string $xml + * @param string $xml XML */ - function __construct($xml) - { - $this->parse($xml); + function __construct($xml) { + $this->_parse($xml); } - + /** * Return the method name associated with the call. * * @return string */ public function getMethodName() { return $this->methodname; } - + /** * Return the parameters. * Returns a nested array of XmlElement. - * - * @see XmlElement + * + * @see XmlElement * @return array */ public function getParameters() { return $this->params; } - + /** - * Parse the xml into its components according to spec. - * This first version is a little primitive. + * Parse the xml into its components according to spec. + * This first version is a little primitive. + * + * @param string $xml XML * - * @param string $xml + * @return void */ - private function parse($xml) - { + private function _parse($xml) { $xml = xml_to_object($xml); - + // sanity check - if ((isset($xml->name)) && (strcasecmp($xml->name, "methodCall")!=0)) + if ((isset($xml->name)) && (strcasecmp($xml->name, "methodCall") != 0)) { throw new CallException(elgg_echo('CallException:NotRPCCall')); - + } + // method name $this->methodname = $xml->children[0]->content; - - // parameters - $this->params = $xml->children[1]->children; + + // parameters + $this->params = $xml->children[1]->children; } }
\ No newline at end of file diff --git a/engine/classes/XMLRPCDateParameter.php b/engine/classes/XMLRPCDateParameter.php index 39a849fe2..35e02fb37 100644 --- a/engine/classes/XMLRPCDateParameter.php +++ b/engine/classes/XMLRPCDateParameter.php @@ -1,25 +1,32 @@ <?php /** - * @class XMLRPCDateParameter An ISO8601 data and time. + * An ISO8601 data and time. + * + * @package Elgg.Core + * @subpackage XMLRPC */ -class XMLRPCDateParameter extends XMLRPCParameter -{ +class XMLRPCDateParameter extends XMLRPCParameter { /** * Construct a date * * @param int $timestamp The unix timestamp, or blank for "now". */ - function __construct($timestamp = 0) - { + function __construct($timestamp = 0) { parent::__construct(); - + $this->value = $timestamp; - if (!$timestamp) - $this->value = time(); + + if (!$timestamp) { + $this->value = time(); + } } - - function __toString() - { + + /** + * Convert to string + * + * @return string + */ + function __toString() { $value = date('c', $this->value); return "<value><dateTime.iso8601>{$value}</dateTime.iso8601></value>"; } diff --git a/engine/classes/XMLRPCDoubleParameter.php b/engine/classes/XMLRPCDoubleParameter.php index c2e346b37..b7834650e 100644 --- a/engine/classes/XMLRPCDoubleParameter.php +++ b/engine/classes/XMLRPCDoubleParameter.php @@ -1,18 +1,29 @@ <?php /** - * @class XMLRPCDoubleParameter A double precision signed floating point number. + * A double precision signed floating point number. + * + * @package Elgg.Core + * @subpackage XMLRPC */ -class XMLRPCDoubleParameter extends XMLRPCParameter -{ - function __construct($value) - { +class XMLRPCDoubleParameter extends XMLRPCParameter { + + /** + * New XML Double + * + * @param int $value Value + */ + function __construct($value) { parent::__construct(); - - $this->value = (float)$value; + + $this->value = (float)$value; } - - function __toString() - { + + /** + * Convert to string + * + * @return string + */ + function __toString() { return "<value><double>{$this->value}</double></value>"; } } diff --git a/engine/classes/XMLRPCErrorResponse.php b/engine/classes/XMLRPCErrorResponse.php index c52601d3a..c3dbd0373 100644 --- a/engine/classes/XMLRPCErrorResponse.php +++ b/engine/classes/XMLRPCErrorResponse.php @@ -1,18 +1,20 @@ <?php /** - * @class XMLRPCErrorResponse + * XMLRPC Error Response + * + * @package Elgg.Core + * @subpackage XMLRPC */ -class XMLRPCErrorResponse extends XMLRPCResponse -{ +class XMLRPCErrorResponse extends XMLRPCResponse { /** * Set the error response and error code. * * @param string $message The message - * @param int $code Error code (default = system error as defined by http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php) + * @param int $code Error code (default = system error as defined by + * http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php) */ - function __construct($message, $code = -32400) - { + function __construct($message, $code = -32400) { $this->addParameter( new XMLRPCStructParameter( array ( @@ -22,12 +24,13 @@ class XMLRPCErrorResponse extends XMLRPCResponse ) ); } - + /** * Output to XML. + * + * @return string */ - public function __toString() - { + public function __toString() { return "<methodResponse><fault><value>{$this->parameters[0]}</value></fault></methodResponse>"; } }
\ No newline at end of file diff --git a/engine/classes/XMLRPCIntParameter.php b/engine/classes/XMLRPCIntParameter.php index ef950bc14..0fc146165 100644 --- a/engine/classes/XMLRPCIntParameter.php +++ b/engine/classes/XMLRPCIntParameter.php @@ -1,18 +1,29 @@ <?php /** - * @class XMLRPCIntParameter An Integer. + * An Integer. + * + * @package Elgg.Core + * @subpackage XMLRPC */ -class XMLRPCIntParameter extends XMLRPCParameter -{ - function __construct($value) - { +class XMLRPCIntParameter extends XMLRPCParameter { + + /** + * A new XML int + * + * @param int $value Value + */ + function __construct($value) { parent::__construct(); - - $this->value = (int)$value; + + $this->value = (int)$value; } - - function __toString() - { + + /** + * Convert to string + * + * @return string + */ + function __toString() { return "<value><i4>{$this->value}</i4></value>"; } } diff --git a/engine/classes/XMLRPCParameter.php b/engine/classes/XMLRPCParameter.php index cbec2c1a2..5fac33201 100644 --- a/engine/classes/XMLRPCParameter.php +++ b/engine/classes/XMLRPCParameter.php @@ -1,11 +1,16 @@ <?php /** - * @class XMLRPCParameter Superclass for all RPC parameters. + * Superclass for all RPC parameters. + * + * @package Elgg.Core + * @subpackage XMLRPC */ -abstract class XMLRPCParameter -{ +abstract class XMLRPCParameter { protected $value; + /** + * Set initial values + */ function __construct() { } - + }
\ No newline at end of file diff --git a/engine/classes/XMLRPCResponse.php b/engine/classes/XMLRPCResponse.php index 22fd9d421..2a0319431 100644 --- a/engine/classes/XMLRPCResponse.php +++ b/engine/classes/XMLRPCResponse.php @@ -1,28 +1,71 @@ <?php /** - * @class XMLRPCResponse XML-RPC Response. + * XML-RPC Response. + * + * @package Elgg.Core + * @subpackage XMLRPC */ -abstract class XMLRPCResponse -{ +abstract class XMLRPCResponse { /** An array of parameters */ protected $parameters = array(); - + /** * Add a parameter here. * * @param XMLRPCParameter $param The parameter. + * + * @return void */ - public function addParameter(XMLRPCParameter $param) - { - if (!is_array($this->parameters)) + public function addParameter(XMLRPCParameter $param) { + if (!is_array($this->parameters)) { $this->parameters = array(); - + } + $this->parameters[] = $param; } - public function addInt($value) { $this->addParameter(new XMLRPCIntParameter($value)); } - public function addString($value) { $this->addParameter(new XMLRPCStringParameter($value)); } - public function addDouble($value) { $this->addParameter(new XMLRPCDoubleParameter($value)); } - public function addBoolean($value) { $this->addParameter(new XMLRPCBoolParameter($value)); } + /** + * Add an integer + * + * @param int $value Value + * + * @return void + */ + public function addInt($value) { + $this->addParameter(new XMLRPCIntParameter($value)); + } + + /** + * Add a string + * + * @param string $value Value + * + * @return void + */ + public function addString($value) { + $this->addParameter(new XMLRPCStringParameter($value)); + } + + /** + * Add a double + * + * @param int $value Value + * + * @return void + */ + public function addDouble($value) { + $this->addParameter(new XMLRPCDoubleParameter($value)); + } + + /** + * Add a boolean + * + * @param bool $value Value + * + * @return void + */ + public function addBoolean($value) { + $this->addParameter(new XMLRPCBoolParameter($value)); + } }
\ No newline at end of file diff --git a/engine/classes/XMLRPCStringParameter.php b/engine/classes/XMLRPCStringParameter.php index 8381afb11..35b28214b 100644 --- a/engine/classes/XMLRPCStringParameter.php +++ b/engine/classes/XMLRPCStringParameter.php @@ -1,18 +1,29 @@ <?php /** - * @class XMLRPCStringParameter A string. + * A string. + * + * @package Elgg.Core + * @subpackage XMLRPC */ -class XMLRPCStringParameter extends XMLRPCParameter -{ - function __construct($value) - { +class XMLRPCStringParameter extends XMLRPCParameter { + + /** + * A new XML string + * + * @param string $value Value + */ + function __construct($value) { parent::__construct(); - - $this->value = $value; + + $this->value = $value; } - - function __toString() - { + + /** + * Convert to XML string + * + * @return string + */ + function __toString() { $value = htmlentities($this->value); return "<value><string>{$value}</string></value>"; } diff --git a/engine/classes/XMLRPCStructParameter.php b/engine/classes/XMLRPCStructParameter.php index 4f406abcb..754c92616 100644 --- a/engine/classes/XMLRPCStructParameter.php +++ b/engine/classes/XMLRPCStructParameter.php @@ -1,48 +1,55 @@ <?php /** - * @class XMLRPCStructParameter A structure containing other XMLRPCParameter objects. + * A structure containing other XMLRPCParameter objects. + * + * @package Elgg.Core + * @subpackage XMLRPC */ -class XMLRPCStructParameter extends XMLRPCParameter -{ +class XMLRPCStructParameter extends XMLRPCParameter { /** * Construct a struct. * - * @param array $parameters Optional associated array of parameters, if not provided then addField must be used. + * @param array $parameters Optional associated array of parameters, if + * not provided then addField must be used. */ - function __construct($parameters = NULL) - { + function __construct($parameters = NULL) { parent::__construct(); - - if (is_array($parameters)) - { - foreach ($parameters as $k => $v) + + if (is_array($parameters)) { + foreach ($parameters as $k => $v) { $this->addField($k, $v); + } } } - + /** * Add a field to the container. * - * @param string $name The name of the field. + * @param string $name The name of the field. * @param XMLRPCParameter $value The value. + * + * @return void */ - public function addField($name, XMLRPCParameter $value) - { - if (!is_array($this->value)) + public function addField($name, XMLRPCParameter $value) { + if (!is_array($this->value)) { $this->value = array(); - + } + $this->value[$name] = $value; } - - function __toString() - { + + /** + * Convert to string + * + * @return string + */ + function __toString() { $params = ""; - foreach ($this->value as $k => $v) - { + foreach ($this->value as $k => $v) { $params .= "<member><name>$k</name>$v</member>"; } - + return "<value><struct>$params</struct></value>"; } }
\ No newline at end of file diff --git a/engine/classes/XMLRPCSuccessResponse.php b/engine/classes/XMLRPCSuccessResponse.php index 8ac1eae4b..2f452ef42 100644 --- a/engine/classes/XMLRPCSuccessResponse.php +++ b/engine/classes/XMLRPCSuccessResponse.php @@ -1,18 +1,22 @@ <?php /** - * @class XMLRPCSuccessResponse + * Success Response + * + * @package Elgg.Core + * @subpackage XMLRPC */ -class XMLRPCSuccessResponse extends XMLRPCResponse -{ +class XMLRPCSuccessResponse extends XMLRPCResponse { /** * Output to XML. + * + * @return string */ - public function __toString() - { + public function __toString() { $params = ""; - foreach ($this->parameters as $param) + foreach ($this->parameters as $param) { $params .= "<param>$param</param>\n"; - + } + return "<methodResponse><params>$params</params></methodResponse>"; } }
\ No newline at end of file diff --git a/engine/classes/XmlElement.php b/engine/classes/XmlElement.php index b44023eb3..64d54e6b0 100644 --- a/engine/classes/XmlElement.php +++ b/engine/classes/XmlElement.php @@ -1,19 +1,20 @@ <?php /** - * @class XmlElement * A class representing an XML element for import. + * + * @package Elgg.Core + * @subpackage XML */ -class XmlElement -{ +class XmlElement { /** The name of the element */ public $name; - + /** The attributes */ public $attributes; - + /** CData */ public $content; - + /** Child elements */ public $children; };
\ No newline at end of file |