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 | |
| 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')
126 files changed, 7411 insertions, 3741 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 diff --git a/engine/handlers/xml-rpc_handler.php b/engine/handlers/xml-rpc_handler.php index 20f1c529c..996400647 100644 --- a/engine/handlers/xml-rpc_handler.php +++ b/engine/handlers/xml-rpc_handler.php @@ -15,10 +15,10 @@ global $CONFIG; // Register the error handler error_reporting(E_ALL); -set_error_handler('__php_xmlrpc_error_handler'); +set_error_handler('_php_xmlrpc_error_handler'); // Register a default exception handler -set_exception_handler('__php_xmlrpc_exception_handler'); +set_exception_handler('_php_xmlrpc_exception_handler'); // Set some defaults $result = null; diff --git a/engine/lib/access.php b/engine/lib/access.php index e34f7c021..5b67afbd1 100644 --- a/engine/lib/access.php +++ b/engine/lib/access.php @@ -15,12 +15,16 @@ * Return a string of access_ids for $user_id appropriate for inserting into an SQL IN clause. * * @uses get_access_array - * @param int $user_id User ID; defaults to currently logged in user - * @param int $site_id Site ID; defaults to current site - * @param boolean $flush If set to true, will refresh the access list from the database + * * @return string A list of access collections suitable for injection in an SQL call * @link http://docs.elgg.org/Access * @see get_access_array() + * + * @param int $user_id User ID; defaults to currently logged in user + * @param int $site_id Site ID; defaults to current site + * @param bool $flush If set to true, will refresh the access list from the database + * + * @return string */ function get_access_list($user_id = 0, $site_id = 0, $flush = false) { global $CONFIG, $init_finished, $SESSION; @@ -54,9 +58,10 @@ function get_access_list($user_id = 0, $site_id = 0, $flush = false) { * * Can be overridden with the access:collections:read, user plugin hook. * - * @param int $user_id User ID; defaults to currently logged in user - * @param int $site_id Site ID; defaults to current site - * @param boolean $flush If set to true, will refresh the access list from the database + * @param int $user_id User ID; defaults to currently logged in user + * @param int $site_id Site ID; defaults to current site + * @param boolean $flush If set to true, will refresh the access list from the database + * * @return array An array of access collections ids * @see get_access_list() */ @@ -90,12 +95,13 @@ function get_access_array($user_id = 0, $site_id = 0, $flush = false) { $tmp_access_array[] = ACCESS_LOGGED_IN; // Get ACL memberships - $query = "SELECT am.access_collection_id FROM {$CONFIG->dbprefix}access_collection_membership am "; - $query .= " LEFT JOIN {$CONFIG->dbprefix}access_collections ag ON ag.id = am.access_collection_id "; - $query .= " WHERE am.user_guid = {$user_id} AND (ag.site_guid = {$site_id} OR ag.site_guid = 0)"; + $query = "SELECT am.access_collection_id" + . " FROM {$CONFIG->dbprefix}access_collection_membership am" + . " LEFT JOIN {$CONFIG->dbprefix}access_collections ag ON ag.id = am.access_collection_id" + . " WHERE am.user_guid = {$user_id} AND (ag.site_guid = {$site_id} OR ag.site_guid = 0)"; if ($collections = get_data($query)) { - foreach($collections as $collection) { + foreach ($collections as $collection) { if (!empty($collection->access_collection_id)) { $tmp_access_array[] = $collection->access_collection_id; } @@ -103,11 +109,11 @@ function get_access_array($user_id = 0, $site_id = 0, $flush = false) { } // Get ACLs owned. - $query = "SELECT ag.id FROM {$CONFIG->dbprefix}access_collections ag "; - $query .= " WHERE ag.owner_guid = {$user_id} AND (ag.site_guid = {$site_id} OR ag.site_guid = 0)"; + $query = "SELECT ag.id FROM {$CONFIG->dbprefix}access_collections ag "; + $query .= "WHERE ag.owner_guid = {$user_id} AND (ag.site_guid = {$site_id} OR ag.site_guid = 0)"; if ($collections = get_data($query)) { - foreach($collections as $collection) { + foreach ($collections as $collection) { if (!empty($collection->id)) { $tmp_access_array[] = $collection->id; } @@ -130,7 +136,8 @@ function get_access_array($user_id = 0, $site_id = 0, $flush = false) { $tmp_access_array = $access_array[$user_id]; } - return trigger_plugin_hook('access:collections:read', 'user', array('user_id' => $user_id, 'site_id' => $site_id), $tmp_access_array); + $options = array('user_id' => $user_id, 'site_id' => $site_id); + return trigger_plugin_hook('access:collections:read', 'user', $options, $tmp_access_array); } /** @@ -138,6 +145,8 @@ function get_access_array($user_id = 0, $site_id = 0, $flush = false) { * * This returns the default access level for the site or optionally for the user. * + * @param ElggUser $user Get the user's default access. Defaults to logged in user. + * * @return int default access id (see ACCESS defines in elgglib.php) * @link http://docs.elgg.org/Access */ @@ -172,7 +181,10 @@ $ENTITY_SHOW_HIDDEN_OVERRIDE = false; * Show or hide disabled entities. * * @access private + * * @param bool $show_hidden Show disabled entities. + * + * @return void */ function access_show_hidden_entities($show_hidden) { global $ENTITY_SHOW_HIDDEN_OVERRIDE; @@ -198,10 +210,11 @@ function access_get_show_hidden_status() { * * @todo This is fairly generic so perhaps it could be moved to annotations.php * - * @param string $annotation_name name of the annotation - * @param string $entity_guid SQL string that evaluates to the GUID of the entity the annotation should be attached to - * @param string $owner_guid SQL string that evaluates to the GUID of the owner of the annotation - * @param boolean $exists If set to true, will return true if the annotation exists, otherwise returns false + * @param string $annotation_name Name of the annotation + * @param string $entity_guid SQL GUID of entity the annotation is attached to. + * @param string $owner_guid SQL string that evaluates to the GUID of the annotation owner + * @param boolean $exists If true, returns BOOL if the annotation exists + * * @return string An SQL fragment suitable for inserting into a WHERE clause * @todo Document and maybe even remove. At least rename to something that makes sense. */ @@ -234,7 +247,8 @@ END; * this will return blank. * * @param string $table_prefix Optional table. prefix for the access code. - * @param int $owner + * @param int $owner The guid to check access for. Defaults to logged in user. + * * @return string The SQL for a where clause * @access private */ @@ -269,7 +283,7 @@ function get_access_sql_suffix($table_prefix = '', $owner = null) { WHERE relationship='friend' AND guid_two=$owner )"; - $friends_bit = '('.$friends_bit.') OR '; + $friends_bit = '(' . $friends_bit . ') OR '; if ((isset($CONFIG->user_block_and_filter_enabled)) && ($CONFIG->user_block_and_filter_enabled)) { // check to see if the user is in the entity owner's block list @@ -297,9 +311,11 @@ function get_access_sql_suffix($table_prefix = '', $owner = null) { $sql = "$enemies_bit AND ($sql)"; } - if (!$ENTITY_SHOW_HIDDEN_OVERRIDE) + if (!$ENTITY_SHOW_HIDDEN_OVERRIDE) { $sql .= " and {$table_prefix}enabled='yes'"; - return '('.$sql.')'; + } + + return '(' . $sql . ')'; } /** @@ -312,7 +328,9 @@ function get_access_sql_suffix($table_prefix = '', $owner = null) { * to an entity that is currently loaded. * * @param ElggEntity $entity The entity to check access for. - * @param ElggUser $user Optionally the user to check access for. Defaults to the logged in user (which doesn't make sense). + * @param ElggUser $user Optionally user to check access for. Defaults to + * logged in user (which doesn't make sense). + * * @return boolean True if the user can access the entity * @link http://docs.elgg.org/Access */ @@ -339,9 +357,10 @@ function has_access_to_entity($entity, $user = null) { * Returns an array of access permissions that the user is allowed to save objects with. * Permissions are of the form ('id' => 'Description') * - * @param int $user_id The user's GUID. - * @param int $site_id The current site. - * @param true|false $flush If this is set to true, this will ignore any cached version + * @param int $user_id The user's GUID. + * @param int $site_id The current site. + * @param bool $flush If this is set to true, this will ignore any cached version + * * @return array List of access permissions * @link http://docs.elgg.org/Access */ @@ -367,12 +386,14 @@ function get_write_access_array($user_id = 0, $site_id = 0, $flush = false) { $query .= " AND (ag.owner_guid = {$user_id})"; $query .= " AND ag.id >= 3"; - $tmp_access_array = array( ACCESS_PRIVATE => elgg_echo("PRIVATE"), + $tmp_access_array = array( + ACCESS_PRIVATE => elgg_echo("PRIVATE"), ACCESS_FRIENDS => elgg_echo("access:friends:label"), ACCESS_LOGGED_IN => elgg_echo("LOGGED_IN"), - ACCESS_PUBLIC => elgg_echo("PUBLIC")); + ACCESS_PUBLIC => elgg_echo("PUBLIC") + ); if ($collections = get_data($query)) { - foreach($collections as $collection) { + foreach ($collections as $collection) { $tmp_access_array[$collection->id] = $collection->name; } } @@ -382,7 +403,9 @@ function get_write_access_array($user_id = 0, $site_id = 0, $flush = false) { $tmp_access_array = $access_array[$user_id]; } - $tmp_access_array = trigger_plugin_hook('access:collections:write', 'user', array('user_id' => $user_id, 'site_id' => $site_id), $tmp_access_array); + $options = array('user_id' => $user_id, 'site_id' => $site_id); + $tmp_access_array = trigger_plugin_hook('access:collections:write', 'user', + $options, $tmp_access_array); return $tmp_access_array; } @@ -396,9 +419,10 @@ function get_write_access_array($user_id = 0, $site_id = 0, $flush = false) { * @internal Access collections are stored in the access_collections table. * Memberships to collections are in access_collections_membership. * - * @param string $name The name of the collection. - * @param int $owner_guid The GUID of the owner (default: currently logged in user). - * @param int $site_guid The GUID of the site (default: current site). + * @param string $name The name of the collection. + * @param int $owner_guid The GUID of the owner (default: currently logged in user). + * @param int $site_guid The GUID of the site (default: current site). + * * @return int|false Depending on success (the collection ID if successful). * @link http://docs.elgg.org/Access/Collections * @see update_access_collection() @@ -448,8 +472,9 @@ function create_access_collection($name, $owner_guid = 0, $site_guid = 0) { * @note This will run all hooks associated with adding or removing * members to access collections. * - * @param int $collection_id The ID of the collection. - * @param array $members Array of member GUIDs + * @param int $collection_id The ID of the collection. + * @param array $members Array of member GUIDs + * * @return true|false Depending on success * @link http://docs.elgg.org/Access/Collections * @see add_user_to_access_collection() @@ -495,6 +520,7 @@ function update_access_collection($collection_id, $members) { * Deletes a specified access collection and its membership. * * @param int $collection_id The collection ID + * * @return bool * @link http://docs.elgg.org/Access/Collections * @see create_access_collection() @@ -511,8 +537,12 @@ function delete_access_collection($collection_id) { if (array_key_exists($collection_id, $collections)) { global $CONFIG; - delete_data("delete from {$CONFIG->dbprefix}access_collection_membership where access_collection_id = {$collection_id}"); - delete_data("delete from {$CONFIG->dbprefix}access_collections where id = {$collection_id}"); + $query = "delete from {$CONFIG->dbprefix}access_collection_membership" + . " where access_collection_id = {$collection_id}"; + delete_data($query); + + $query = "delete from {$CONFIG->dbprefix}access_collections where id = {$collection_id}"; + delete_data($query); return true; } else { return false; @@ -527,13 +557,15 @@ function delete_access_collection($collection_id) { * just the database row of the actual collection. * * @param int $collection_id The collection ID + * * @return array|false */ function get_access_collection($collection_id) { global $CONFIG; $collection_id = (int) $collection_id; - $get_collection = get_data_row("SELECT * FROM {$CONFIG->dbprefix}access_collections WHERE id = {$collection_id}"); + $query = "SELECT * FROM {$CONFIG->dbprefix}access_collections WHERE id = {$collection_id}"; + $get_collection = get_data_row($query); return $get_collection; } @@ -543,8 +575,9 @@ function get_access_collection($collection_id) { * * Emits the access:collections:add_user, collection plugin hook. * - * @param int $user_guid The GUID of the user to add + * @param int $user_guid The GUID of the user to add * @param int $collection_id The ID of the collection to add them to + * * @return true|false Depending on success * @link http://docs.elgg.org/Access/Collections * @see update_access_collection() @@ -555,8 +588,9 @@ function add_user_to_access_collection($user_guid, $collection_id) { $user_guid = (int) $user_guid; $collections = get_write_access_array(); - if (!($collection = get_access_collection($collection_id))) + if (!($collection = get_access_collection($collection_id))) { return false; + } if ((array_key_exists($collection_id, $collections) || $collection->owner_guid == 0) && $user = get_user($user_guid)) { @@ -572,7 +606,9 @@ function add_user_to_access_collection($user_guid, $collection_id) { } try { - insert_data("insert into {$CONFIG->dbprefix}access_collection_membership set access_collection_id = {$collection_id}, user_guid = {$user_guid}"); + $query = "insert into {$CONFIG->dbprefix}access_collection_membership" + . " set access_collection_id = {$collection_id}, user_guid = {$user_guid}"; + insert_data($queyr); } catch (DatabaseException $e) { // nothing. } @@ -588,19 +624,22 @@ function add_user_to_access_collection($user_guid, $collection_id) { * * Emits the access:collections:remove_user, collection plugin hook. * - * @param int $user_guid The user GUID + * @param int $user_guid The user GUID * @param int $collection_id The access collection ID + * * @return true|false Depending on success */ function remove_user_from_access_collection($user_guid, $collection_id) { $collection_id = (int) $collection_id; $user_guid = (int) $user_guid; $collections = get_write_access_array(); + $user = $user = get_user($user_guid); - if (!($collection = get_access_collection($collection_id))) + if (!($collection = get_access_collection($collection_id))) { return false; + } - if ((array_key_exists($collection_id, $collections) || $collection->owner_guid == 0) && $user = get_user($user_guid)) { + if ((array_key_exists($collection_id, $collections) || $collection->owner_guid == 0) && $user) { global $CONFIG; $params = array( 'collection_id' => $collection_id, @@ -611,7 +650,9 @@ function remove_user_from_access_collection($user_guid, $collection_id) { return false; } - delete_data("delete from {$CONFIG->dbprefix}access_collection_membership where access_collection_id = {$collection_id} and user_guid = {$user_guid}"); + delete_data("delete from {$CONFIG->dbprefix}access_collection_membership " + . "where access_collection_id = {$collection_id} and user_guid = {$user_guid}"); + return true; } @@ -623,7 +664,8 @@ function remove_user_from_access_collection($user_guid, $collection_id) { * Returns an array of database row objects of the access collections owned by $owner_guid. * * @param int $owner_guid The entity guid - * @param int $site_guid The GUID of the site (default: current site). + * @param int $site_guid The GUID of the site (default: current site). + * * @return array|false * @see add_access_collection() * @see get_members_of_access_collection() @@ -650,8 +692,9 @@ function get_user_access_collections($owner_guid, $site_guid = 0) { /** * Get all of members of an access collection * - * @param int $collection The collection's ID - * @param true|false $idonly If set to true, will only return the members' GUIDs (default: false) + * @param int $collection The collection's ID + * @param bool $idonly If set to true, will only return the members' GUIDs (default: false) + * * @return array ElggUser guids or entities if successful, false if not * @see add_user_to_access_collection() * @see http://docs.elgg.org/Access/Collections @@ -661,15 +704,19 @@ function get_members_of_access_collection($collection, $idonly = FALSE) { $collection = (int)$collection; if (!$idonly) { - $query = "SELECT e.* FROM {$CONFIG->dbprefix}access_collection_membership m JOIN {$CONFIG->dbprefix}entities e ON e.guid = m.user_guid WHERE m.access_collection_id = {$collection}"; + $query = "SELECT e.* FROM {$CONFIG->dbprefix}access_collection_membership m" + . " JOIN {$CONFIG->dbprefix}entities e ON e.guid = m.user_guid" + . " WHERE m.access_collection_id = {$collection}"; $collection_members = get_data($query, "entity_row_to_elggstar"); } else { - $query = "SELECT e.guid FROM {$CONFIG->dbprefix}access_collection_membership m JOIN {$CONFIG->dbprefix}entities e ON e.guid = m.user_guid WHERE m.access_collection_id = {$collection}"; + $query = "SELECT e.guid FROM {$CONFIG->dbprefix}access_collection_membership m" + . " JOIN {$CONFIG->dbprefix}entities e ON e.guid = m.user_guid" + . " WHERE m.access_collection_id = {$collection}"; $collection_members = get_data($query); if (!$collection_members) { return FALSE; } - foreach($collection_members as $key => $val) { + foreach ($collection_members as $key => $val) { $collection_members[$key] = $val->guid; } } @@ -681,12 +728,13 @@ function get_members_of_access_collection($collection, $idonly = FALSE) { * Displays a user's access collections, using the friends/collections view * * @param int $owner_guid The GUID of the owning user + * * @return string A formatted rendition of the collections * @todo Move to the friends/collection.php page. */ function elgg_view_access_collections($owner_guid) { if ($collections = get_user_access_collections($owner_guid)) { - foreach($collections as $key => $collection) { + foreach ($collections as $key => $collection) { $collections[$key]->members = get_members_of_access_collection($collection->id, true); $collections[$key]->entities = get_user_friends($owner_guid, "", 9999); } @@ -700,20 +748,22 @@ function elgg_view_access_collections($owner_guid) { * * @deprecated 1.7. Use elgg_get_entities_from_access_id() * - * @param $collection_id - * @param $entity_type - * @param $entity_subtype - * @param $owner_guid - * @param $limit - * @param $offset - * @param $order_by - * @param $site_guid - * @param $count - * @return unknown_type + * @param int $collection_id ID of collection + * @param string $entity_type Type of entities + * @param string $entity_subtype Subtype of entities + * @param int $owner_guid Guid of owner + * @param int $limit Limit of number of entities to return + * @param int $offset Skip this many entities + * @param string $order_by Column to order by + * @param int $site_guid The site guid + * @param bool $count Return a count or entities + * + * @return array */ -function get_entities_from_access_id($collection_id, $entity_type = "", $entity_subtype = "", $owner_guid = 0, $limit = 10, $offset = 0, $order_by = "", $site_guid = 0, $count = false) { +function get_entities_from_access_id($collection_id, $entity_type = "", $entity_subtype = "", + $owner_guid = 0, $limit = 10, $offset = 0, $order_by = "", $site_guid = 0, $count = false) { // log deprecated warning - elgg_deprecated_notice('get_entities_from_access_id() was deprecated by elgg_get_entities()!', 1.7); + elgg_deprecated_notice('get_entities_from_access_id() was deprecated by elgg_get_entities()', 1.7); if (!$collection_id) { return FALSE; @@ -763,11 +813,12 @@ function get_entities_from_access_id($collection_id, $entity_type = "", $entity_ * * @param array $options Any options accepted by {@link elgg_get_entities()} and: * access_id => int The access ID of the entity. + * * @see elgg_get_entities() * @return array * @since 1.7.0 */ -function elgg_get_entities_from_access_id(array $options=array()) { +function elgg_get_entities_from_access_id(array $options = array()) { // restrict the resultset to access collection provided if (!isset($options['access_id'])) { return FALSE; @@ -792,24 +843,29 @@ function elgg_get_entities_from_access_id(array $options=array()) { /** * Lists entities from an access collection * - * @param $collection_id - * @param $entity_type - * @param $entity_subtype - * @param $owner_guid - * @param $limit - * @param $fullview - * @param $viewtypetoggle - * @param $pagination + * @param int $collection_id ID of collection + * @param string $entity_type Type of entities + * @param string $entity_subtype Subtype of entities + * @param int $owner_guid Guid of owner + * @param int $limit Limit of number of entities to return + * @param bool $fullview Show a full view + * @param bool $viewtypetoggle Allow to toggle between views + * @param bool $pagination Show pagination + * * @return str * @todo deprecate with elgg_list_entities_from_access_id() function */ -function list_entities_from_access_id($collection_id, $entity_type = "", $entity_subtype = "", $owner_guid = 0, $limit = 10, $fullview = true, $viewtypetoggle = true, $pagination = true) { +function list_entities_from_access_id($collection_id, $entity_type = "", $entity_subtype = "", + $owner_guid = 0, $limit = 10, $fullview = true, $viewtypetoggle = true, $pagination = true) { $offset = (int) get_input('offset'); $limit = (int) $limit; - $count = get_entities_from_access_id($collection_id, $entity_type, $entity_subtype, $owner_guid, $limit, $offset, "", 0, true); - $entities = get_entities_from_access_id($collection_id, $entity_type, $entity_subtype, $owner_guid, $limit, $offset, "", 0, false); + $count = get_entities_from_access_id($collection_id, $entity_type, $entity_subtype, + $owner_guid, $limit, $offset, "", 0, true); + $entities = get_entities_from_access_id($collection_id, $entity_type, $entity_subtype, + $owner_guid, $limit, $offset, "", 0, false); - return elgg_view_entity_list($entities, $count, $offset, $limit, $fullview, $viewtypetoggle, $pagination); + return elgg_view_entity_list($entities, $count, $offset, $limit, + $fullview, $viewtypetoggle, $pagination); } /** @@ -818,21 +874,22 @@ function list_entities_from_access_id($collection_id, $entity_type = "", $entity * * @warning This function probably doesn't work how it's meant to. * - * @param $entity_accessid (int) The entity's access id + * @param int $entity_accessid The entity's access id + * * @return string e.g. Public, Private etc * @since 1.7.0 * @todo I think this probably wants get_access_array() instead of get_write_access_array(), * but those two functions return different types of arrays. */ -function get_readable_access_level($entity_accessid){ +function get_readable_access_level($entity_accessid) { $access = (int) $entity_accessid; //get the access level for object in readable string $options = get_write_access_array(); //@todo Really? Use array_key_exists() - foreach($options as $key => $option) { - if($key == $access){ + foreach ($options as $key => $option) { + if ($key == $access) { $entity_acl = htmlentities($option, ENT_QUOTES, 'UTF-8'); return $entity_acl; break; @@ -855,6 +912,8 @@ function get_readable_access_level($entity_accessid){ * @warning This will not show disabled entities. Use {@link $ENTITY_SHOW_HIDDEN_OVERRIDE} * for that. * + * @param bool $ignore If true, disables all access checks. + * * @return bool Previous ignore_access setting. * @since 1.7.0 * @see http://docs.elgg.org/Access/IgnoreAccess @@ -862,7 +921,7 @@ function get_readable_access_level($entity_accessid){ */ function elgg_set_ignore_access($ignore = true) { $elgg_access = elgg_get_access_object(); - return $elgg_access->set_ignore_access($ignore); + return $elgg_access->setIgnoreAccess($ignore); } /** @@ -874,7 +933,7 @@ function elgg_set_ignore_access($ignore = true) { * @see elgg_set_ignore_access() */ function elgg_get_ignore_access() { - return elgg_get_access_object()->get_ignore_access(); + return elgg_get_access_object()->getIgnoreAccess(); } /** @@ -883,6 +942,8 @@ function elgg_get_ignore_access() { * The access system can be ignored if 1) an admin user is logged in * or 2) {@link elgg_set_ignore_access()} was called with true. * + * @param mixed $user_guid The user to check against. Defaults to logged in. + * * @return bool * @since 1.7.0 */ @@ -929,6 +990,8 @@ $init_finished = false; * * @elgg_event_handler init system * @todo Invesigate + * + * @return void */ function access_init() { global $init_finished; @@ -945,7 +1008,7 @@ function access_init() { * @since 1.7.0 * @elgg_event_handler permissions_check all */ -function elgg_override_permissions_hook($hook, $type, $returnval, $params) { +function elgg_override_permissions_hook() { $user_guid = get_loggedin_userid(); // check for admin diff --git a/engine/lib/actions.php b/engine/lib/actions.php index 18475de27..63ddfcbfb 100644 --- a/engine/lib/actions.php +++ b/engine/lib/actions.php @@ -47,10 +47,13 @@ * @warning All actions require {@link http://docs.elgg.org/Actions/Tokens Action Tokens}. * @warning Most plugin shouldn't call this manually. * -* @param string $action The requested action +* @param string $action The requested action * @param string $forwarder Optionally, the location to forward to +* * @link http://docs.elgg.org/Actions * @see register_action() +* +* @return void */ function action($action, $forwarder = "") { global $CONFIG; @@ -142,12 +145,15 @@ function action($action, $forwarder = "") { * ) * </code> * - * @param string $action The name of the action (eg "register", "account/settings/save") - * @param boolean $public Can this action be accessed by people not logged into the system? - * @param string $filename Optionally, the filename where this action is located + * @param string $action The name of the action (eg "register", "account/settings/save") + * @param boolean $public Can this action be accessed by people not logged into the system? + * @param string $filename Optionally, the filename where this action is located * @param boolean $admin_only Whether this action is only available to admin users. + * * @see action() * @see http://docs.elgg.org/Actions + * + * @return true */ function register_action($action, $public = false, $filename = "", $admin_only = false) { global $CONFIG; @@ -169,7 +175,11 @@ function register_action($action, $public = false, $filename = "", $admin_only = $filename = $path . "actions/" . $action . ".php"; } - $CONFIG->actions[$action] = array('file' => $filename, 'public' => $public, 'admin' => $admin_only); + $CONFIG->actions[$action] = array( + 'file' => $filename, + 'public' => $public, + 'admin' => $admin_only + ); return true; } @@ -183,9 +193,11 @@ function register_action($action, $public = false, $filename = "", $admin_only = * Plugin authors should never have to manually validate action tokens. * * @access private - * @param bool $visibleerrors Emit {@link register_error()} errors on failure? - * @param mixed $token The token to test against. Pulls from $_REQUEST['__elgg_token'] if NULL. - * @param mixed $ts The time stamp to test against. Pulls from $_REQUEST['__elgg_ts'] if NULL. + * + * @param bool $visibleerrors Emit {@link register_error()} errors on failure? + * @param mixed $token The token to test against. Default: $_REQUEST['__elgg_token'] + * @param mixed $ts The time stamp to test against. Default: $_REQUEST['__elgg_ts'] + * * @return bool * @see generate_action_token() * @link http://docs.elgg.org/Actions/Tokens @@ -207,11 +219,11 @@ function validate_action_token($visibleerrors = TRUE, $token = NULL, $ts = NULL) // Validate token if ($token == $generated_token) { - $hour = 60*60; + $hour = 60 * 60; $now = time(); // Validate time to ensure its not crazy - if (($ts>$now-$hour) && ($ts<$now+$hour)) { + if (($ts > $now - $hour) && ($ts < $now + $hour)) { // We have already got this far, so unless anything // else says something to the contry we assume we're ok $returnval = true; @@ -232,8 +244,7 @@ function validate_action_token($visibleerrors = TRUE, $token = NULL, $ts = NULL) } else if ($visibleerrors) { register_error(elgg_echo('actiongatekeeper:tokeninvalid')); } - } - else if ($visibleerrors) { + } else if ($visibleerrors) { register_error(elgg_echo('actiongatekeeper:missingfields')); } @@ -272,9 +283,12 @@ function action_gatekeeper() { * @warning Action tokens are required for all actions. * * @param int $timestamp Unix timestamp + * * @see @elgg_view input/securitytoken * @see @elgg_view input/form * @example actions/manual_tokens.php + * + * @return string|false */ function generate_action_token($timestamp) { $site_secret = get_site_secret(); @@ -299,7 +313,7 @@ function generate_action_token($timestamp) { * @todo Move to better file. */ function init_site_secret() { - $secret = md5(rand().microtime()); + $secret = md5(rand() . microtime()); if (datalist_set('__site_secret__', $secret)) { return $secret; } @@ -328,7 +342,8 @@ function get_site_secret() { /** * Check if an action is registered and its file exists. * - * @param string $action + * @param string $action Action name + * * @return BOOL * @since 1.8 */ diff --git a/engine/lib/admin.php b/engine/lib/admin.php index defeaa6e3..0f5a4f400 100644 --- a/engine/lib/admin.php +++ b/engine/lib/admin.php @@ -9,8 +9,8 @@ /** * Register an admin page with the admin panel. - * This function extends the view "admin/main" with the provided view. This view should provide a description - * and either a control or a link to. + * This function extends the view "admin/main" with the provided view. + * This view should provide a description and either a control or a link to. * * Usage: * - To add a control to the main admin panel then extend admin/main @@ -22,12 +22,13 @@ * At the moment this is essentially a wrapper around elgg_extend_view(). * * @param string $new_admin_view The view associated with the control you're adding - * @param string $view The view to extend, by default this is 'admin/main'. - * @param int $priority Optional priority to govern the appearance in the list. + * @param string $view The view to extend, by default this is 'admin/main'. + * @param int $priority Optional priority to govern the appearance in the list. + * + * @return void */ function extend_elgg_admin_page($new_admin_view, $view = 'admin/main', $priority = 500) { - elgg_deprecated_notice('extend_elgg_admin_page() does nothing now. Extend admin views manually. See http://docs.elgg.org/', 1.8); - //return elgg_extend_view($view, $new_admin_view, $priority); + elgg_deprecated_notice('extend_elgg_admin_page() does nothing. Extend admin views manually.', 1.8); } /** @@ -35,6 +36,7 @@ function extend_elgg_admin_page($new_admin_view, $view = 'admin/main', $priority * This is done in a separate function called from the admin * page handler because of performance concerns. * + * @return void */ function elgg_admin_add_plugin_settings_sidemenu() { global $CONFIG; @@ -75,9 +77,11 @@ function elgg_admin_add_plugin_settings_sidemenu() { * Used in conjuction with http://elgg.org/admin/section_id/child_section style * page handler. * - * @param string $section_id + * @param string $section_id The Unique ID of section * @param string $section_title Human readable section title. - * @param string $parent_id If a child section, the parent section id. + * @param string $parent_id If a child section, the parent section id. + * + * @return bool */ function elgg_add_admin_submenu_item($section_id, $section_title, $parent_id = NULL) { global $CONFIG; @@ -104,6 +108,8 @@ function elgg_add_admin_submenu_item($section_id, $section_title, $parent_id = N /** * Initialise the admin page. + * + * @return void */ function admin_init() { register_action('admin/user/ban', FALSE, "", TRUE); @@ -153,7 +159,9 @@ function admin_init() { /** * Handle admin pages. Expects corresponding views as admin/section/subsection * - * @param $page + * @param array $page Array of pages + * + * @return void */ function admin_settings_page_handler($page) { global $CONFIG; @@ -169,14 +177,16 @@ function admin_settings_page_handler($page) { // was going to fix this in the page_handler() function but // it's commented to explicitly return a string if there's a trailing / - if (empty($page[count($page)-1])) { + if (empty($page[count($page) - 1])) { array_pop($page); } $vars = array('page' => $page); // special page for plugin settings since we create the form for them - if ($page[0] == 'plugin_settings' && isset($page[1]) && elgg_view_exists("settings/{$page[1]}/edit")) { + if ($page[0] == 'plugin_settings' && isset($page[1]) + && elgg_view_exists("settings/{$page[1]}/edit")) { + $view = '/admin/components/plugin_settings'; $vars['plugin'] = $page[1]; $vars['entity'] = find_plugin_settings($page[1]); @@ -192,8 +202,6 @@ function admin_settings_page_handler($page) { $content = elgg_echo('admin:unknown_section'); } - //$body = elgg_view('admin/components/admin_page_layout', array('content' => $content, 'page' => $page)); - $notices_html = ''; if ($notices = elgg_get_admin_notices()) { foreach ($notices as $notice) { @@ -217,8 +225,10 @@ function admin_settings_page_handler($page) { * 'Before your users can use Twitter services on this site, you must set up * the Twitter API key in the <a href="link">Twitter Services Settings</a>'); * - * @param string $id A unique ID that your plugin can remember + * @param string $id A unique ID that your plugin can remember * @param string $message Body of the message + * + * @return boo */ function elgg_add_admin_notice($id, $message) { if ($id && $message) { @@ -245,13 +255,20 @@ function elgg_add_admin_notice($id, $message) { * } * * @param string $id The unique ID assigned in add_admin_notice() + * + * @return bool */ function elgg_delete_admin_notice($id) { if (!$id) { return FALSE; } $result = TRUE; - if ($notices = elgg_get_entities_from_metadata(array('metadata_name' => 'admin_notice_id', 'metadata_value' => $id))) { + $notices = elgg_get_entities_from_metadata(array( + 'metadata_name' => 'admin_notice_id', + 'metadata_value' => $id + )); + + if ($notices) { // in case a bad plugin adds many, let it remove them all at once. foreach ($notices as $notice) { $result = ($result && $notice->delete()); @@ -265,6 +282,8 @@ function elgg_delete_admin_notice($id) { * List all admin messages. * * @param int $limit Limit + * + * @return array List of admin notices */ function elgg_get_admin_notices($limit = 10) { return elgg_get_entities_from_metadata(array( @@ -276,7 +295,10 @@ function elgg_get_admin_notices($limit = 10) { /** * Check if an admin notice is currently active. + * * @param string $id The unique ID used to register the notice. + * + * @return bool */ function elgg_admin_notice_exists($id) { $notice = elgg_get_entities_from_metadata(array( diff --git a/engine/lib/annotations.php b/engine/lib/annotations.php index 3a8054b8c..48421b2d6 100644 --- a/engine/lib/annotations.php +++ b/engine/lib/annotations.php @@ -10,7 +10,8 @@ /** * Convert a database row to a new ElggAnnotation * - * @param stdClass $row + * @param stdClass $row Db row result object + * * @return ElggAnnotation */ function row_to_elggannotation($row) { @@ -24,7 +25,8 @@ function row_to_elggannotation($row) { /** * Get a specific annotation. * - * @param int $annotation_id + * @param int $annotation_id Annotation ID + * * @return ElggAnnotation */ function get_annotation($annotation_id) { @@ -33,21 +35,29 @@ function get_annotation($annotation_id) { $annotation_id = (int) $annotation_id; $access = get_access_sql_suffix("a"); - return row_to_elggannotation(get_data_row("SELECT a.*, n.string as name, v.string as value from {$CONFIG->dbprefix}annotations a JOIN {$CONFIG->dbprefix}metastrings n on a.name_id = n.id JOIN {$CONFIG->dbprefix}metastrings v on a.value_id = v.id where a.id=$annotation_id and $access")); + $query = "SELECT a.*, n.string as name, v.string as value" + . " from {$CONFIG->dbprefix}annotations a" + . " JOIN {$CONFIG->dbprefix}metastrings n on a.name_id = n.id" + . " JOIN {$CONFIG->dbprefix}metastrings v on a.value_id = v.id" + . " where a.id=$annotation_id and $access"; + + return row_to_elggannotation(get_data_row($query)); } /** * Create a new annotation. * - * @param int $entity_guid - * @param string $name - * @param string $value - * @param string $value_type - * @param int $owner_guid - * @param int $access_id + * @param int $entity_guid Entity Guid + * @param string $name Name of annotation + * @param string $value Value of annotation + * @param string $value_type Type of value + * @param int $owner_guid Owner of annotation + * @param int $access_id Access level of annotation + * * @return int|bool id on success or false on failure */ -function create_annotation($entity_guid, $name, $value, $value_type, $owner_guid, $access_id = ACCESS_PRIVATE) { +function create_annotation($entity_guid, $name, $value, $value_type, +$owner_guid, $access_id = ACCESS_PRIVATE) { global $CONFIG; $result = false; @@ -58,7 +68,7 @@ function create_annotation($entity_guid, $name, $value, $value_type, $owner_guid $value_type = detect_extender_valuetype($value, sanitise_string(trim($value_type))); $owner_guid = (int)$owner_guid; - if ($owner_guid==0) { + if ($owner_guid == 0) { $owner_guid = get_loggedin_userid(); } @@ -78,7 +88,7 @@ function create_annotation($entity_guid, $name, $value, $value_type, $owner_guid $entity = get_entity($entity_guid); - if (trigger_elgg_event('annotate',$entity->type,$entity)) { + if (trigger_elgg_event('annotate', $entity->type, $entity)) { system_log($entity, 'annotate'); // If ok then add it @@ -86,7 +96,7 @@ function create_annotation($entity_guid, $name, $value, $value_type, $owner_guid (entity_guid, name_id, value_id, value_type, owner_guid, time_created, access_id) VALUES ($entity_guid,'$name',$value,'$value_type', $owner_guid, $time, $access_id)"); - if ($result!==false) { + if ($result !== false) { $obj = get_annotation($result); if (trigger_elgg_event('create', 'annotation', $obj)) { return $result; @@ -104,12 +114,13 @@ function create_annotation($entity_guid, $name, $value, $value_type, $owner_guid /** * Update an annotation. * - * @param int $annotation_id - * @param string $name - * @param string $value - * @param string $value_type - * @param int $owner_guid - * @param int $access_id + * @param int $annotation_id Annotation ID + * @param string $name Name of annotation + * @param string $value Value of annotation + * @param string $value_type Type of value + * @param int $owner_guid Owner of annotation + * @param int $access_id Access level of annotation + * * @return bool */ function update_annotation($annotation_id, $name, $value, $value_type, $owner_guid, $access_id) { @@ -121,7 +132,7 @@ function update_annotation($annotation_id, $name, $value, $value_type, $owner_gu $value_type = detect_extender_valuetype($value, sanitise_string(trim($value_type))); $owner_guid = (int)$owner_guid; - if ($owner_guid==0) { + if ($owner_guid == 0) { $owner_guid = get_loggedin_userid(); } @@ -145,7 +156,7 @@ function update_annotation($annotation_id, $name, $value, $value_type, $owner_gu set value_id='$value', value_type='$value_type', access_id=$access_id, owner_guid=$owner_guid where id=$annotation_id and name_id='$name' and $access"); - if ($result!==false) { + if ($result !== false) { $obj = get_annotation($annotation_id); if (trigger_elgg_event('update', 'annotation', $obj)) { return true; @@ -161,18 +172,24 @@ function update_annotation($annotation_id, $name, $value, $value_type, $owner_gu /** * Get a list of annotations for a given object/user/annotation type. * - * @param int|array $entity_guid - * @param string $entity_type - * @param string $entity_subtype - * @param string $name - * @param mixed $value - * @param int|array $owner_guid - * @param int $limit - * @param int $offset - * @param string $order_by + * @param int|array $entity_guid GUID to return annotations of (falsey for any) + * @param string $entity_type Type of entity + * @param string $entity_subtype Subtype of entity + * @param string $name Name of annotation + * @param mixed $value Value of annotation + * @param int|array $owner_guid Owner(s) of annotation + * @param int $limit Limit + * @param int $offset Offset + * @param string $order_by Order annotations by SQL + * @param int $timelower Lower time limit + * @param int $timeupper Upper time limit + * @param int $entity_owner_guid Owner guid for the entity + * + * @return array */ function get_annotations($entity_guid = 0, $entity_type = "", $entity_subtype = "", $name = "", -$value = "", $owner_guid = 0, $limit = 10, $offset = 0, $order_by = "asc", $timelower = 0, $timeupper = 0, $entity_owner_guid = 0) { +$value = "", $owner_guid = 0, $limit = 10, $offset = 0, $order_by = "asc", $timelower = 0, +$timeupper = 0, $entity_owner_guid = 0) { global $CONFIG; $timelower = (int) $timelower; @@ -180,7 +197,7 @@ $value = "", $owner_guid = 0, $limit = 10, $offset = 0, $order_by = "asc", $time if (is_array($entity_guid)) { if (sizeof($entity_guid) > 0) { - foreach($entity_guid as $key => $val) { + foreach ($entity_guid as $key => $val) { $entity_guid[$key] = (int) $val; } } else { @@ -212,7 +229,7 @@ $value = "", $owner_guid = 0, $limit = 10, $offset = 0, $order_by = "asc", $time if (is_array($owner_guid)) { if (sizeof($owner_guid) > 0) { - foreach($owner_guid as $key => $val) { + foreach ($owner_guid as $key => $val) { $owner_guid[$key] = (int) $val; } } else { @@ -224,7 +241,7 @@ $value = "", $owner_guid = 0, $limit = 10, $offset = 0, $order_by = "asc", $time if (is_array($entity_owner_guid)) { if (sizeof($entity_owner_guid) > 0) { - foreach($entity_owner_guid as $key => $val) { + foreach ($entity_owner_guid as $key => $val) { $entity_owner_guid[$key] = (int) $val; } } else { @@ -236,11 +253,11 @@ $value = "", $owner_guid = 0, $limit = 10, $offset = 0, $order_by = "asc", $time $limit = (int)$limit; $offset = (int)$offset; - if($order_by == 'asc') { + if ($order_by == 'asc') { $order_by = "a.time_created asc"; } - if($order_by == 'desc') { + if ($order_by == 'desc') { $order_by = "a.time_created desc"; } @@ -249,7 +266,7 @@ $value = "", $owner_guid = 0, $limit = 10, $offset = 0, $order_by = "asc", $time if ($entity_guid != 0 && !is_array($entity_guid)) { $where[] = "a.entity_guid=$entity_guid"; } else if (is_array($entity_guid)) { - $where[] = "a.entity_guid in (". implode(",",$entity_guid) . ")"; + $where[] = "a.entity_guid in (" . implode(",", $entity_guid) . ")"; } if ($entity_type != "") { @@ -264,7 +281,7 @@ $value = "", $owner_guid = 0, $limit = 10, $offset = 0, $order_by = "asc", $time $where[] = "a.owner_guid=$owner_guid"; } else { if (is_array($owner_guid)) { - $where[] = "a.owner_guid in (" . implode(",",$owner_guid) . ")"; + $where[] = "a.owner_guid in (" . implode(",", $owner_guid) . ")"; } } @@ -272,7 +289,7 @@ $value = "", $owner_guid = 0, $limit = 10, $offset = 0, $order_by = "asc", $time $where[] = "e.owner_guid=$entity_owner_guid"; } else { if (is_array($entity_owner_guid)) { - $where[] = "e.owner_guid in (" . implode(",",$entity_owner_guid) . ")"; + $where[] = "e.owner_guid in (" . implode(",", $entity_owner_guid) . ")"; } } @@ -319,20 +336,26 @@ $value = "", $owner_guid = 0, $limit = 10, $offset = 0, $order_by = "asc", $time * * @see elgg_get_entities * @see elgg_get_entities_from_metadata + * * @param array $options Array in format: * * annotation_names => NULL|ARR annotations names * * annotation_values => NULL|ARR annotations values * - * annotation_name_value_pairs => NULL|ARR (name = 'name', value => 'value', 'operand' => '=', 'case_sensitive' => TRUE) entries. - * Currently if multiple values are sent via an array (value => array('value1', 'value2') the pair's operand will be forced to "IN". + * annotation_name_value_pairs => NULL|ARR (name = 'name', value => 'value', + * 'operand' => '=', 'case_sensitive' => TRUE) entries. + * Currently if multiple values are sent via an array (value => array('value1', 'value2') + * the pair's operand will be forced to "IN". * - * annotation_name_value_pairs_operator => NULL|STR The operator to use for combining (name = value) OPERATOR (name = value); default AND + * annotation_name_value_pairs_operator => NULL|STR The operator to use for combining + * (name = value) OPERATOR (name = value); default AND * * annotation_case_sensitive => BOOL Overall Case sensitive * - * order_by_annotation => NULL|ARR (array('name' => 'annotation_text1', 'direction' => ASC|DESC, 'as' => text|integer), + * order_by_annotation => NULL|ARR (array('name' => 'annotation_text1', 'direction' => ASC|DESC, + * 'as' => text|integer), + * * Also supports array('name' => 'annotation_text1') * * annotation_owner_guids => NULL|ARR guids for annotaiton owners @@ -358,7 +381,9 @@ function elgg_get_entities_from_annotations(array $options = array()) { $options = array_merge($defaults, $options); - $singulars = array('annotation_name', 'annotation_value', 'annotation_name_value_pair', 'annotation_owner_guid'); + $singulars = array('annotation_name', 'annotation_value', + 'annotation_name_value_pair', 'annotation_owner_guid'); + $options = elgg_normalise_plural_options_array($options, $singulars); if (!$options = elgg_entities_get_metastrings_options('annotation', $options)) { @@ -374,25 +399,32 @@ function elgg_get_entities_from_annotations(array $options = array()) { } /** + * Get entities from annotations + * + * No longer used. + * * @deprecated 1.7 Use elgg_get_entities_from_annotations() - * @param $entity_type - * @param $entity_subtype - * @param $name - * @param $value - * @param $owner_guid - * @param $group_guid - * @param $limit - * @param $offset - * @param $order_by - * @param $count - * @param $timelower - * @param $timeupper + * + * @param mixed $entity_type Type of entity + * @param mixed $entity_subtype Subtype of entity + * @param string $name Name of annotation + * @param string $value Value of annotation + * @param int $owner_guid Guid of owner of annotation + * @param int $group_guid Guid of group + * @param int $limit Limit + * @param int $offset Offset + * @param string $order_by SQL order by string + * @param bool $count Count or return entities + * @param int $timelower Lower time limit + * @param int $timeupper Upper time limit + * * @return unknown_type */ -function get_entities_from_annotations($entity_type = "", $entity_subtype = "", $name = "", $value = "", -$owner_guid = 0, $group_guid = 0, $limit = 10, $offset = 0, $order_by = "asc", $count = false, -$timelower = 0, $timeupper = 0) { - elgg_deprecated_notice('get_entities_from_annotations() was deprecated by elgg_get_entities_from_annotations().', 1.7); +function get_entities_from_annotations($entity_type = "", $entity_subtype = "", $name = "", +$value = "", $owner_guid = 0, $group_guid = 0, $limit = 10, $offset = 0, $order_by = "asc", +$count = false, $timelower = 0, $timeupper = 0) { + $msg = 'get_entities_from_annotations() is deprecated by elgg_get_entities_from_annotations().'; + elgg_deprecated_notice($msg, 1.7); $options = array(); @@ -446,23 +478,28 @@ $timelower = 0, $timeupper = 0) { * * @see elgg_view_entity_list * - * @param string $entity_type Type of entity. - * @param string $entity_subtype Subtype of entity. - * @param string $name Name of annotation. - * @param string $value Value of annotation. - * @param int $limit Maximum number of results to return. - * @param int $owner_guid Owner. - * @param int $group_guid Group container. Currently this is only supported if $entity_type == 'object' - * @param boolean $asc Whether to list in ascending or descending order (default: desc) - * @param boolean $fullview Whether to display the entities in full - * @param boolean $viewtypetoggle Determines whether or not the 'gallery' view can be displayed (default: no) + * @param string $entity_type Type of entity. + * @param string $entity_subtype Subtype of entity. + * @param string $name Name of annotation. + * @param string $value Value of annotation. + * @param int $limit Maximum number of results to return. + * @param int $owner_guid Owner. + * @param int $group_guid Group container. Currently only supported if entity_type is object + * @param boolean $asc Whether to list in ascending or descending order (default: desc) + * @param boolean $fullview Whether to display the entities in full + * @param boolean $viewtypetoggle Can 'gallery' view can be displayed (default: no) + * * @return string Formatted entity list */ -function list_entities_from_annotations($entity_type = "", $entity_subtype = "", $name = "", $value = "", $limit = 10, $owner_guid = 0, $group_guid = 0, $asc = false, $fullview = true, $viewtypetoggle = false) { - elgg_deprecated_notice('list_entities_from_annotations is deprecated by elgg_list_entities_from_annotations', 1.8); +function list_entities_from_annotations($entity_type = "", $entity_subtype = "", $name = "", +$value = "", $limit = 10, $owner_guid = 0, $group_guid = 0, $asc = false, $fullview = true, +$viewtypetoggle = false) { + + $msg = 'list_entities_from_annotations is deprecated by elgg_list_entities_from_annotations'; + elgg_deprecated_notice($msg, 1.8); $options = array(); - + if ($entity_type) { $options['types'] = $entity_type; } @@ -543,10 +580,11 @@ function elgg_list_entities_from_annotations($options = array()) { /** * Returns a human-readable list of annotations on a particular entity. * - * @param int $entity_guid The entity GUID - * @param string $name The name of the kind of annotation - * @param int $limit The number of annotations to display at once - * @param true|false $asc Whether or not the annotations are displayed in ascending order. (Default: true) + * @param int $entity_guid The entity GUID + * @param string $name The name of the kind of annotation + * @param int $limit The number of annotations to display at once + * @param true|false $asc Display annotations in ascending order. (Default: true) + * * @return string HTML (etc) version of the annotation list */ function list_annotations($entity_guid, $name = "", $limit = 25, $asc = true) { @@ -556,7 +594,7 @@ function list_annotations($entity_guid, $name = "", $limit = 25, $asc = true) { $asc = "desc"; } $count = count_annotations($entity_guid, "", "", $name); - $offset = (int) get_input("annoff",0); + $offset = (int) get_input("annoff", 0); $annotations = get_annotations($entity_guid, "", "", $name, "", "", $limit, $offset, $asc); return elgg_view_annotation_list($annotations, $count, $offset, $limit); @@ -565,73 +603,125 @@ function list_annotations($entity_guid, $name = "", $limit = 25, $asc = true) { /** * Return the sum of a given integer annotation. * - * @param $entity_guid int - * @param $entity_type string - * @param $entity_subtype string - * @param $name string + * @param int $entity_guid Guid of Entity + * @param string $entity_type Type of Entity + * @param string $entity_subtype Subtype of Entity + * @param string $name Name of annotation + * @param string $value Value of annotation + * @param string $value_type Type of value + * @param int $owner_guid GUID of owner of annotation + * + * @return int */ -function get_annotations_sum($entity_guid, $entity_type = "", $entity_subtype = "", $name = "", $value = "", $value_type = "", $owner_guid = 0) { - return __get_annotations_calculate_x("sum", $entity_guid, $entity_type, $entity_subtype, $name, $value, $value_type, $owner_guid); +function get_annotations_sum($entity_guid, $entity_type = "", $entity_subtype = "", $name = "", +$value = "", $value_type = "", $owner_guid = 0) { + + return get_annotations_calculate_x("sum", $entity_guid, $entity_type, $entity_subtype, $name, + $value, $value_type, $owner_guid); } /** * Return the max of a given integer annotation. * - * @param $entity_guid int - * @param $entity_type string - * @param $entity_subtype string - * @param $name string + * @param int $entity_guid Guid of Entity + * @param string $entity_type Type of Entity + * @param string $entity_subtype Subtype of Entity + * @param string $name Name of annotation + * @param string $value Value of annotation + * @param string $value_type Type of value + * @param int $owner_guid GUID of owner of annotation + * + * @return int */ -function get_annotations_max($entity_guid, $entity_type = "", $entity_subtype = "", $name = "", $value = "", $value_type = "", $owner_guid = 0) { - return __get_annotations_calculate_x("max", $entity_guid, $entity_type, $entity_subtype, $name, $value, $value_type, $owner_guid); +function get_annotations_max($entity_guid, $entity_type = "", $entity_subtype = "", $name = "", +$value = "", $value_type = "", $owner_guid = 0) { + + return get_annotations_calculate_x("max", $entity_guid, $entity_type, $entity_subtype, $name, + $value, $value_type, $owner_guid); } /** * Return the minumum of a given integer annotation. * - * @param $entity_guid int - * @param $entity_type string - * @param $entity_subtype string - * @param $name string + * @param int $entity_guid Guid of Entity + * @param string $entity_type Type of Entity + * @param string $entity_subtype Subtype of Entity + * @param string $name Name of annotation + * @param string $value Value of annotation + * @param string $value_type Type of value + * @param int $owner_guid GUID of owner of annotation + * + * @return int */ -function get_annotations_min($entity_guid, $entity_type = "", $entity_subtype = "", $name = "", $value = "", $value_type = "", $owner_guid = 0) { - return __get_annotations_calculate_x("min", $entity_guid, $entity_type, $entity_subtype, $name, $value, $value_type, $owner_guid); +function get_annotations_min($entity_guid, $entity_type = "", $entity_subtype = "", $name = "", +$value = "", $value_type = "", $owner_guid = 0) { + + return get_annotations_calculate_x("min", $entity_guid, $entity_type, $entity_subtype, $name, + $value, $value_type, $owner_guid); } /** * Return the average of a given integer annotation. * - * @param $entity_guid int - * @param $entity_type string - * @param $entity_subtype string - * @param $name string + * @param int $entity_guid Guid of Entity + * @param string $entity_type Type of Entity + * @param string $entity_subtype Subtype of Entity + * @param string $name Name of annotation + * @param string $value Value of annotation + * @param string $value_type Type of value + * @param int $owner_guid GUID of owner of annotation + * + * @return int */ -function get_annotations_avg($entity_guid, $entity_type = "", $entity_subtype = "", $name = "", $value = "", $value_type = "", $owner_guid = 0) { - return __get_annotations_calculate_x("avg", $entity_guid, $entity_type, $entity_subtype, $name, $value, $value_type, $owner_guid); +function get_annotations_avg($entity_guid, $entity_type = "", $entity_subtype = "", $name = "", +$value = "", $value_type = "", $owner_guid = 0) { + + return get_annotations_calculate_x("avg", $entity_guid, $entity_type, $entity_subtype, $name, + $value, $value_type, $owner_guid); } /** * Count the number of annotations based on search parameters * - * @param int $entity_guid - * @param string $entity_type - * @param string $entity_subtype - * @param string $name + * @param int $entity_guid Guid of Entity + * @param string $entity_type Type of Entity + * @param string $entity_subtype Subtype of Entity + * @param string $name Name of annotation + * @param string $value Value of annotation + * @param string $value_type Type of value + * @param int $owner_guid GUID of owner of annotation + * @param int $timelower Lower time limit + * @param int $timeupper Upper time limit + * + * @return int */ -function count_annotations($entity_guid = 0, $entity_type = "", $entity_subtype = "", $name = "", $value = "", $value_type = "", $owner_guid = 0, $timelower = 0, $timeupper = 0) { - return __get_annotations_calculate_x("count", $entity_guid, $entity_type, $entity_subtype, $name, $value, $value_type, $owner_guid, $timelower, $timeupper); +function count_annotations($entity_guid = 0, $entity_type = "", $entity_subtype = "", +$name = "", $value = "", $value_type = "", $owner_guid = 0, $timelower = 0, +$timeupper = 0) { + return get_annotations_calculate_x("count", $entity_guid, $entity_type, $entity_subtype, + $name, $value, $value_type, $owner_guid, $timelower, $timeupper); } /** * Perform a mathmatical calculation on integer annotations. * - * @param $sum string - * @param $entity_id int - * @param $entity_type string - * @param $entity_subtype string - * @param $name string + * @param string $sum What sort of calculation to perform + * @param int $entity_guid Guid of Entity + * @param string $entity_type Type of Entity + * @param string $entity_subtype Subtype of Entity + * @param string $name Name of annotation + * @param string $value Value of annotation + * @param string $value_type Type of value + * @param int $owner_guid GUID of owner of annotation + * @param int $timelower Lower time limit + * @param int $timeupper Upper time limit + * + * @return int */ -function __get_annotations_calculate_x($sum = "avg", $entity_guid, $entity_type = "", $entity_subtype = "", $name = "", $value = "", $value_type = "", $owner_guid = 0, $timelower = 0, $timeupper = 0) { +function get_annotations_calculate_x($sum = "avg", $entity_guid, $entity_type = "", +$entity_subtype = "", $name = "", $value = "", $value_type = "", $owner_guid = 0, +$timelower = 0, $timeupper = 0) { + global $CONFIG; $sum = sanitise_string($sum); @@ -665,7 +755,7 @@ function __get_annotations_calculate_x($sum = "avg", $entity_guid, $entity_type $where[] = "e.guid=$entity_guid"; } - if ($entity_type!="") { + if ($entity_type != "") { $where[] = "e.type='$entity_type'"; } @@ -673,15 +763,15 @@ function __get_annotations_calculate_x($sum = "avg", $entity_guid, $entity_type $where[] = "e.subtype=$entity_subtype"; } - if ($name!="") { + if ($name != "") { $where[] = "a.name_id='$name'"; } - if ($value!="") { + if ($value != "") { $where[] = "a.value_id='$value'"; } - if ($value_type!="") { + if ($value_type != "") { $where[] = "a.value_type='$value_type'"; } @@ -724,17 +814,23 @@ function __get_annotations_calculate_x($sum = "avg", $entity_guid, $entity_type /** * Get entities ordered by a mathematical calculation * - * @param $sum string - * @param $entity_type string - * @param $entity_subtype string - * @param $name string - * @param $mdname string - * @param $mdvalue string - * @param $limit int - * @param string $orderdir Default: asc - the sort order - * @return unknown + * @param string $sum What sort of calculation to perform + * @param string $entity_type Type of Entity + * @param string $entity_subtype Subtype of Entity + * @param string $name Name of annotation + * @param string $mdname Metadata name + * @param string $mdvalue Metadata value + * @param int $owner_guid GUID of owner of annotation + * @param int $limit Limit of results + * @param int $offset Offset of results + * @param string $orderdir Order of results + * @param bool $count Return count or entities + * + * @return mixed */ -function __get_entities_from_annotations_calculate_x($sum = "sum", $entity_type = "", $entity_subtype = "", $name = "", $mdname = '', $mdvalue = '', $owner_guid = 0, $limit = 10, $offset = 0, $orderdir = 'desc', $count = false) { +function get_entities_from_annotations_calculate_x($sum = "sum", $entity_type = "", +$entity_subtype = "", $name = "", $mdname = '', $mdvalue = '', $owner_guid = 0, +$limit = 10, $offset = 0, $orderdir = 'desc', $count = false) { global $CONFIG; $sum = sanitise_string($sum); @@ -762,7 +858,7 @@ function __get_entities_from_annotations_calculate_x($sum = "sum", $entity_type $where = array(); - if ($entity_type!="") { + if ($entity_type != "") { $where[] = "e.type='$entity_type'"; } @@ -774,16 +870,16 @@ function __get_entities_from_annotations_calculate_x($sum = "sum", $entity_type $where[] = "e.subtype=$entity_subtype"; } - if ($name!="") { + if ($name != "") { $where[] = "a.name_id='$name'"; } if (!empty($mdname) && !empty($mdvalue)) { - if ($mdname!="") { + if ($mdname != "") { $where[] = "m.name_id='$meta_n'"; } - if ($mdvalue!="") { + if ($mdvalue != "") { $where[] = "m.value_id='$meta_v'"; } } @@ -798,7 +894,9 @@ function __get_entities_from_annotations_calculate_x($sum = "sum", $entity_type } else { $query = "SELECT count(distinct e.guid) as num, $sum(ms.string) as sum "; } - $query .= " from {$CONFIG->dbprefix}entities e JOIN {$CONFIG->dbprefix}annotations a on a.entity_guid = e.guid JOIN {$CONFIG->dbprefix}metastrings ms on a.value_id=ms.id "; + $query .= " from {$CONFIG->dbprefix}entities e" + . " JOIN {$CONFIG->dbprefix}annotations a on a.entity_guid = e.guid" + . " JOIN {$CONFIG->dbprefix}metastrings ms on a.value_id=ms.id "; if (!empty($mdname) && !empty($mdvalue)) { $query .= " JOIN {$CONFIG->dbprefix}metadata m on m.entity_guid = e.guid "; @@ -830,83 +928,110 @@ function __get_entities_from_annotations_calculate_x($sum = "sum", $entity_type /** * Returns entities ordered by the sum of an annotation * - * @param unknown_type $entity_type - * @param unknown_type $entity_subtype - * @param unknown_type $name - * @param string $mdname - * @param string $mdvalue - * @param unknown_type $owner_guid - * @param int $limit - * @param int $offset - * @param true|false $count + * @param string $entity_type Type of Entity + * @param string $entity_subtype Subtype of Entity + * @param string $name Name of annotation + * @param string $mdname Metadata name + * @param string $mdvalue Metadata value + * @param int $owner_guid GUID of owner of annotation + * @param int $limit Limit of results + * @param int $offset Offset of results + * @param string $orderdir Order of results + * @param bool $count Return count or entities + * * @return unknown */ -function get_entities_from_annotation_count($entity_type = "", $entity_subtype = "", $name = "", $mdname = '', $mdvalue = '', $owner_guid = 0, $limit = 10, $offset = 0, $orderdir = 'desc', $count = false) { - return __get_entities_from_annotations_calculate_x('sum',$entity_type,$entity_subtype,$name,$mdname, $mdvalue, $owner_guid,$limit, $offset, $orderdir, $count); +function get_entities_from_annotation_count($entity_type = "", $entity_subtype = "", $name = "", +$mdname = '', $mdvalue = '', $owner_guid = 0, $limit = 10, $offset = 0, $orderdir = 'desc', +$count = false) { + + return get_entities_from_annotations_calculate_x('sum', $entity_type, $entity_subtype, + $name, $mdname, $mdvalue, $owner_guid, $limit, $offset, $orderdir, $count); } /** * Lists entities by the totals of a particular kind of annotation * - * @param string $entity_type Type of entity. - * @param string $entity_subtype Subtype of entity. - * @param string $name Name of annotation. - * @param int $limit Maximum number of results to return. - * @param int $owner_guid Owner. - * @param int $group_guid Group container. Currently this is only supported if $entity_type == 'object' - * @param boolean $asc Whether to list in ascending or descending order (default: desc) - * @param boolean $fullview Whether to display the entities in full - * @param boolean $viewtypetoggle Determines whether or not the 'gallery' view can be displayed (default: no) + * @param string $entity_type Type of entity. + * @param string $entity_subtype Subtype of entity. + * @param string $name Name of annotation. + * @param int $limit Maximum number of results to return. + * @param int $owner_guid Owner. + * @param int $group_guid Group container. Currently only supported if entity_type is object + * @param boolean $asc Whether to list in ascending or descending order (default: desc) + * @param boolean $fullview Whether to display the entities in full + * @param boolean $viewtypetoggle Can the 'gallery' view can be displayed (default: no) + * @param boolean $pagination Add pagination + * @param string $orderdir Order desc or asc + * * @return string Formatted entity list */ -function list_entities_from_annotation_count($entity_type = "", $entity_subtype = "", $name = "", $limit = 10, $owner_guid = 0, $group_guid = 0, $asc = false, $fullview = true, $viewtypetoggle = false, $pagination = true, $orderdir = 'desc') { +function list_entities_from_annotation_count($entity_type = "", $entity_subtype = "", $name = "", +$limit = 10, $owner_guid = 0, $group_guid = 0, $asc = false, $fullview = true, +$viewtypetoggle = false, $pagination = true, $orderdir = 'desc') { if ($asc) { $asc = "asc"; } else { $asc = "desc"; } - $offset = (int) get_input("offset",0); - $count = get_entities_from_annotation_count($entity_type, $entity_subtype, $name, '', '', $owner_guid, $limit, $offset, $orderdir, true); - $entities = get_entities_from_annotation_count($entity_type, $entity_subtype, $name, '', '', $owner_guid, $limit, $offset, $orderdir, false); + $offset = (int) get_input("offset", 0); + $count = get_entities_from_annotation_count($entity_type, $entity_subtype, $name, + '', '', $owner_guid, $limit, $offset, $orderdir, true); + + $entities = get_entities_from_annotation_count($entity_type, $entity_subtype, $name, + '', '', $owner_guid, $limit, $offset, $orderdir, false); - return elgg_view_entity_list($entities, $count, $offset, $limit, $fullview, $viewtypetoggle, $pagination); + return elgg_view_entity_list($entities, $count, $offset, $limit, + $fullview, $viewtypetoggle, $pagination); } /** - * Lists entities by the totals of a particular kind of annotation AND the value of a piece of metadata - * - * @param string $entity_type Type of entity. - * @param string $entity_subtype Subtype of entity. - * @param string $name Name of annotation. - * @param string $mdname Metadata name - * @param string $mdvalue Metadata value - * @param int $limit Maximum number of results to return. - * @param int $owner_guid Owner. - * @param int $group_guid Group container. Currently this is only supported if $entity_type == 'object' - * @param boolean $asc Whether to list in ascending or descending order (default: desc) - * @param boolean $fullview Whether to display the entities in full - * @param boolean $viewtypetoggle Determines whether or not the 'gallery' view can be displayed (default: no) + * Lists entities by the totals of a particular kind of annotation AND + * the value of a piece of metadata + * + * @param string $entity_type Type of entity. + * @param string $entity_subtype Subtype of entity. + * @param string $name Name of annotation. + * @param string $mdname Metadata name + * @param string $mdvalue Metadata value + * @param int $limit Maximum number of results to return. + * @param int $owner_guid Owner. + * @param int $group_guid Group container. Currently only supported if entity_type is object + * @param boolean $asc Whether to list in ascending or descending order (default: desc) + * @param boolean $fullview Whether to display the entities in full + * @param boolean $viewtypetoggle Can the 'gallery' view can be displayed (default: no) + * @param boolean $pagination Display pagination + * @param string $orderdir 'desc' or 'asc' + * * @return string Formatted entity list */ -function list_entities_from_annotation_count_by_metadata($entity_type = "", $entity_subtype = "", $name = "", $mdname = '', $mdvalue = '', $limit = 10, $owner_guid = 0, $group_guid = 0, $asc = false, $fullview = true, $viewtypetoggle = false, $pagination = true, $orderdir = 'desc') { +function list_entities_from_annotation_count_by_metadata($entity_type = "", $entity_subtype = "", +$name = "", $mdname = '', $mdvalue = '', $limit = 10, $owner_guid = 0, $group_guid = 0, +$asc = false, $fullview = true, $viewtypetoggle = false, $pagination = true, $orderdir = 'desc') { + if ($asc) { $asc = "asc"; } else { $asc = "desc"; } - $offset = (int) get_input("offset",0); - $count = get_entities_from_annotation_count($entity_type, $entity_subtype, $name, $mdname, $mdvalue, $owner_guid, $limit, $offset, $orderdir, true); - $entities = get_entities_from_annotation_count($entity_type, $entity_subtype, $name, $mdname, $mdvalue, $owner_guid, $limit, $offset, $orderdir, false); + $offset = (int) get_input("offset", 0); + $count = get_entities_from_annotation_count($entity_type, $entity_subtype, $name, $mdname, + $mdvalue, $owner_guid, $limit, $offset, $orderdir, true); + $entities = get_entities_from_annotation_count($entity_type, $entity_subtype, $name, $mdname, + $mdvalue, $owner_guid, $limit, $offset, $orderdir, false); - return elgg_view_entity_list($entities, $count, $offset, $limit, $fullview, $viewtypetoggle, $pagination); + return elgg_view_entity_list($entities, $count, $offset, $limit, $fullview, + $viewtypetoggle, $pagination); } /** * Delete a given annotation. * - * @param $id int The id + * @param int $id The annotation id + * + * @return bool */ function delete_annotation($id) { global $CONFIG; @@ -927,8 +1052,10 @@ function delete_annotation($id) { /** * Clear all the annotations for a given entity, assuming you have access to that metadata. * - * @param int $guid - * @return number of annotations deleted or false if an error + * @param int $guid The entity guid + * @param string $name The name of the annotation to delete. + * + * @return int Number of annotations deleted or false if an error */ function clear_annotations($guid, $name = "") { global $CONFIG; @@ -968,13 +1095,17 @@ function clear_annotations($guid, $name = "") { * Clear all annotations belonging to a given owner_guid * * @param int $owner_guid The owner + * + * @return int Number of annotations deleted */ function clear_annotations_by_owner($owner_guid) { global $CONFIG; $owner_guid = (int)$owner_guid; - $annotations = get_data("SELECT id from {$CONFIG->dbprefix}annotations WHERE owner_guid=$owner_guid"); + $query = "SELECT id from {$CONFIG->dbprefix}annotations WHERE owner_guid=$owner_guid"; + + $annotations = get_data($query); $deleted = 0; if (!$annotations) { @@ -993,6 +1124,15 @@ function clear_annotations_by_owner($owner_guid) { /** * Handler called by trigger_plugin_hook on the "export" event. + * + * @param string $hook 'export' + * @param string $entity_type 'all' + * @param mixed $returnvalue Default return value + * @param mixed $params List of params to export + * + * @elgg_plugin_hook export all + * + * @return mixed */ function export_annotation_plugin_hook($hook, $entity_type, $returnvalue, $params) { // Sanity check values @@ -1019,9 +1159,12 @@ function export_annotation_plugin_hook($hook, $entity_type, $returnvalue, $param } /** - * Get the URL for this item of metadata, by default this links to the export handler in the current view. + * Get the URL for this item of metadata, by default this links to the + * export handler in the current view. + * + * @param int $id Annotation id * - * @param int $id + * @return mixed */ function get_annotation_url($id) { $id = (int)$id; @@ -1035,9 +1178,9 @@ function get_annotation_url($id) { /** * Check to see if a user has already created an annotation on an object * - * @param int $entity_guid - * @param string $annotation_type - * @param int $owner_guid Defaults to logged in user. + * @param int $entity_guid Entity guid + * @param string $annotation_type Type of annotation + * @param int $owner_guid Defaults to logged in user. * * @return true | false */ @@ -1068,6 +1211,8 @@ function elgg_annotation_exists($entity_guid, $annotation_type, $owner_guid = NU * * @param string $function_name The function. * @param string $extender_name The name, default 'all'. + * + * @return string */ function register_annotation_url_handler($function_name, $extender_name = "all") { return register_extender_url_handler($function_name, 'annotation', $extender_name); diff --git a/engine/lib/api.php b/engine/lib/api.php index 6cb8debaa..fa7c17d80 100644 --- a/engine/lib/api.php +++ b/engine/lib/api.php @@ -1,13 +1,13 @@ <?php /** * Elgg API - * Functions and objects which make up the API engine. + * Functions and objects that make up the API engine. * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage WebServicesAPI */ -// Primary Services API Server functions ///////////////////////////////////////////////////////////////////// +// Primary Services API Server functions /** * A global array holding API methods. @@ -38,28 +38,38 @@ $API_METHODS = array(); * It also cannot handle arrays of bools or arrays of arrays. * Also, input will be filtered to protect against XSS attacks through the API. * - * @param string $method The api name to expose - for example "myapi.dosomething" - * @param string $function Your function callback. - * @param array $parameters (optional) List of parameters in the same order as in your function. - * Default values may be set for parameters which allow REST api users flexibility in - * what parameters are passed. Generally, optional parameters should be after required parameters. - * This array should be in the format - * "variable" = array ( - * type => 'int' | 'bool' | 'float' | 'string' | 'array' - * required => true (default) | false - * default => value (optional) - * ) - * @param string $description (optional) human readable description of the function. - * @param string $call_method (optional) Define what http method must be used for this function. Default: GET - * @param bool $require_api_auth (optional) (default is false) Does this method require API authorization? (example: API key) - * @param bool $require_user_auth (optional) (default is false) Does this method require user authorization? + * @param string $method The api name to expose - for example "myapi.dosomething" + * @param string $function Your function callback. + * @param array $parameters (optional) List of parameters in the same order as in + * your function. Default values may be set for parameters which + * allow REST api users flexibility in what parameters are passed. + * Generally, optional parameters should be after required + * parameters. + * + * This array should be in the format + * "variable" = array ( + * type => 'int' | 'bool' | 'float' | 'string' | 'array' + * required => true (default) | false + * default => value (optional) + * ) + * @param string $description (optional) human readable description of the function. + * @param string $call_method (optional) Define what http method must be used for + * this function. Default: GET + * @param bool $require_api_auth (optional) (default is false) Does this method + * require API authorization? (example: API key) + * @param bool $require_user_auth (optional) (default is false) Does this method + * require user authorization? + * * @return bool */ -function expose_function($method, $function, array $parameters = NULL, $description = "", $call_method = "GET", $require_api_auth = false, $require_user_auth = false) { +function expose_function($method, $function, array $parameters = NULL, $description = "", +$call_method = "GET", $require_api_auth = false, $require_user_auth = false) { + global $API_METHODS; if (($method == "") || ($function == "")) { - throw new InvalidParameterException(elgg_echo('InvalidParameterException:APIMethodOrFunctionNotSet')); + $msg = elgg_echo('InvalidParameterException:APIMethodOrFunctionNotSet'); + throw new InvalidParameterException($msg); } // does not check whether this method has already been exposed - good idea? @@ -72,13 +82,15 @@ function expose_function($method, $function, array $parameters = NULL, $descript if ($parameters != NULL) { if (!is_array($parameters)) { - throw new InvalidParameterException(sprintf(elgg_echo('InvalidParameterException:APIParametersArrayStructure'), $method)); + $msg = sprintf(elgg_echo('InvalidParameterException:APIParametersArrayStructure'), $method); + throw new InvalidParameterException($msg); } // catch common mistake of not setting up param array correctly $first = current($parameters); if (!is_array($first)) { - throw new InvalidParameterException(sprintf(elgg_echo('InvalidParameterException:APIParametersArrayStructure'), $method)); + $msg = sprintf(elgg_echo('InvalidParameterException:APIParametersArrayStructure'), $method); + throw new InvalidParameterException($msg); } } @@ -103,7 +115,10 @@ function expose_function($method, $function, array $parameters = NULL, $descript $API_METHODS[$method]["call_method"] = 'GET'; break; default : - throw new InvalidParameterException(sprintf(elgg_echo('InvalidParameterException:UnrecognisedHttpMethod'), $call_method, $method)); + $msg = sprintf(elgg_echo('InvalidParameterException:UnrecognisedHttpMethod'), + $call_method, $method); + + throw new InvalidParameterException($msg); } $API_METHODS[$method]["require_api_auth"] = $require_api_auth; @@ -115,8 +130,12 @@ function expose_function($method, $function, array $parameters = NULL, $descript /** * Unregister an API method + * * @param string $method The api name that was exposed + * * @since 1.7.0 + * + * @return void */ function unexpose_function($method) { global $API_METHODS; @@ -128,7 +147,9 @@ function unexpose_function($method) { /** * Check that the method call has the proper API and user authentication + * * @param string $method The api name that was exposed + * * @return true or throws an exception * @throws APIException * @since 1.7.0 @@ -171,6 +192,7 @@ function authenticate_method($method) { * A method is a function which you have previously exposed using expose_function. * * @param string $method Method, e.g. "foo.bar" + * * @return GenericResult The result of the execution. * @throws APIException, CallException */ @@ -179,17 +201,24 @@ function execute_method($method) { // method must be exposed if (!isset($API_METHODS[$method])) { - throw new APIException(sprintf(elgg_echo('APIException:MethodCallNotImplemented'), $method)); + $msg = sprintf(elgg_echo('APIException:MethodCallNotImplemented'), $method); + throw new APIException($msg); } // function must be callable - if (!(isset($API_METHODS[$method]["function"])) || !(is_callable($API_METHODS[$method]["function"]))) { - throw new APIException(sprintf(elgg_echo('APIException:FunctionDoesNotExist'), $method)); + if (!(isset($API_METHODS[$method]["function"])) + || !(is_callable($API_METHODS[$method]["function"]))) { + + $msg = sprintf(elgg_echo('APIException:FunctionDoesNotExist'), $method); + throw new APIException($msg); } // check http call method if (strcmp(get_call_method(), $API_METHODS[$method]["call_method"]) != 0) { - throw new CallException(sprintf(elgg_echo('CallException:InvalidCallMethod'), $method, $API_METHODS[$method]["call_method"])); + $msg = sprintf(elgg_echo('CallException:InvalidCallMethod'), $method, + $API_METHODS[$method]["call_method"]); + + throw new CallException($msg); } $parameters = get_parameters_for_method($method); @@ -213,12 +242,14 @@ function execute_method($method) { } if ($result === false) { - throw new APIException(sprintf(elgg_echo('APIException:FunctionParseError'), $function, $serialised_parameters)); + $msg = sprintf(elgg_echo('APIException:FunctionParseError'), $function, $serialised_parameters); + throw new APIException($msg); } - if ($result === NULL) { + if ($result === NULL) { // If no value - throw new APIException(sprintf(elgg_echo('APIException:FunctionNoReturn'), $function, $serialised_parameters)); + $msg = sprintf(elgg_echo('APIException:FunctionNoReturn'), $function, $serialised_parameters); + throw new APIException($msg); } // Otherwise assume that the call was successful and return it as a success object. @@ -227,6 +258,7 @@ function execute_method($method) { /** * Get the request method. + * * @return string HTTP request method */ function get_call_method() { @@ -240,6 +272,7 @@ function get_call_method() { * an associated array. * * @param string $method The method + * * @return array containing parameters as key => value */ function get_parameters_for_method($method) { @@ -268,6 +301,7 @@ function get_parameters_for_method($method) { /** * Get POST data * Since this is called through a handler, we need to manually get the post data + * * @return POST data as string encoded as multipart/form-data */ function get_post_data() { @@ -279,7 +313,10 @@ function get_post_data() { /** * This fixes the post parameters that are munged due to page handler + * * @since 1.7.0 + * + * @return void */ function include_post_data() { @@ -307,8 +344,10 @@ function include_post_data() { /** * Verify that the required parameters are present - * @param $method - * @param $parameters + * + * @param string $method Method name + * @param array $parameters List of expected parameters + * * @return true on success or exception * @throws APIException * @since 1.7.0 @@ -325,12 +364,15 @@ function verify_parameters($method, $parameters) { foreach ($API_METHODS[$method]['parameters'] as $key => $value) { // this tests the expose structure: must be array to describe parameter and type must be defined if (!is_array($value) || !isset($value['type'])) { - throw new APIException(sprintf(elgg_echo('APIException:InvalidParameter'), $key, $method)); + + $msg = sprintf(elgg_echo('APIException:InvalidParameter'), $key, $method); + throw new APIException($msg); } // Check that the variable is present in the request if required if ($value['required'] && !array_key_exists($key, $parameters)) { - throw new APIException(sprintf(elgg_echo('APIException:MissingParameterInMethod'), $key, $method)); + $msg = sprintf(elgg_echo('APIException:MissingParameterInMethod'), $key, $method); + throw new APIException($msg); } } @@ -340,8 +382,9 @@ function verify_parameters($method, $parameters) { /** * Serialize an array of parameters for an API method call * - * @param string $method API method name - * @param array $parameters Array of parameters + * @param string $method API method name + * @param array $parameters Array of parameters + * * @return string or exception * @throws APIException * @since 1.7.0 @@ -390,7 +433,8 @@ function serialise_parameters($method, $parameters) { case 'array': // we can handle an array of strings, maybe ints, definitely not booleans or other arrays if (!is_array($parameters[$key])) { - throw new APIException(sprintf(elgg_echo('APIException:ParameterNotArray'), $key)); + $msg = sprintf(elgg_echo('APIException:ParameterNotArray'), $key); + throw new APIException($msg); } $array = "array("; @@ -402,7 +446,7 @@ function serialise_parameters($method, $parameters) { $array .= "'$k'=>'$v',"; } - $array = trim($array,","); + $array = trim($array, ","); $array .= ")"; $array = ",$array"; @@ -410,7 +454,8 @@ function serialise_parameters($method, $parameters) { $serialised_parameters .= $array; break; default: - throw new APIException(sprintf(elgg_echo('APIException:UnrecognisedTypeCast'), $value['type'], $key, $method)); + $msg = sprintf(elgg_echo('APIException:UnrecognisedTypeCast'), $value['type'], $key, $method); + throw new APIException($msg); } } @@ -421,7 +466,10 @@ function serialise_parameters($method, $parameters) { /** * PAM: Confirm that the call includes a valid API key + * * @return true if good API key - otherwise throws exception + * + * @return mixed * @throws APIException * @since 1.7.0 */ @@ -449,7 +497,9 @@ function api_auth_key() { /** * PAM: Confirm the HMAC signature + * * @return true if success - otherwise throws exception + * * @throws SecurityException * @since 1.7.0 */ @@ -463,7 +513,8 @@ function api_auth_hmac() { $api_user = get_api_user($CONFIG->site_id, $api_header->api_key); if (!$api_user) { - throw new SecurityException(elgg_echo('SecurityException:InvalidAPIKey'), ErrorResult::$RESULT_FAIL_APIKEY_INVALID); + throw new SecurityException(elgg_echo('SecurityException:InvalidAPIKey'), + ErrorResult::$RESULT_FAIL_APIKEY_INVALID); } // Get the secret key @@ -492,12 +543,15 @@ function api_auth_hmac() { } // Validate post data - if ($api_header->method=="POST") { + if ($api_header->method == "POST") { $postdata = get_post_data(); $calculated_posthash = calculate_posthash($postdata, $api_header->posthash_algo); - if (strcmp($api_header->posthash, $calculated_posthash)!=0) { - throw new SecurityException(sprintf(elgg_echo('SecurityException:InvalidPostHash'), $calculated_posthash, $api_header->posthash)); + if (strcmp($api_header->posthash, $calculated_posthash) != 0) { + $msg = sprintf(elgg_echo('SecurityException:InvalidPostHash'), + $calculated_posthash, $api_header->posthash); + + throw new SecurityException($msg); } } @@ -547,7 +601,7 @@ function get_and_validate_api_headers() { // This values determines how long the HMAC cache needs to store previous // signatures. Heavy use of HMAC is better handled with a shorter sig lifetime. // See cache_hmac_check_replay() - if (($result->time<(time()-90000)) || ($result->time>(time()+90000))) { + if (($result->time < (time() - 90000)) || ($result->time > (time() + 90000))) { throw new APIException(elgg_echo('APIException:TemporalDrift')); } @@ -581,6 +635,7 @@ function get_and_validate_api_headers() { * This also gives us an easy way to disable algorithms. * * @param string $algo The algorithm + * * @return string The php algorithm * @throws APIException if an algorithm is not supported. */ @@ -605,15 +660,20 @@ function map_api_hash($algo) { * This function signs an api request using the information provided. The signature returned * has been base64 encoded and then url encoded. * - * @param string $algo The HMAC algorithm used - * @param string $time String representation of unix time - * @param string $api_key Your api key - * @param string $secret Your private key - * @param string $get_variables URLEncoded string representation of the get variable parameters, eg "method=user&guid=2" - * @param string $post_hash Optional sha1 hash of the post data. + * @param string $algo The HMAC algorithm used + * @param string $time String representation of unix time + * @param string $nonce Nonce + * @param string $api_key Your api key + * @param string $secret_key Your private key + * @param string $get_variables URLEncoded string representation of the get variable parameters, + * eg "method=user&guid=2" + * @param string $post_hash Optional sha1 hash of the post data. + * * @return string The HMAC signature */ -function calculate_hmac($algo, $time, $nonce, $api_key, $secret_key, $get_variables, $post_hash = "") { +function calculate_hmac($algo, $time, $nonce, $api_key, $secret_key, +$get_variables, $post_hash = "") { + global $CONFIG; elgg_log("HMAC Parts: $algo, $time, $api_key, $secret_key, $get_variables, $post_hash"); @@ -624,7 +684,7 @@ function calculate_hmac($algo, $time, $nonce, $api_key, $secret_key, $get_variab hash_update($ctx, trim($nonce)); hash_update($ctx, trim($api_key)); hash_update($ctx, trim($get_variables)); - if (trim($post_hash)!="") { + if (trim($post_hash) != "") { hash_update($ctx, trim($post_hash)); } @@ -636,8 +696,9 @@ function calculate_hmac($algo, $time, $nonce, $api_key, $secret_key, $get_variab * * @todo Work out how to handle really large bits of data. * - * @param string $postdata string The post data. - * @param string $algo The algorithm used. + * @param string $postdata The post data. + * @param string $algo The algorithm used. + * * @return string The hash. */ function calculate_posthash($postdata, $algo) { @@ -653,6 +714,7 @@ function calculate_posthash($postdata, $algo) { * hasn't been seen before, and secondly it will add the given hmac to the cache. * * @param string $hmac The hmac string. + * * @return bool True if replay detected, false if not. */ function cache_hmac_check_replay($hmac) { @@ -675,6 +737,7 @@ function cache_hmac_check_replay($hmac) { * Generate a new API user for a site, returning a new keypair on success. * * @param int $site_guid The GUID of the site. (default is current site) + * * @return stdClass object or false */ function create_api_user($site_guid) { @@ -686,8 +749,8 @@ function create_api_user($site_guid) { $site_guid = (int)$site_guid; - $public = sha1(rand().$site_guid.microtime()); - $secret = sha1(rand().$site_guid.microtime().$public); + $public = sha1(rand() . $site_guid . microtime()); + $secret = sha1(rand() . $site_guid . microtime() . $public); $insert = insert_data("INSERT into {$CONFIG->dbprefix}api_users (site_guid, api_key, secret) values @@ -701,10 +764,12 @@ function create_api_user($site_guid) { } /** - * Find an API User's details based on the provided public api key. These users are not users in the traditional sense. + * Find an API User's details based on the provided public api key. + * These users are not users in the traditional sense. + * + * @param int $site_guid The GUID of the site. + * @param string $api_key The API Key * - * @param int $site_guid The GUID of the site. - * @param string $api_key The API Key * @return mixed stdClass representing the database row or false. */ function get_api_user($site_guid, $api_key) { @@ -713,14 +778,18 @@ function get_api_user($site_guid, $api_key) { $api_key = sanitise_string($api_key); $site_guid = (int)$site_guid; - return get_data_row("SELECT * from {$CONFIG->dbprefix}api_users where api_key='$api_key' and site_guid=$site_guid and active=1"); + $query = "SELECT * from {$CONFIG->dbprefix}api_users" + . " where api_key='$api_key' and site_guid=$site_guid and active=1"; + + return get_data_row($query); } /** * Revoke an api user key. * - * @param int $site_guid The GUID of the site. - * @param string $api_key The API Key (public). + * @param int $site_guid The GUID of the site. + * @param string $api_key The API Key (public). + * * @return bool */ function remove_api_user($site_guid, $api_key) { @@ -735,7 +804,7 @@ function remove_api_user($site_guid, $api_key) { } -// User Authorization functions //////////////////////////////////////////////////////////////// +// User Authorization functions /** * Check the user token @@ -743,10 +812,9 @@ function remove_api_user($site_guid, $api_key) { * it is present and is valid. The user gets logged in so with the current * session code of Elgg, that user will be logged out of all other sessions. * - * @param array/mixed $credentials * @return bool */ -function pam_auth_usertoken($credentials = NULL) { +function pam_auth_usertoken() { global $CONFIG; $token = get_input('auth_token'); @@ -765,7 +833,7 @@ function pam_auth_usertoken($credentials = NULL) { } // Not an elgg user - if ( (!$u instanceof ElggUser)) { + if ((!$u instanceof ElggUser)) { return false; } @@ -787,19 +855,21 @@ function pam_auth_usertoken($credentials = NULL) { /** * See if the user has a valid login sesson + * * @return bool */ -function pam_auth_session($credentials = NULL) { +function pam_auth_session() { return isloggedin(); } -// user token functions ///////////////////////////////////////////////////////////////////// +// user token functions /** * Obtain a token for a user. * * @param string $username The username - * @param int $expire minutes until token expires (default is 60 minutes) + * @param int $expire Minutes until token expires (default is 60 minutes) + * * @return bool */ function create_user_token($username, $expire = 60) { @@ -809,7 +879,7 @@ function create_user_token($username, $expire = 60) { $user = get_user_by_username($username); $time = time(); $time += 60 * $expire; - $token = md5(rand(). microtime() . $username . $time . $site_guid); + $token = md5(rand() . microtime() . $username . $time . $site_guid); if (!$user) { return false; @@ -817,7 +887,8 @@ function create_user_token($username, $expire = 60) { if (insert_data("INSERT into {$CONFIG->dbprefix}users_apisessions (user_guid, site_guid, token, expires) values - ({$user->guid}, $site_guid, '$token', '$time') on duplicate key update token='$token', expires='$time'")) { + ({$user->guid}, $site_guid, '$token', '$time') + on duplicate key update token='$token', expires='$time'")) { return $token; } @@ -829,6 +900,7 @@ function create_user_token($username, $expire = 60) { * * @param int $user_guid The user GUID * @param int $site_guid The ID of the site (default is current site) + * * @return false if none available or array of stdClass objects * (see users_apisessions schema for available variables in objects) * @since 1.7.0 @@ -852,11 +924,12 @@ function get_user_tokens($user_guid, $site_guid) { /** * Validate a token against a given site. * - * A token registered with one site can not be used from a different apikey(site), so be aware of this - * during development. + * A token registered with one site can not be used from a + * different apikey(site), so be aware of this during development. + * + * @param string $token The Token. + * @param int $site_guid The ID of the site (default is current site) * - * @param string $token The Token. - * @param int $site_guid The ID of the site (default is current site) * @return mixed The user id attached to the token if not expired or false. */ function validate_user_token($token, $site_guid) { @@ -884,8 +957,9 @@ function validate_user_token($token, $site_guid) { /** * Remove user token * - * @param string $token - * @param int $site_guid The ID of the site (default is current site) + * @param string $token The toekn + * @param int $site_guid The ID of the site (default is current site) + * * @return bool * @since 1.7.0 */ @@ -920,12 +994,13 @@ function remove_expired_user_tokens() { where site_guid=$site_guid and expires < $time"); } -// Client api functions /////////////////////////////////////////////////////////////////// +// Client api functions /** * Utility function to serialise a header array into its text representation. * * @param array $headers The array of headers "key" => "value" + * * @return string */ function serialise_api_headers(array $headers) { @@ -941,15 +1016,18 @@ function serialise_api_headers(array $headers) { /** * Send a raw API call to an elgg api endpoint. * - * @param array $keys The api keys. - * @param string $url URL of the endpoint. - * @param array $call Associated array of "variable" => "value" - * @param string $method GET or POST - * @param string $post_data The post data + * @param array $keys The api keys. + * @param string $url URL of the endpoint. + * @param array $call Associated array of "variable" => "value" + * @param string $method GET or POST + * @param string $post_data The post data * @param string $content_type The content type + * * @return string */ -function send_api_call(array $keys, $url, array $call, $method = 'GET', $post_data = '', $content_type = 'application/octet-stream') { +function send_api_call(array $keys, $url, array $call, $method = 'GET', $post_data = '', +$content_type = 'application/octet-stream') { + global $CONFIG; $headers = array(); @@ -972,8 +1050,8 @@ function send_api_call(array $keys, $url, array $call, $method = 'GET', $post_da $nonce = uniqid(''); // URL encode all the parameters - foreach ($call as $k => $v){ - $encoded_params[] = urlencode($k).'='.urlencode($v); + foreach ($call as $k => $v) { + $encoded_params[] = urlencode($k) . '=' . urlencode($v); } $params = implode('&', $encoded_params); @@ -1033,9 +1111,10 @@ function send_api_call(array $keys, $url, array $call, $method = 'GET', $post_da /** * Send a GET call * - * @param string $url URL of the endpoint. - * @param array $call Associated array of "variable" => "value" - * @param array $keys The keys dependant on chosen authentication method + * @param string $url URL of the endpoint. + * @param array $call Associated array of "variable" => "value" + * @param array $keys The keys dependant on chosen authentication method + * * @return string */ function send_api_get_call($url, array $call, array $keys) { @@ -1045,32 +1124,38 @@ function send_api_get_call($url, array $call, array $keys) { /** * Send a GET call * - * @param string $url URL of the endpoint. - * @param array $call Associated array of "variable" => "value" - * @param array $keys The keys dependant on chosen authentication method - * @param string $post_data The post data + * @param string $url URL of the endpoint. + * @param array $call Associated array of "variable" => "value" + * @param array $keys The keys dependant on chosen authentication method + * @param string $post_data The post data * @param string $content_type The content type + * * @return string */ -function send_api_post_call($url, array $call, array $keys, $post_data, $content_type = 'application/octet-stream') { +function send_api_post_call($url, array $call, array $keys, $post_data, +$content_type = 'application/octet-stream') { + return send_api_call($keys, $url, $call, 'POST', $post_data, $content_type); } /** - * Return a key array suitable for the API client using the standard authentication method based on api-keys and secret keys. + * Return a key array suitable for the API client using the standard + * authentication method based on api-keys and secret keys. * * @param string $secret_key Your secret key - * @param string $api_key Your api key + * @param string $api_key Your api key + * * @return array */ function get_standard_api_key_array($secret_key, $api_key) { return array('public' => $api_key, 'private' => $secret_key); } -// System functions /////////////////////////////////////////////////////////////////////// +// System functions /** * Simple api to return a list of all api's installed on the system. + * * @return array */ function list_all_apis() { @@ -1090,6 +1175,7 @@ function list_all_apis() { * * @param string $username Username * @param string $password Clear text password + * * @return string Token string or exception * @throws SecurityException */ @@ -1104,7 +1190,7 @@ function auth_gettoken($username, $password) { throw new SecurityException(elgg_echo('SecurityException:authenticationfailed')); } -// Error handler functions //////////////////////////////////////////////////////////////// +// Error handler functions /** Define a global array of errors */ $ERRORS = array(); @@ -1114,22 +1200,25 @@ $ERRORS = array(); * This function acts as a wrapper to catch and report PHP error messages. * * @see http://uk3.php.net/set-error-handler - * @param int $errno - * @param string $errmsg - * @param string $filename - * @param int $linenum - * @param array $vars - * @return none + * + * @param int $errno Error number + * @param string $errmsg Human readable message + * @param string $filename Filename + * @param int $linenum Line number + * @param array $vars Vars + * + * @return void */ -function __php_api_error_handler($errno, $errmsg, $filename, $linenum, $vars) { +function _php_api_error_handler($errno, $errmsg, $filename, $linenum, $vars) { global $ERRORS; - $error = date("Y-m-d H:i:s (T)") . ": \"" . $errmsg . "\" in file " . $filename . " (line " . $linenum . ")"; + $error = date("Y-m-d H:i:s (T)") . ": \"" . $errmsg . "\" in file " + . $filename . " (line " . $linenum . ")"; switch ($errno) { case E_USER_ERROR: error_log("ERROR: " . $error); - $ERRORS[] = "ERROR: " .$error; + $ERRORS[] = "ERROR: " . $error; // Since this is a fatal error, we want to stop any further execution but do so gracefully. throw new Exception("ERROR: " . $error); @@ -1138,12 +1227,12 @@ function __php_api_error_handler($errno, $errmsg, $filename, $linenum, $vars) { case E_WARNING : case E_USER_WARNING : error_log("WARNING: " . $error); - $ERRORS[] = "WARNING: " .$error; + $ERRORS[] = "WARNING: " . $error; break; default: error_log("DEBUG: " . $error); - $ERRORS[] = "DEBUG: " .$error; + $ERRORS[] = "DEBUG: " . $error; } } @@ -1153,10 +1242,11 @@ function __php_api_error_handler($errno, $errmsg, $filename, $linenum, $vars) { * uncaught exception, end API execution and return the result to the requestor * as an ErrorResult in the requested format. * - * @param Exception $exception - * @return none + * @param Exception $exception Exception + * + * @return void */ -function __php_api_exception_handler($exception) { +function _php_api_exception_handler($exception) { error_log("*** FATAL EXCEPTION (API) *** : " . $exception); @@ -1167,21 +1257,23 @@ function __php_api_exception_handler($exception) { } -// Services handler /////////////////////////////////////////// +// Services handler /** * Services handler - turns request over to the registered handler * If no handler is found, this returns a 404 error * - * @param string $handler - * @param array $request + * @param string $handler Handler name + * @param array $request Request string + * + * @return void */ function service_handler($handler, $request) { global $CONFIG; set_context('api'); - $request = explode('/',$request); + $request = explode('/', $request); // after the handler, the first identifier is response format // ex) http://example.org/services/api/rest/xml/?method=test @@ -1198,7 +1290,9 @@ function service_handler($handler, $request) { // no handlers set or bad url header("HTTP/1.0 404 Not Found"); exit; - } else if (isset($CONFIG->servicehandler[$handler]) && is_callable($CONFIG->servicehandler[$handler])) { + } else if (isset($CONFIG->servicehandler[$handler]) + && is_callable($CONFIG->servicehandler[$handler])) { + $function = $CONFIG->servicehandler[$handler]; $function($request, $handler); } else { @@ -1211,9 +1305,10 @@ function service_handler($handler, $request) { /** * Registers a web services handler * - * @param string $handler web services type + * @param string $handler Web services type * @param string $function Your function name - * @return true|false Depending on success + * + * @return bool Depending on success * @since 1.7.0 */ function register_service_handler($handler, $function) { @@ -1235,6 +1330,7 @@ function register_service_handler($handler, $function) { * with register_service_handler(). * * @param string $handler web services type + * * @return 1.7.0 */ function unregister_service_handler($handler) { @@ -1244,10 +1340,12 @@ function unregister_service_handler($handler) { } } -// REST handler ////////////////////////////////////////////////////////////// +// REST handler /** * REST API handler + * + * @return void */ function rest_handler() { global $CONFIG; @@ -1255,10 +1353,17 @@ function rest_handler() { require $CONFIG->path . "services/api/rest_api.php"; } -// Initialisation ///////////////////////////////////////////////////////////// +// Initialisation /** * Unit tests for API + * + * @param sting $hook unit_test + * @param string $type system + * @param mixed $value Array of tests + * @param mixed $params Params + * + * @return array */ function api_unit_test($hook, $type, $value, $params) { global $CONFIG; @@ -1269,15 +1374,17 @@ function api_unit_test($hook, $type, $value, $params) { /** * Initialise the API subsystem. * + * @return void */ function api_init() { // Register a page handler, so we can have nice URLs - register_service_handler('rest','rest_handler'); + register_service_handler('rest', 'rest_handler'); register_plugin_hook('unit_test', 'system', 'api_unit_test'); // expose the list of api methods - expose_function("system.api.list", "list_all_apis", NULL, elgg_echo("system.api.list"), "GET", false, false); + expose_function("system.api.list", "list_all_apis", NULL, + elgg_echo("system.api.list"), "GET", false, false); // The authentication token api expose_function("auth.gettoken", @@ -1292,4 +1399,4 @@ function api_init() { } -register_elgg_event_handler('init','system','api_init'); +register_elgg_event_handler('init', 'system', 'api_init'); diff --git a/engine/lib/calendar.php b/engine/lib/calendar.php index ea0f5c51d..f1a18ddb8 100644 --- a/engine/lib/calendar.php +++ b/engine/lib/calendar.php @@ -2,13 +2,20 @@ /** * Elgg calendar / entity / event functions. * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage Calendar + * + * @todo Implement or remove */ /** * Return a timestamp for the start of a given day (defaults today). * + * @param int $day Day + * @param int $month Month + * @param int $year Year + * + * @return int */ function get_day_start($day = null, $month = null, $year = null) { return mktime(0, 0, 0, $month, $day, $year); @@ -17,6 +24,11 @@ function get_day_start($day = null, $month = null, $year = null) { /** * Return a timestamp for the end of a given day (defaults today). * + * @param int $day Day + * @param int $month Month + * @param int $year Year + * + * @return int */ function get_day_end($day = null, $month = null, $year = null) { return mktime(23, 59, 59, $month, $day, $year); @@ -25,19 +37,23 @@ function get_day_end($day = null, $month = null, $year = null) { /** * Return the notable entities for a given time period. * - * @param int $start_time The start time as a unix timestamp. - * @param int $end_time The end time as a unix timestamp. - * @param string $type The type of entity (eg "user", "object" etc) - * @param string $subtype The arbitrary subtype of the entity - * @param int $owner_guid The GUID of the owning user - * @param string $order_by The field to order by; by default, time_created desc - * @param int $limit The number of entities to return; 10 by default - * @param int $offset The indexing offset, 0 by default - * @param boolean $count Set to true to get a count rather than the entities themselves (limits and offsets don't apply in this context). Defaults to false. - * @param int $site_guid The site to get entities for. Leave as 0 (default) for the current site; -1 for all sites. - * @param int|array $container_guid The container or containers to get entities from (default: all containers). + * @param int $start_time The start time as a unix timestamp. + * @param int $end_time The end time as a unix timestamp. + * @param string $type The type of entity (eg "user", "object" etc) + * @param string $subtype The arbitrary subtype of the entity + * @param int $owner_guid The GUID of the owning user + * @param string $order_by The field to order by; by default, time_created desc + * @param int $limit The number of entities to return; 10 by default + * @param int $offset The indexing offset, 0 by default + * @param boolean $count Set to true to get a count instead of entities. Defaults to false. + * @param int $site_guid Site to get entities for. Default 0 = current site. -1 = any. + * @param mixed $container_guid Container or containers to get entities from (default: any). + * + * @return array|false */ -function get_notable_entities($start_time, $end_time, $type = "", $subtype = "", $owner_guid = 0, $order_by = "asc", $limit = 10, $offset = 0, $count = false, $site_guid = 0, $container_guid = null) { +function get_notable_entities($start_time, $end_time, $type = "", $subtype = "", $owner_guid = 0, +$order_by = "asc", $limit = 10, $offset = 0, $count = false, $site_guid = 0, +$container_guid = null) { global $CONFIG; if ($subtype === false || $subtype === null || $subtype === 0) { @@ -59,15 +75,17 @@ function get_notable_entities($start_time, $end_time, $type = "", $subtype = "", if (is_array($type)) { $tempwhere = ""; if (sizeof($type)) { - foreach($type as $typekey => $subtypearray) { - foreach($subtypearray as $subtypeval) { + foreach ($type as $typekey => $subtypearray) { + foreach ($subtypearray as $subtypeval) { $typekey = sanitise_string($typekey); if (!empty($subtypeval)) { $subtypeval = (int) get_subtype_id($typekey, $subtypeval); } else { $subtypeval = 0; } - if (!empty($tempwhere)) $tempwhere .= " or "; + if (!empty($tempwhere)) { + $tempwhere .= " or "; + } $tempwhere .= "(e.type = '{$typekey}' and e.subtype = {$subtypeval})"; } } @@ -83,7 +101,7 @@ function get_notable_entities($start_time, $end_time, $type = "", $subtype = "", $where[] = "e.type='$type'"; } - if ($subtype!=="") { + if ($subtype !== "") { $where[] = "e.subtype=$subtype"; } } @@ -96,8 +114,8 @@ function get_notable_entities($start_time, $end_time, $type = "", $subtype = "", } else if (sizeof($owner_guid) > 0) { $owner_array = array_map('sanitise_int', $owner_guid); // Cast every element to the owner_guid array to int - $owner_guid = implode(",",$owner_guid); // - $where[] = "e.owner_guid in ({$owner_guid})" ; // + $owner_guid = implode(",", $owner_guid); + $where[] = "e.owner_guid in ({$owner_guid})"; } if (is_null($container_guid)) { $container_guid = $owner_array; @@ -110,8 +128,10 @@ function get_notable_entities($start_time, $end_time, $type = "", $subtype = "", if (!is_null($container_guid)) { if (is_array($container_guid)) { - foreach($container_guid as $key => $val) $container_guid[$key] = (int) $val; - $where[] = "e.container_guid in (" . implode(",",$container_guid) . ")"; + foreach ($container_guid as $key => $val) { + $container_guid[$key] = (int) $val; + } + $where[] = "e.container_guid in (" . implode(",", $container_guid) . ")"; } else { $container_guid = (int) $container_guid; $where[] = "e.container_guid = {$container_guid}"; @@ -163,21 +183,25 @@ function get_notable_entities($start_time, $end_time, $type = "", $subtype = "", /** * Return the notable entities for a given time period based on an item of metadata. * - * @param int $start_time The start time as a unix timestamp. - * @param int $end_time The end time as a unix timestamp. - * @param mixed $meta_name - * @param mixed $meta_value - * @param string $entity_type The type of entity to look for, eg 'site' or 'object' + * @param int $start_time The start time as a unix timestamp. + * @param int $end_time The end time as a unix timestamp. + * @param mixed $meta_name Metadata name + * @param mixed $meta_value Metadata value + * @param string $entity_type The type of entity to look for, eg 'site' or 'object' * @param string $entity_subtype The subtype of the entity. - * @param int $limit - * @param int $offset - * @param string $order_by Optional ordering. - * @param int $site_guid The site to get entities for. Leave as 0 (default) for the current site; -1 for all sites. - * @param true|false $count If set to true, returns the total number of entities rather than a list. (Default: false) + * @param int $owner_guid Owner GUID + * @param int $limit Limit + * @param int $offset Offset + * @param string $order_by Optional ordering. + * @param int $site_guid Site to get entities for. Default 0 = current site. -1 = any. + * @param bool $count If true, returns count instead of entities. (Default: false) * * @return int|array A list of entities, or a count if $count is set to true */ -function get_notable_entities_from_metadata($start_time, $end_time, $meta_name, $meta_value = "", $entity_type = "", $entity_subtype = "", $owner_guid = 0, $limit = 10, $offset = 0, $order_by = "", $site_guid = 0, $count = false) { +function get_notable_entities_from_metadata($start_time, $end_time, $meta_name, $meta_value = "", +$entity_type = "", $entity_subtype = "", $owner_guid = 0, $limit = 10, $offset = 0, $order_by = "", +$site_guid = 0, $count = false) { + global $CONFIG; $meta_n = get_metastring_id($meta_name); @@ -195,7 +219,7 @@ function get_notable_entities_from_metadata($start_time, $end_time, $meta_name, $order_by = sanitise_string($order_by); $site_guid = (int) $site_guid; if ((is_array($owner_guid) && (count($owner_guid)))) { - foreach($owner_guid as $key => $guid) { + foreach ($owner_guid as $key => $guid) { $owner_guid[$key] = (int) $guid; } } else { @@ -210,7 +234,7 @@ function get_notable_entities_from_metadata($start_time, $end_time, $meta_name, $where = array(); - if ($entity_type!="") { + if ($entity_type != "") { $where[] = "e.type='$entity_type'"; } @@ -218,11 +242,11 @@ function get_notable_entities_from_metadata($start_time, $end_time, $meta_name, $where[] = "e.subtype=$entity_subtype"; } - if ($meta_name!="") { + if ($meta_name != "") { $where[] = "m.name_id='$meta_n'"; } - if ($meta_value!="") { + if ($meta_value != "") { $where[] = "m.value_id='$meta_v'"; } @@ -231,7 +255,7 @@ function get_notable_entities_from_metadata($start_time, $end_time, $meta_name, } if (is_array($owner_guid)) { - $where[] = "e.container_guid in (".implode(",",$owner_guid).")"; + $where[] = "e.container_guid in (" . implode(",", $owner_guid) . ")"; } else if ($owner_guid > 0) { $where[] = "e.container_guid = {$owner_guid}"; } @@ -258,7 +282,9 @@ function get_notable_entities_from_metadata($start_time, $end_time, $meta_name, $query = "SELECT count(distinct e.guid) as total "; } - $query .= "from {$CONFIG->dbprefix}entities e JOIN {$CONFIG->dbprefix}metadata m on e.guid = m.entity_guid $cal_join where"; + $query .= "from {$CONFIG->dbprefix}entities e" + . " JOIN {$CONFIG->dbprefix}metadata m on e.guid = m.entity_guid $cal_join where"; + foreach ($where as $w) { $query .= " $w and "; } @@ -283,22 +309,28 @@ function get_notable_entities_from_metadata($start_time, $end_time, $meta_name, /** * Return the notable entities for a given time period based on their relationship. * - * @param int $start_time The start time as a unix timestamp. - * @param int $end_time The end time as a unix timestamp. - * @param string $relationship The relationship eg "friends_of" - * @param int $relationship_guid The guid of the entity to use query - * @param bool $inverse_relationship Reverse the normal function of the query to instead say "give me all entities for whome $relationship_guid is a $relationship of" - * @param string $type - * @param string $subtype - * @param int $owner_guid - * @param string $order_by - * @param int $limit - * @param int $offset - * @param boolean $count Set to true if you want to count the number of entities instead (default false) - * @param int $site_guid The site to get entities for. Leave as 0 (default) for the current site; -1 for all sites. + * @param int $start_time The start time as a unix timestamp. + * @param int $end_time The end time as a unix timestamp. + * @param string $relationship The relationship eg "friends_of" + * @param int $relationship_guid The guid of the entity to use query + * @param bool $inverse_relationship Reverse the normal function of the query to say + * "give me all entities for whom $relationship_guid is a + * $relationship of" + * @param string $type Entity type + * @param string $subtype Entity subtype + * @param int $owner_guid Owner GUID + * @param string $order_by Optional Order by + * @param int $limit Limit + * @param int $offset Offset + * @param boolean $count If true returns a count of entities (default false) + * @param int $site_guid Site to get entities for. Default 0 = current site. -1 = any + * * @return array|int|false An array of entities, or the number of entities, or false on failure */ -function get_noteable_entities_from_relationship($start_time, $end_time, $relationship, $relationship_guid, $inverse_relationship = false, $type = "", $subtype = "", $owner_guid = 0, $order_by = "", $limit = 10, $offset = 0, $count = false, $site_guid = 0) { +function get_noteable_entities_from_relationship($start_time, $end_time, $relationship, +$relationship_guid, $inverse_relationship = false, $type = "", $subtype = "", $owner_guid = 0, +$order_by = "", $limit = 10, $offset = 0, $count = false, $site_guid = 0) { + global $CONFIG; $start_time = (int)$start_time; @@ -324,11 +356,12 @@ function get_noteable_entities_from_relationship($start_time, $end_time, $relati $where = array(); - if ($relationship!="") { + if ($relationship != "") { $where[] = "r.relationship='$relationship'"; } if ($relationship_guid) { - $where[] = ($inverse_relationship ? "r.guid_two='$relationship_guid'" : "r.guid_one='$relationship_guid'"); + $where[] = $inverse_relationship ? + "r.guid_two='$relationship_guid'" : "r.guid_one='$relationship_guid'"; } if ($type != "") { $where[] = "e.type='$type'"; @@ -369,7 +402,9 @@ function get_noteable_entities_from_relationship($start_time, $end_time, $relati } else { $query = "SELECT distinct e.* "; } - $query .= " from {$CONFIG->dbprefix}entity_relationships r JOIN {$CONFIG->dbprefix}entities e on $joinon $cal_join where "; + $query .= " from {$CONFIG->dbprefix}entity_relationships r" + . " JOIN {$CONFIG->dbprefix}entities e on $joinon $cal_join where "; + foreach ($where as $w) { $query .= " $w and "; } @@ -389,66 +424,84 @@ function get_noteable_entities_from_relationship($start_time, $end_time, $relati /** * Get all entities for today. * - * @param string $type The type of entity (eg "user", "object" etc) - * @param string $subtype The arbitrary subtype of the entity - * @param int $owner_guid The GUID of the owning user - * @param string $order_by The field to order by; by default, time_created desc - * @param int $limit The number of entities to return; 10 by default - * @param int $offset The indexing offset, 0 by default - * @param boolean $count Set to true to get a count rather than the entities themselves (limits and offsets don't apply in this context). Defaults to false. - * @param int $site_guid The site to get entities for. Leave as 0 (default) for the current site; -1 for all sites. - * @param int|array $container_guid The container or containers to get entities from (default: all containers). + * @param string $type The type of entity (eg "user", "object" etc) + * @param string $subtype The arbitrary subtype of the entity + * @param int $owner_guid The GUID of the owning user + * @param string $order_by The field to order by; by default, time_created desc + * @param int $limit The number of entities to return; 10 by default + * @param int $offset The indexing offset, 0 by default + * @param boolean $count If true returns a count of entities (default false) + * @param int $site_guid Site to get entities for. Default 0 = current site. -1 = any + * @param mixed $container_guid Container(s) to get entities from (default: any). + * + * @return array|false */ -function get_todays_entities($type = "", $subtype = "", $owner_guid = 0, $order_by = "", $limit = 10, $offset = 0, $count = false, $site_guid = 0, $container_guid = null) { +function get_todays_entities($type = "", $subtype = "", $owner_guid = 0, $order_by = "", +$limit = 10, $offset = 0, $count = false, $site_guid = 0, $container_guid = null) { + $day_start = get_day_start(); $day_end = get_day_end(); - return get_notable_entities($day_start, $day_end, $type, $subtype, $owner_guid, $order_by, $limit, $offset, $count, $site_guid, $container_guid); + return get_notable_entities($day_start, $day_end, $type, $subtype, $owner_guid, $order_by, + $limit, $offset, $count, $site_guid, $container_guid); } /** * Get entities for today from metadata. * - * @param mixed $meta_name - * @param mixed $meta_value - * @param string $entity_type The type of entity to look for, eg 'site' or 'object' + * @param mixed $meta_name Metadata name + * @param mixed $meta_value Metadata value + * @param string $entity_type The type of entity to look for, eg 'site' or 'object' * @param string $entity_subtype The subtype of the entity. - * @param int $limit - * @param int $offset - * @param string $order_by Optional ordering. - * @param int $site_guid The site to get entities for. Leave as 0 (default) for the current site; -1 for all sites. - * @param true|false $count If set to true, returns the total number of entities rather than a list. (Default: false) + * @param int $owner_guid Owner GUID + * @param int $limit Limit + * @param int $offset Offset + * @param string $order_by Optional ordering. + * @param int $site_guid Site to get entities for. Default 0 = current site. -1 = any. + * @param bool $count If true, returns count instead of entities. (Default: false) * * @return int|array A list of entities, or a count if $count is set to true */ -function get_todays_entities_from_metadata($meta_name, $meta_value = "", $entity_type = "", $entity_subtype = "", $owner_guid = 0, $limit = 10, $offset = 0, $order_by = "", $site_guid = 0, $count = false) { +function get_todays_entities_from_metadata($meta_name, $meta_value = "", $entity_type = "", +$entity_subtype = "", $owner_guid = 0, $limit = 10, $offset = 0, $order_by = "", $site_guid = 0, +$count = false) { + $day_start = get_day_start(); $day_end = get_day_end(); - return get_notable_entities_from_metadata($day_start, $day_end, $meta_name, $meta_value, $entity_type, $entity_subtype, $owner_guid, $limit, $offset, $order_by, $site_guid, $count); + return get_notable_entities_from_metadata($day_start, $day_end, $meta_name, $meta_value, + $entity_type, $entity_subtype, $owner_guid, $limit, $offset, $order_by, $site_guid, $count); } /** * Get entities for today from a relationship * - * @param string $relationship The relationship eg "friends_of" - * @param int $relationship_guid The guid of the entity to use query - * @param bool $inverse_relationship Reverse the normal function of the query to instead say "give me all entities for whome $relationship_guid is a $relationship of" - * @param string $type - * @param string $subtype - * @param int $owner_guid - * @param string $order_by - * @param int $limit - * @param int $offset - * @param boolean $count Set to true if you want to count the number of entities instead (default false) - * @param int $site_guid The site to get entities for. Leave as 0 (default) for the current site; -1 for all sites. + * @param string $relationship The relationship eg "friends_of" + * @param int $relationship_guid The guid of the entity to use query + * @param bool $inverse_relationship Reverse the normal function of the query to say + * "give me all entities for whom $relationship_guid is a + * $relationship of" + * @param string $type Entity type + * @param string $subtype Entity subtype + * @param int $owner_guid Owner GUID + * @param string $order_by Optional Order by + * @param int $limit Limit + * @param int $offset Offset + * @param boolean $count If true returns a count of entities (default false) + * @param int $site_guid Site to get entities for. Default 0 = current site. -1 = any + * * @return array|int|false An array of entities, or the number of entities, or false on failure */ -function get_todays_entities_from_relationship($relationship, $relationship_guid, $inverse_relationship = false, $type = "", $subtype = "", $owner_guid = 0, $order_by = "", $limit = 10, $offset = 0, $count = false, $site_guid = 0) { +function get_todays_entities_from_relationship($relationship, $relationship_guid, +$inverse_relationship = false, $type = "", $subtype = "", $owner_guid = 0, +$order_by = "", $limit = 10, $offset = 0, $count = false, $site_guid = 0) { + $day_start = get_day_start(); $day_end = get_day_end(); - return get_notable_entities_from_relationship($day_start, $day_end, $relationship, $relationship_guid, $inverse_relationship, $type, $subtype, $owner_guid, $order_by, $limit, $offset, $count, $site_guid); + return get_notable_entities_from_relationship($day_start, $day_end, $relationship, + $relationship_guid, $inverse_relationship, $type, $subtype, $owner_guid, $order_by, + $limit, $offset, $count, $site_guid); } /** @@ -456,23 +509,30 @@ function get_todays_entities_from_relationship($relationship, $relationship_guid * * @see elgg_view_entity_list * - * @param int $start_time The start time as a unix timestamp. - * @param int $end_time The end time as a unix timestamp. - * @param string $type The type of entity (eg "user", "object" etc) - * @param string $subtype The arbitrary subtype of the entity - * @param int $owner_guid The GUID of the owning user - * @param int $limit The number of entities to display per page (default: 10) - * @param true|false $fullview Whether or not to display the full view (default: true) - * @param true|false $viewtypetoggle Whether or not to allow gallery view - * @param true|false $pagination Display pagination? Default: true + * @param int $start_time The start time as a unix timestamp. + * @param int $end_time The end time as a unix timestamp. + * @param string $type The type of entity (eg "user", "object" etc) + * @param string $subtype The arbitrary subtype of the entity + * @param int $owner_guid The GUID of the owning user + * @param int $limit The number of entities to return; 10 by default + * @param boolean $fullview Whether or not to display the full view (default: true) + * @param boolean $viewtypetoggle Whether or not to allow gallery view + * @param boolean $navigation Display pagination? Default: true + * * @return string A viewable list of entities */ -function list_notable_entities($start_time, $end_time, $type= "", $subtype = "", $owner_guid = 0, $limit = 10, $fullview = true, $viewtypetoggle = false, $navigation = true) { +function list_notable_entities($start_time, $end_time, $type= "", $subtype = "", $owner_guid = 0, +$limit = 10, $fullview = true, $viewtypetoggle = false, $navigation = true) { + $offset = (int) get_input('offset'); - $count = get_notable_entities($start_time, $end_time, $type, $subtype, $owner_guid, "", $limit, $offset, true); - $entities = get_notable_entities($start_time, $end_time,$type, $subtype, $owner_guid, "", $limit, $offset); + $count = get_notable_entities($start_time, $end_time, $type, $subtype, + $owner_guid, "", $limit, $offset, true); + + $entities = get_notable_entities($start_time, $end_time, $type, $subtype, + $owner_guid, "", $limit, $offset); - return elgg_view_entity_list($entities, $count, $offset, $limit, $fullview, $viewtypetoggle, $navigation); + return elgg_view_entity_list($entities, $count, $offset, $limit, + $fullview, $viewtypetoggle, $navigation); } /** @@ -480,18 +540,22 @@ function list_notable_entities($start_time, $end_time, $type= "", $subtype = "", * * @see list_notable_entities * - * @param string $type The type of entity (eg "user", "object" etc) - * @param string $subtype The arbitrary subtype of the entity - * @param int $owner_guid The GUID of the owning user - * @param int $limit The number of entities to display per page (default: 10) - * @param true|false $fullview Whether or not to display the full view (default: true) - * @param true|false $viewtypetoggle Whether or not to allow gallery view - * @param true|false $pagination Display pagination? Default: true + * @param string $type The type of entity (eg "user", "object" etc) + * @param string $subtype The arbitrary subtype of the entity + * @param int $owner_guid The GUID of the owning user + * @param int $limit The number of entities to return; 10 by default + * @param boolean $fullview Whether or not to display the full view (default: true) + * @param boolean $viewtypetoggle Whether or not to allow gallery view + * @param boolean $navigation Display pagination? Default: true + * * @return string A viewable list of entities */ -function list_todays_entities($type= "", $subtype = "", $owner_guid = 0, $limit = 10, $fullview = true, $viewtypetoggle = false, $navigation = true) { +function list_todays_entities($type= "", $subtype = "", $owner_guid = 0, $limit = 10, +$fullview = true, $viewtypetoggle = false, $navigation = true) { + $day_start = get_day_start(); $day_end = get_day_end(); - return list_notable_entities($day_start, $day_end, $type, $subtype, $owner_guid, $limit, $fullview, $viewtypetoggle, $navigation); + return list_notable_entities($day_start, $day_end, $type, $subtype, $owner_guid, $limit, + $fullview, $viewtypetoggle, $navigation); }
\ No newline at end of file diff --git a/engine/lib/configuration.php b/engine/lib/configuration.php index 0394cc770..d8c11b485 100644 --- a/engine/lib/configuration.php +++ b/engine/lib/configuration.php @@ -24,9 +24,11 @@ * These settings are stored in the dbprefix_config table and read during system * boot into $CONFIG. * - * @param string $name The name of the field. - * @param int $site_guid Optionally, the GUID of the site (current site is assumed by default). + * @param string $name The name of the field. + * @param int $site_guid Optionally, the GUID of the site (current site is assumed by default). + * * @return int|false The number of affected rows or false on error. + * * @see get_config() * @see set_config() */ @@ -39,7 +41,8 @@ function unset_config($name, $site_guid = 0) { $site_guid = (int) $CONFIG->site_id; } - return delete_data("delete from {$CONFIG->dbprefix}config where name='$name' and site_guid=$site_guid"); + $query = "delete from {$CONFIG->dbprefix}config where name='$name' and site_guid=$site_guid"; + return delete_data($query); } /** @@ -51,9 +54,10 @@ function unset_config($name, $site_guid = 0) { * These settings are stored in the dbprefix_config table and read during system * boot into $CONFIG. * - * @param string $name The name of the configuration value - * @param string $value Its value - * @param int $site_guid Optionally, the GUID of the site (current site is assumed by default) + * @param string $name The name of the configuration value + * @param string $value Its value + * @param int $site_guid Optionally, the GUID of the site (current site is assumed by default) + * * @return 0 * @todo The config table doens't have numeric primary keys so insert_data returns 0. * @todo Use "INSERT ... ON DUPLICATE KEY UPDATE" instead of trying to delete then add. @@ -73,7 +77,9 @@ function set_config($name, $value, $site_guid = 0) { $CONFIG->$name = $value; $value = sanitise_string(serialize($value)); - return insert_data("insert into {$CONFIG->dbprefix}config set name = '{$name}', value = '{$value}', site_guid = {$site_guid}"); + $query = "insert into {$CONFIG->dbprefix}config" + . " set name = '{$name}', value = '{$value}', site_guid = {$site_guid}"; + return insert_data($query); } /** @@ -83,8 +89,9 @@ function set_config($name, $value, $site_guid = 0) { * These settings are stored in the dbprefix_config table and read during system * boot into $CONFIG. * - * @param string $name The name of the config value - * @param int $site_guid Optionally, the GUID of the site (current site is assumed by default) + * @param string $name The name of the config value + * @param int $site_guid Optionally, the GUID of the site (current site is assumed by default) + * * @return mixed|false * @see set_config() * @see unset_config() @@ -115,6 +122,7 @@ function get_config($name, $site_guid = 0) { * Loads all configuration values from the dbprefix_config table into $CONFIG. * * @param int $site_guid Optionally, the GUID of the site (current site is assumed by default) + * * @return bool */ function get_all_config($site_guid = 0) { @@ -141,12 +149,14 @@ function get_all_config($site_guid = 0) { /** * Sets defaults for or attempts to autodetect some common config values and * loads them into $CONFIG. + * + * @return void */ function set_default_config() { global $CONFIG; if (empty($CONFIG->path)) { - $CONFIG->path = str_replace("\\","/",dirname(dirname(dirname(__FILE__)))) . "/"; + $CONFIG->path = str_replace("\\", "/", dirname(dirname(dirname(__FILE__)))) . "/"; } if (empty($CONFIG->viewpath)) { @@ -170,8 +180,8 @@ function set_default_config() { $CONFIG->wwwroot .= $request; */ - $pathpart = str_replace("//","/",str_replace($_SERVER['DOCUMENT_ROOT'],"",$CONFIG->path)); - if (substr($pathpart,0,1) != "/") { + $pathpart = str_replace("//", "/", str_replace($_SERVER['DOCUMENT_ROOT'], "", $CONFIG->path)); + if (substr($pathpart, 0, 1) != "/") { $pathpart = "/" . $pathpart; } $CONFIG->wwwroot = "http://" . $_SERVER['HTTP_HOST'] . $pathpart; diff --git a/engine/lib/cron.php b/engine/lib/cron.php index c89a52395..811a4cdda 100644 --- a/engine/lib/cron.php +++ b/engine/lib/cron.php @@ -9,11 +9,12 @@ /** * Initialisation * + * @return void */ function cron_init() { // Register a pagehandler for cron - register_page_handler('cron','cron_page_handler'); - + register_page_handler('cron', 'cron_page_handler'); + // register a hook for Walled Garden public pages register_plugin_hook('public_pages', 'walled_garden', 'cron_public_pages'); } @@ -21,7 +22,9 @@ function cron_init() { /** * Cron handler for redirecting pages. * - * @param unknown_type $page + * @param array $page Pages + * + * @return void */ function cron_page_handler($page) { global $CONFIG; @@ -51,6 +54,16 @@ function cron_page_handler($page) { } } +/** + * Register cron's pages as public in case we're in Walled Garden mode + * + * @param string $hook public_pages + * @param string $type system + * @param array $return_value Array of pages to allow + * @param mixed $params Params + * + * @return array + */ function cron_public_pages($hook, $type, $return_value, $params) { $return_value[] = 'pg/cron/minute'; $return_value[] = 'pg/cron/fiveminute'; @@ -62,9 +75,9 @@ function cron_public_pages($hook, $type, $return_value, $params) { $return_value[] = 'pg/cron/monthly'; $return_value[] = 'pg/cron/yearly'; $return_value[] = 'pg/cron/reboot'; - + return $return_value; } // Register a startup event -register_elgg_event_handler('init','system','cron_init');
\ No newline at end of file +register_elgg_event_handler('init', 'system', 'cron_init');
\ No newline at end of file diff --git a/engine/lib/database.php b/engine/lib/database.php index 76ca6c193..4b0a38bb3 100644 --- a/engine/lib/database.php +++ b/engine/lib/database.php @@ -64,7 +64,10 @@ $dbcalls = 0; * * Connect to the database server and use the Elgg database for a particular database link * - * @param string $dblinkname The type of database connection. Used to identify the resource. eg "read", "write", or "readwrite". + * @param string $dblinkname The type of database connection. Used to identify the + * resource. eg "read", "write", or "readwrite". + * + * @return void */ function establish_db_link($dblinkname = "readwrite") { // Get configuration, and globalise database link @@ -72,7 +75,7 @@ function establish_db_link($dblinkname = "readwrite") { if ($dblinkname != "readwrite" && isset($CONFIG->db[$dblinkname])) { if (is_array($CONFIG->db[$dblinkname])) { - $index = rand(0,sizeof($CONFIG->db[$dblinkname])); + $index = rand(0, sizeof($CONFIG->db[$dblinkname])); $dbhost = $CONFIG->db[$dblinkname][$index]->dbhost; $dbuser = $CONFIG->db[$dblinkname][$index]->dbuser; $dbpass = $CONFIG->db[$dblinkname][$index]->dbpass; @@ -121,6 +124,8 @@ function establish_db_link($dblinkname = "readwrite") { * * If the configuration has been set up for multiple read/write databases, set those * links up separately; otherwise just create the one database link. + * + * @return void */ function setup_db_connections() { global $CONFIG, $dblink; @@ -135,6 +140,8 @@ function setup_db_connections() { /** * Display profiling information about db at NOTICE debug level upon shutdown. + * + * @return void */ function db_profiling_shutdown_hook() { global $dbcalls; @@ -145,6 +152,8 @@ function db_profiling_shutdown_hook() { /** * Execute any delayed queries upon shutdown. + * + * @return void */ function db_delayedexecution_shutdown_hook() { global $DB_DELAYED_QUERIES, $CONFIG; @@ -169,9 +178,7 @@ function db_delayedexecution_shutdown_hook() { * * @note Database connections are established upon first call to database. * - * @param string $event The event type - * @param string $object_type The object type - * @param mixed $object Used for nothing in this context + * @return true * @elgg_event_handler boot system */ function init_db() { @@ -189,6 +196,7 @@ function init_db() { * no links exist. * * @param string $dblinktype The type of link we want: "read", "write" or "readwrite". + * * @return object Database link */ function get_db_link($dblinktype) { @@ -207,8 +215,9 @@ function get_db_link($dblinktype) { /** * Execute an EXPLAIN for $query. * - * @param str $query The query to explain - * @param mixed $link The database link resource to user. + * @param str $query The query to explain + * @param mixed $link The database link resource to user. + * * @return mixed An object of the query's result, or FALSE */ function explain_query($query, $link) { @@ -228,8 +237,9 @@ function explain_query($query, $link) { * @internal * {@link $dbcalls} is incremented and the query is saved into the {@link $DB_QUERY_CACHE}. * - * @param string $query The query - * @param link $dblink the DB link + * @param string $query The query + * @param link $dblink The DB link + * * @return The result of mysql_query() * @throws DatabaseException */ @@ -256,9 +266,11 @@ function execute_query($query, $dblink) { * You can specify a handler function if you care about the result. This function will accept * the raw result from {@link mysql_query()}. * - * @param string $query The query to execute - * @param resource $dblink The database link to use - * @param string $handler A callback function to pass the results array to + * @param string $query The query to execute + * @param resource $dblink The database link to use + * @param string $handler A callback function to pass the results array to + * + * @return true */ function execute_delayed_query($query, $dblink, $handler = "") { global $DB_DELAYED_QUERIES; @@ -281,8 +293,10 @@ function execute_delayed_query($query, $dblink, $handler = "") { /** * Write wrapper for execute_delayed_query() * - * @param string $query The query to execute + * @param string $query The query to execute * @param string $handler The handler if you care about the result. + * + * @return true * @uses execute_delayed_query() * @uses get_db_link() */ @@ -293,8 +307,10 @@ function execute_delayed_write_query($query, $handler = "") { /** * Read wrapper for execute_delayed_query() * - * @param string $query The query to execute + * @param string $query The query to execute * @param string $handler The handler if you care about the result. + * + * @return true * @uses execute_delayed_query() * @uses get_db_link() */ @@ -313,8 +329,9 @@ function execute_delayed_read_query($query, $handler = "") { * * If no results are matched, FALSE is returned. * - * @param mixed $query The query being passed. - * @param string $call Optionally, the name of a function to call back to on each row + * @param mixed $query The query being passed. + * @param string $callback Optionally, the name of a function to call back to on each row + * * @return array|false An array of database result objects or callback function results or false */ function get_data($query, $callback = "") { @@ -372,7 +389,9 @@ function get_data($query, $callback = "") { * matched. If a callback function $callback is specified, the row will be passed * as the only argument to $callback. * - * @param mixed $query The query to execute. + * @param mixed $query The query to execute. + * @param string $callback A callback function + * * @return mixed A single database result object or the result of the callback function. */ function get_data_row($query, $callback = "") { @@ -425,7 +444,9 @@ function get_data_row($query, $callback = "") { * @note Altering the DB invalidates all queries in {@link $DB_QUERY_CACHE}. * * @param mixed $query The query to execute. - * @return int|false The database id of the inserted row if a AUTO_INCREMENT field is defined, 0 if not, and false on failure. + * + * @return int|false The database id of the inserted row if a AUTO_INCREMENT field is + * defined, 0 if not, and false on failure. */ function insert_data($query) { global $CONFIG, $DB_QUERY_CACHE; @@ -452,6 +473,7 @@ function insert_data($query) { * @note Altering the DB invalidates all queries in {@link $DB_QUERY_CACHE}. * * @param string $query The query to run. + * * @return Bool */ function update_data($query) { @@ -478,6 +500,7 @@ function update_data($query) { * @note Altering the DB invalidates all queries in {@link $DB_QUERY_CACHE}. * * @param string $query The SQL query to run + * * @return int|false The number of affected rows or false on failure */ function delete_data($query) { @@ -524,12 +547,13 @@ function get_db_tables() { $tables = array(); if (is_array($result) && !empty($result)) { - foreach($result as $row) { + foreach ($result as $row) { $row = (array) $row; - if (is_array($row) && !empty($row)) - foreach($row as $element) { + if (is_array($row) && !empty($row)) { + foreach ($row as $element) { $tables[] = $element; } + } } } else { return FALSE; @@ -544,6 +568,8 @@ function get_db_tables() { * Executes an OPTIMIZE TABLE query on $table. Useful after large DB changes. * * @param string $table The name of the table to optimise + * + * @return bool */ function optimize_table($table) { $table = sanitise_string($table); @@ -553,7 +579,8 @@ function optimize_table($table) { /** * Get the last database error for a particular database link * - * @param resource $dblink + * @param resource $dblink The DB link + * * @return string Database error message */ function get_db_error($dblink) { @@ -576,6 +603,8 @@ function get_db_error($dblink) { * are displayed as a {@link DatabaseException} * * @param string $scriptlocation The full path to the script + * + * @return void * @throws DatabaseException */ function run_sql_script($scriptlocation) { @@ -588,11 +617,11 @@ function run_sql_script($scriptlocation) { $script = preg_replace('/\-\-.*\n/', '', $script); // Statements must end with ; and a newline - $sql_statements = preg_split('/;[\n\r]+/', $script); + $sql_statements = preg_split('/;[\n\r]+/', $script); - foreach($sql_statements as $statement) { + foreach ($sql_statements as $statement) { $statement = trim($statement); - $statement = str_replace("prefix_",$CONFIG->dbprefix,$statement); + $statement = str_replace("prefix_", $CONFIG->dbprefix, $statement); if (!empty($statement)) { try { $result = update_data($statement); @@ -603,13 +632,16 @@ function run_sql_script($scriptlocation) { } if (!empty($errors)) { $errortxt = ""; - foreach($errors as $error) { + foreach ($errors as $error) { $errortxt .= " {$error};"; } - throw new DatabaseException(elgg_echo('DatabaseException:DBSetupIssues') . $errortxt); + + $msg = elgg_echo('DatabaseException:DBSetupIssues') . $errortxt; + throw new DatabaseException($msg); } } else { - throw new DatabaseException(sprintf(elgg_echo('DatabaseException:ScriptNotFound'), $scriptlocation)); + $msg = sprintf(elgg_echo('DatabaseException:ScriptNotFound'), $scriptlocation); + throw new DatabaseException($msg); } } @@ -624,9 +656,10 @@ function run_sql_script($scriptlocation) { * * @warning Plugin authors should not call this function directly. * - * @param int $version The version you are upgrading from in the format YYYYMMDDII. - * @param string $fromdir Optional directory to load upgrades from (default: engine/schema/upgrades/) - * @param bool $quiet If true, will suppress all error messages. Should be used only for the upgrade from version <=1.6. + * @param int $version The version you are upgrading from in the format YYYYMMDDII. + * @param string $fromdir Optional directory to load upgrades from. default: engine/schema/upgrades/ + * @param bool $quiet If true, suppress all error messages. Only use for the upgrade from <=1.6. + * * @return bool * @see upgrade.php * @see version.php @@ -662,7 +695,7 @@ function db_upgrade($version, $fromdir = "", $quiet = FALSE) { asort($sqlupgrades); if (sizeof($sqlupgrades) > 0) { - foreach($sqlupgrades as $sqlfile) { + foreach ($sqlupgrades as $sqlfile) { // hide all errors. if ($quiet) { @@ -684,8 +717,9 @@ function db_upgrade($version, $fromdir = "", $quiet = FALSE) { /** * Sanitise a string for database use, but with the option of escaping extra characters. * - * @param string $string The string to sanitise + * @param string $string The string to sanitise * @param string $extra_escapeable Extra characters to escape with '\\' + * * @return string The escaped string */ function sanitise_string_special($string, $extra_escapeable = '') { @@ -702,6 +736,7 @@ function sanitise_string_special($string, $extra_escapeable = '') { * Sanitise a string for database use. * * @param string $string The string to sanitise + * * @return string Sanitised string */ function sanitise_string($string) { @@ -714,6 +749,7 @@ function sanitise_string($string) { * Wrapper function for alternate English spelling * * @param string $string The string to sanitise + * * @return string Sanitised string */ function sanitize_string($string) { @@ -723,7 +759,8 @@ function sanitize_string($string) { /** * Sanitises an integer for database use. * - * @param int $int + * @param int $int Integer + * * @return int Sanitised integer */ function sanitise_int($int) { @@ -733,7 +770,8 @@ function sanitise_int($int) { /** * Wrapper function for alternate English spelling * - * @param int $int + * @param int $int Integer + * * @return int Sanitised integer */ function sanitize_int($int) { diff --git a/engine/lib/elgglib.php b/engine/lib/elgglib.php index 81be96752..4d51e6d7d 100644 --- a/engine/lib/elgglib.php +++ b/engine/lib/elgglib.php @@ -2,17 +2,24 @@ /** * Bootstrapping and helper procedural code available for use in Elgg core and plugins. * - * * @package Elgg.Core * @todo These functions can't be subpackaged because they cover a wide mix of - * puposes and subsystems. Many of them should be moved to more relevant files. + * purposes and subsystems. Many of them should be moved to more relevant files. */ // prep core classes to be autoloadable -spl_autoload_register('__elgg_autoload'); +spl_autoload_register('_elgg_autoload'); elgg_register_classes(dirname(dirname(__FILE__)) . '/classes'); -function __elgg_autoload($class) { +/** + * Autoload classes + * + * @param string $class The name of the class + * + * @return void + * @throws Exception + */ +function _elgg_autoload($class) { global $CONFIG; if (!include($CONFIG->classes[$class])) { @@ -20,6 +27,14 @@ function __elgg_autoload($class) { } } +/** + * Register all files found in $dir as classes + * Need to be named MyClass.php + * + * @param string $dir The dir to look in + * + * @return void + */ function elgg_register_classes($dir) { $classes = elgg_get_file_list($dir, array(), array(), array('.php')); @@ -28,6 +43,14 @@ function elgg_register_classes($dir) { } } +/** + * Register a classname to a file. + * + * @param string $class The name of the class + * @param string $location The location of the file + * + * @return void + */ function elgg_register_class($class, $location) { global $CONFIG; @@ -41,9 +64,11 @@ function elgg_register_class($class, $location) { /** * Forward to $location. * - * Sends a 'Location: $location' header and exists. If headers have already been sent, returns FALSE. + * Sends a 'Location: $location' header and exists. If headers have + * already been sent, returns FALSE. * * @param string $location URL to forward to browser to. Can be path relative to the network's URL. + * * @return False False if headers have been sent. Terminates execution if forwarding. */ function forward($location = "") { @@ -95,11 +120,11 @@ function current_page_url() { $page .= $url['user']; } if ((isset($url['pass'])) && ($url['pass'])) { - $page .= ":".$url['pass']; + $page .= ":" . $url['pass']; } if ((isset($url['user']) && $url['user']) || (isset($url['pass']) && $url['pass'])) { - $page .="@"; + $page .= "@"; } $page .= $url['host']; @@ -154,6 +179,7 @@ function elgg_filepath_cache_reset() { * 'view_paths'. * * @param mixed $data The data + * * @return bool On success */ function elgg_filepath_cache_save($data) { @@ -170,7 +196,8 @@ function elgg_filepath_cache_save($data) { /** * Returns the contents of the views file paths cache from disk. * - * @return mixed Null if simplecache isn't enabled, the contents of the views file paths cache if it is. + * @return mixed Null if simplecache isn't enabled, the contents of the + * views file paths cache if it is. */ function elgg_filepath_cache_load() { global $CONFIG; @@ -224,6 +251,14 @@ function elgg_disable_filepath_cache() { * * @see elgg_add_submenu_item() * @deprecated 1.8 + * + * @param string $label The label + * @param string $link The link + * @param string $group The group to store item in + * @param boolean $onclick Add a confirmation when clicked? + * @param boolean $selected Is menu item selected + * + * @return bool */ function add_submenu_item($label, $link, $group = 'default', $onclick = false, $selected = NULL) { elgg_deprecated_notice('add_submenu_item was deprecated by elgg_add_submenu_item', 1.8); @@ -239,7 +274,7 @@ function add_submenu_item($label, $link, $group = 'default', $onclick = false, $ } if ($onclick) { - $js = "onclick=\"javascript:return confirm('". elgg_echo('deleteconfirm') . "')\""; + $js = "onclick=\"javascript:return confirm('" . elgg_echo('deleteconfirm') . "')\""; $item['vars'] = array('js' => $js); } // submenu items were added in the page setup hook usually by checking @@ -258,7 +293,7 @@ function add_submenu_item($label, $link, $group = 'default', $onclick = false, $ /** * Add an entry to the submenu. * - * @param array $item The item as: + * @param array $item The item as: * <code> * array( * 'title' => 'Text to display', @@ -270,8 +305,10 @@ function add_submenu_item($label, $link, $group = 'default', $onclick = false, $ * ) * </code> * - * @param string $context Context in which to display this menu item. 'all' will make it show up all the time. Use sparingly. - * @param string $group Group for the item. Each submenu group has its own <ul> + * @param string $context Context in which to display this menu item. 'all' + * will make it show up all the time. Use sparingly. + * @param string $group Group for the item. Each submenu group has its own <ul> + * * @return BOOL * @since 1.8 * @see elgg_prepare_submenu @@ -323,10 +360,13 @@ function elgg_add_submenu_item(array $item, $context = 'all', $group = 'default' /** * Properly nest all submenu entries for contexts $context and 'all' * - * @param string $context - * @param bool $sort Sort the menu items alphabetically + * @param string $context Context for menus + * @param bool $sort Sort the menu items alphabetically + * * @since 1.8 * @see elgg_add_submenu_item + * + * @return true */ function elgg_prepare_submenu($context = 'main', $sort = FALSE) { global $CONFIG; @@ -412,8 +452,10 @@ function elgg_prepare_submenu($context = 'main', $sort = FALSE) { /** * Helper function used to sort submenu items by their display text. * - * @param object $a - * @param object $b + * @param object $a First object + * @param object $b Second object + * + * @return int * @since 1.8 * @see elgg_prepare_submenu */ @@ -429,6 +471,8 @@ function elgg_submenu_item_cmp($a, $b) { * * @see elgg_get_submenu() * @deprecated 1.8 + * + * @return string */ function get_submenu() { elgg_deprecated_notice("get_submenu() has been deprecated by elgg_get_submenu()", 1.8); @@ -439,7 +483,8 @@ function get_submenu() { * Return the HTML for a sidemenu. * * @param string $context The context of the submenu (defaults to main) - * @param BOOL $sort Sort by display name? + * @param BOOL $sort Sort by display name? + * * @return string Formatted HTML. * @since 1.8 * @todo Rename to a view function. See {@trac #2320}. @@ -500,7 +545,7 @@ function elgg_get_submenu($context = NULL, $sort = FALSE) { if ($item = next($items)) { continue; } else { - while($depth > 0) { + while ($depth > 0) { $depth--; $items = array_pop($temp_items); if ($item = next($items)) { @@ -513,7 +558,8 @@ function elgg_get_submenu($context = NULL, $sort = FALSE) { } } - $submenu_html .= elgg_view('navigation/submenu_group', array('group' => $group, 'items' => $items)); + $vars = array('group' => $group, 'items' => $items); + $submenu_html .= elgg_view('navigation/submenu_group', $vars); } // include the JS for the expand menus too @@ -524,11 +570,13 @@ function elgg_get_submenu($context = NULL, $sort = FALSE) { * Returns the HTML for "likes" and "like this" on entities. * * @param ElggEntity $entity The entity to like + * * @return string|false The HTML for the likes, or false on failure + * * @since 1.8 * @see @elgg_view likes/forms/edit */ -function elgg_view_likes($entity){ +function elgg_view_likes($entity) { if (!($entity instanceof ElggEntity)) { return false; } @@ -544,7 +592,8 @@ function elgg_view_likes($entity){ /** * Count the number of likes attached to an entity * - * @param ElggEntity $entity + * @param ElggEntity $entity The entity to count likes for + * * @return int Number of likes * @since 1.8 */ @@ -560,7 +609,8 @@ function elgg_count_likes($entity) { /** * Count the number of comments attached to an entity * - * @param ElggEntity $entity + * @param ElggEntity $entity The entity to count comments for + * * @return int Number of comments */ function elgg_count_comments($entity) { @@ -573,7 +623,15 @@ function elgg_count_comments($entity) { } /** - * @deprecated 1.7 + * Returns all php files in a directory. + * + * @deprecated 1.7 Use elgg_get_file_list() instead + * + * @param string $directory Directory to look in + * @param array $exceptions Array of extensions (with .!) to ignore + * @param array $list A list files to include in the return + * + * @return array */ function get_library_files($directory, $exceptions = array(), $list = array()) { elgg_deprecated_notice('get_library_files() deprecated by elgg_get_file_list()', 1.7); @@ -585,13 +643,16 @@ function get_library_files($directory, $exceptions = array(), $list = array()) { * * Only returns files. Does not recurse into subdirs. * - * @param string $directory - * @param array $exceptions Array of filenames to ignore - * @param array $list Array of files to append to - * @param mixed $extensions Array of extensions to allow, NULL for all. Use a dot: array('.php'). + * @param string $directory Directory to look in + * @param array $exceptions Array of filenames to ignore + * @param array $list Array of files to append to + * @param mixed $extensions Array of extensions to allow, NULL for all. Use a dot: array('.php'). + * * @return array Filenames in $directory, in the form $directory/filename. */ -function elgg_get_file_list($directory, $exceptions = array(), $list = array(), $extensions = NULL) { +function elgg_get_file_list($directory, $exceptions = array(), $list = array(), +$extensions = NULL) { + $directory = sanitise_filepath($directory); if ($handle = opendir($directory)) { while (($file = readdir($handle)) !== FALSE) { @@ -616,7 +677,9 @@ function elgg_get_file_list($directory, $exceptions = array(), $list = array(), /** * Sanitise file paths ensuring that they begin and end with slashes etc. * - * @param string $path The path + * @param string $path The path + * @param bool $append_slash Add tailing slash + * * @return string */ function sanitise_filepath($path, $append_slash = TRUE) { @@ -641,14 +704,17 @@ function sanitise_filepath($path, $append_slash = TRUE) { * * This is only used for the site-wide menu. See {@link add_menu()}. * - * @param string $register_name The name of the top-level register - * @param string $subregister_name The name of the subregister - * @param mixed $subregister_value The value of the subregister - * @param array $children_array Optionally, an array of children + * @param string $register_name The name of the top-level register + * @param string $subregister_name The name of the subregister + * @param mixed $subregister_value The value of the subregister + * @param array $children_array Optionally, an array of children + * * @return true|false Depending on success * @todo Can be deprecated when the new menu system is introduced. */ -function add_to_register($register_name, $subregister_name, $subregister_value, $children_array = array()) { +function add_to_register($register_name, $subregister_name, $subregister_value, +$children_array = array()) { + global $CONFIG; if (empty($register_name) || empty($subregister_name)) { @@ -680,8 +746,9 @@ function add_to_register($register_name, $subregister_name, $subregister_value, * * This is used to by {@link remove_menu()} to remove site-wide menu items. * - * @param string $register_name The name of the top-level register + * @param string $register_name The name of the top-level register * @param string $subregister_name The name of the subregister + * * @return true|false Depending on success * @since 1.7.0 * @todo Can be deprecated when the new menu system is introduced. @@ -712,9 +779,10 @@ function remove_from_register($register_name, $subregister_name) { /** * Constructs and returns a register object. * - * @param string $register_name The name of the register - * @param mixed $register_value The value of the register - * @param array $children_array Optionally, an array of children + * @param string $register_name The name of the register + * @param mixed $register_value The value of the register + * @param array $children_array Optionally, an array of children + * * @return false|stdClass Depending on success * @todo Can be deprecated when the new menu system is introduced. */ @@ -736,6 +804,7 @@ function make_register_object($register_name, $register_value, $children_array = * If it exists, returns a particular register as an array * * @param string $register_name The name of the register + * * @return array|false Depending on success * @todo Can be deprecated when the new menu system is introduced. */ @@ -754,10 +823,11 @@ function get_register($register_name) { * * You can obtain the menu array by calling {@link get_register('menu')} * - * @param string $menu_name The name of the menu item - * @param string $menu_url The URL of the page - * @param array $menu_children Optionally, an array of submenu items (not currently used) - * @param string $context + * @param string $menu_name The name of the menu item + * @param string $menu_url The URL of the page + * @param array $menu_children Optionally, an array of submenu items (not currently used) + * @param string $context The context of the menu + * * @return true|false Depending on success * @todo Can be deprecated when the new menu system is introduced. */ @@ -784,6 +854,7 @@ function add_menu($menu_name, $menu_url, $menu_children = array(), $context = "" * Removes an item from the menu register * * @param string $menu_name The name of the menu item + * * @return true|false Depending on success */ function remove_menu($menu_name) { @@ -795,7 +866,8 @@ function remove_menu($menu_name) { * This is not currently used in the Elgg core. * * @param string $menu_name The name of the menu item - * @param string $menu_url Its URL + * @param string $menu_url Its URL + * * @return stdClass|false Depending on success * @todo Can be deprecated when the new menu system is introduced. */ @@ -811,8 +883,9 @@ function menu_item($menu_name, $menu_url) { * for later display, usually upon next page load. * * The method of displaying these messages differs depending upon plugins and - * viewtypes. The core default viewtype retrieves messages in {@link views/default/page_shells/default.php} - * and displays messages as javascript popups. + * viewtypes. The core default viewtype retrieves messages in + * {@link views/default/page_shells/default.php} and displays messages as + * javascript popups. * * @internal Messages are stored as strings in the $_SESSION['msg'][$register] array. * @@ -824,10 +897,12 @@ function menu_item($menu_name, $menu_url) { * @important This function handles the standard {@link system_message()} ($register = * 'messages') as well as {@link register_error()} messages ($register = 'errors'). * - * @param string|array $message Optionally, a single message or array of messages to add, (default: null) - * @param string $register This allows for different types of messages: "errors", "messages" (default: messages) - * @param bool $count Count the number of messages (default: false) - * @return true|false|array Either the array of messages, or a response regarding whether the message addition was successful + * @param mixed $message Optionally, a single message or array of messages to add, (default: null) + * @param string $register Types of message: "errors", "messages" (default: messages) + * @param bool $count Count the number of messages (default: false) + * + * @return true|false|array Either the array of messages, or a response regarding + * whether the message addition was successful. * @todo Clean up. Separate registering messages and retrieving them. */ function system_messages($message = null, $register = "messages", $count = false) { @@ -860,7 +935,7 @@ function system_messages($message = null, $register = "messages", $count = false return sizeof($_SESSION['msg'][$register]); } else { $count = 0; - foreach($_SESSION['msg'] as $register => $submessages) { + foreach ($_SESSION['msg'] as $register => $submessages) { $count += sizeof($submessages); } return $count; @@ -873,6 +948,7 @@ function system_messages($message = null, $register = "messages", $count = false * Counts the number of messages, either globally or in a particular register * * @param string $register Optionally, the register + * * @return integer The number of messages */ function count_messages($register = "") { @@ -883,7 +959,9 @@ function count_messages($register = "") { * Display a system message on next page load. * * @see system_messages() + * * @param string|array $message Message or messages to add + * * @return Bool */ function system_message($message) { @@ -894,7 +972,9 @@ function system_message($message) { * Display an error on next page load. * * @see system_messages() - * @param string|array $message Error or errors to add + * + * @param string|array $error Error or errors to add + * * @return true|false Success response */ function register_error($error) { @@ -904,9 +984,20 @@ function register_error($error) { /** * Deprecated events core function. Code divided between register_elgg_event_handler() * and trigger_elgg_event(). + * + * @param string $event The type of event (eg 'init', 'update', 'delete') + * @param string $object_type The type of object (eg 'system', 'blog', 'user') + * @param string $function The name of the function that will handle the event + * @param int $priority Priority to call handler. Lower numbers called first (default 500) + * @param boolean $call Set to true to call the event rather than add to it (default false) + * @param mixed $object Optionally, the object the event is being performed on (eg a user) + * + * @return true|false Depending on success */ -function events($event = "", $object_type = "", $function = "", $priority = 500, $call = false, $object = null) { - elgg_deprecated_notice('events has been deprecated', 1.8); +function events($event = "", $object_type = "", $function = "", $priority = 500, +$call = false, $object = null) { + + elgg_deprecated_notice('events() has been deprecated.', 1.8); // leaving this here just in case someone was directly calling this internal function if (!$call) { @@ -963,15 +1054,17 @@ function events($event = "", $object_type = "", $function = "", $priority = 500, * $CONFIG->events[$event][$type][$priority] = $callback; * </code> * - * @param string $event The event type + * @param string $event The event type * @param string $object_type The object type - * @param string $callback The handler callback - * @param int $priority The priority of the event + * @param string $callback The handler callback + * @param int $priority The priority of the event + * * @return bool * @link http://docs.elgg.org/Tutorials/Plugins/Events - * @example events/basic.php Basic example of registering an event handler callback. - * @example events/advanced.php Advanced example of registering an event handler callback and halting execution. - * @example events/all.php Example of how to use the 'all' keyword. + * @example events/basic.php Basic example of registering an event handler callback. + * @example events/advanced.php Advanced example of registering an event handler + * callback and halting execution. + * @example events/all.php Example of how to use the 'all' keyword. */ function register_elgg_event_handler($event, $object_type, $callback, $priority = 500) { global $CONFIG; @@ -1009,14 +1102,16 @@ function register_elgg_event_handler($event, $object_type, $callback, $priority /** * Unregisters a callback for an event. * - * @param string $event The event type + * @param string $event The event type * @param string $object_type The object type - * @param string $callback The callback + * @param string $callback The callback + * + * @return void * @since 1.7.0 */ function unregister_elgg_event_handler($event, $object_type, $callback) { global $CONFIG; - foreach($CONFIG->events[$event][$object_type] as $key => $event_callback) { + foreach ($CONFIG->events[$event][$object_type] as $key => $event_callback) { if ($event_callback == $callback) { unset($CONFIG->events[$event][$object_type][$key]); } @@ -1046,9 +1141,10 @@ function unregister_elgg_event_handler($event, $object_type, $callback) { * @internal @tip Think of $object_type as the primary namespace element, and * $event as the secondary namespace. * - * @param string $event The event type + * @param string $event The event type * @param string $object_type The object type - * @param string $object The object involved in the event + * @param string $object The object involved in the event + * * @return bool The result of running all handler callbacks. * @link http://docs.elgg.org/Tutorials/Core/Events * @internal @example events/emit.php Basic emitting of an Elgg event. @@ -1145,10 +1241,11 @@ function trigger_elgg_event($event, $object_type, $object = null) { * @warning Unlike Elgg Events, a handler that returns false will NOT halt the * execution chain. * - * @param string $hook The name of the hook - * @param string $type The type of the hook + * @param string $hook The name of the hook + * @param string $type The type of the hook * @param callback $callback The name of a valid function or an array with object and method - * @param string $priority The priority - 0 is first, 1000 last, default is 500 + * @param string $priority The priority - 0 is first, 1000 last, default is 500 + * * @return bool * * @example hooks/register/basic.php Registering for a plugin hook and examining the variables. @@ -1191,14 +1288,16 @@ function register_plugin_hook($hook, $type, $callback, $priority = 500) { /** * Unregister a callback as a plugin hook. * - * @param string $hook The name of the hook - * @param string $entity_type The name of the type of entity (eg "user", "object" etc) - * @param callback $callback The PHP callback to be removed + * @param string $hook The name of the hook + * @param string $entity_type The name of the type of entity (eg "user", "object" etc) + * @param callback $callback The PHP callback to be removed + * + * @return void * @since 1.7.0 */ function unregister_plugin_hook($hook, $entity_type, $callback) { global $CONFIG; - foreach($CONFIG->hooks[$hook][$entity_type] as $key => $hook_callback) { + foreach ($CONFIG->hooks[$hook][$entity_type] as $key => $hook_callback) { if ($hook_callback == $callback) { unset($CONFIG->hooks[$hook][$entity_type][$key]); } @@ -1228,23 +1327,30 @@ function unregister_plugin_hook($hook, $entity_type, $callback) { * and $type both are 'all', the handler will be called for all hooks. * * @see register_plugin_hook() - * @param string $hook The name of the hook to trigger ("all" will trigger for all $types regardless of $hook value) - * @param string $type The type of the hook to trigger ("all" will trigger for all $hooks regardless of $type value) - * @param mixed $params Additional parameters to pass to the handlers - * @param mixed $returnvalue An initial return value + * + * @param string $hook The name of the hook to trigger ("all" will + * trigger for all $types regardless of $hook value) + * @param string $type The type of the hook to trigger ("all" will + * trigger for all $hooks regardless of $type value) + * @param mixed $params Additional parameters to pass to the handlers + * @param mixed $returnvalue An initial return value + * * @return mixed|null The return value of the last handler callback called * - * @example hooks/trigger/basic.php Trigger a hook that determins if execution should continue. - * @example hooks/trigger/advanced.php Trigger a hook with a default value and use the results to populate a menu. - * @example hooks/basic.php Trigger and respond to a basic plugin hook. + * @example hooks/trigger/basic.php Trigger a hook that determins if execution + * should continue. + * @example hooks/trigger/advanced.php Trigger a hook with a default value and use + * the results to populate a menu. + * @example hooks/basic.php Trigger and respond to a basic plugin hook. * @link http://docs.elgg.org/Tutorials/Plugins/Hooks */ function trigger_plugin_hook($hook, $type, $params = null, $returnvalue = null) { global $CONFIG; if (!empty($CONFIG->hooks[$hook][$type]) && is_array($CONFIG->hooks[$hook][$type])) { - foreach($CONFIG->hooks[$hook][$type] as $hookcallback) { - $temp_return_value = call_user_func_array($hookcallback, array($hook, $type, $returnvalue, $params)); + foreach ($CONFIG->hooks[$hook][$type] as $hookcallback) { + $temp_return_value = call_user_func_array($hookcallback, + array($hook, $type, $returnvalue, $params)); if (!is_null($temp_return_value)) { $returnvalue = $temp_return_value; } @@ -1252,8 +1358,9 @@ function trigger_plugin_hook($hook, $type, $params = null, $returnvalue = null) } if (!empty($CONFIG->hooks['all'][$type]) && is_array($CONFIG->hooks['all'][$type])) { - foreach($CONFIG->hooks['all'][$type] as $hookcallback) { - $temp_return_value = call_user_func_array($hookcallback, array($hook, $type, $returnvalue, $params)); + foreach ($CONFIG->hooks['all'][$type] as $hookcallback) { + $temp_return_value = call_user_func_array($hookcallback, + array($hook, $type, $returnvalue, $params)); if (!is_null($temp_return_value)) { $returnvalue = $temp_return_value; } @@ -1261,8 +1368,9 @@ function trigger_plugin_hook($hook, $type, $params = null, $returnvalue = null) } if (!empty($CONFIG->hooks[$hook]['all']) && is_array($CONFIG->hooks[$hook]['all'])) { - foreach($CONFIG->hooks[$hook]['all'] as $hookcallback) { - $temp_return_value = call_user_func_array($hookcallback, array($hook, $type, $returnvalue, $params)); + foreach ($CONFIG->hooks[$hook]['all'] as $hookcallback) { + $temp_return_value = call_user_func_array($hookcallback, + array($hook, $type, $returnvalue, $params)); if (!is_null($temp_return_value)) { $returnvalue = $temp_return_value; } @@ -1270,8 +1378,9 @@ function trigger_plugin_hook($hook, $type, $params = null, $returnvalue = null) } if (!empty($CONFIG->hooks['all']['all']) && is_array($CONFIG->hooks['all']['all'])) { - foreach($CONFIG->hooks['all']['all'] as $hookcallback) { - $temp_return_value = call_user_func_array($hookcallback, array($hook, $type, $returnvalue, $params)); + foreach ($CONFIG->hooks['all']['all'] as $hookcallback) { + $temp_return_value = call_user_func_array($hookcallback, + array($hook, $type, $returnvalue, $params)); if (!is_null($temp_return_value)) { $returnvalue = $temp_return_value; } @@ -1293,13 +1402,16 @@ function trigger_plugin_hook($hook, $type, $params = null, $returnvalue = null) * log the error or ignore it. * * @see http://www.php.net/set-error-handler - * @param int $errno The level of the error raised - * @param string $errmsg The error message + * + * @param int $errno The level of the error raised + * @param string $errmsg The error message * @param string $filename The filename the error was raised in - * @param int $linenum The line number the error was raised at - * @param array $vars An array that points to the active symbol table at the point that the error occurred + * @param int $linenum The line number the error was raised at + * @param array $vars An array that points to the active symbol table where error occurred + * + * @return true */ -function __elgg_php_error_handler($errno, $errmsg, $filename, $linenum, $vars) { +function _elgg_php_error_handler($errno, $errmsg, $filename, $linenum, $vars) { $error = date("Y-m-d H:i:s (T)") . ": \"$errmsg\" in file $filename (line $linenum)"; switch ($errno) { @@ -1338,12 +1450,14 @@ function __elgg_php_error_handler($errno, $errmsg, $filename, $linenum, $vars) { * @note No messages will be displayed unless debugging has been enabled. * * @param str $message User message - * @param str $level NOTICE | WARNING | ERROR | DEBUG + * @param str $level NOTICE | WARNING | ERROR | DEBUG + * * @return bool * @since 1.7.0 - * @todo This is complicated and confusing. Using int constants for debug levels will make things easier. + * @todo This is complicated and confusing. Using int constants for debug levels will + * make things easier. */ -function elgg_log($message, $level='NOTICE') { +function elgg_log($message, $level = 'NOTICE') { global $CONFIG; // only log when debugging is enabled @@ -1387,9 +1501,10 @@ function elgg_log($message, $level='NOTICE') { * A {@elgg_plugin_hook debug log} is called. If a handler returns * false, it will stop the default logging method. * - * @param mixed $value - * @param bool $to_screen - * @param string $level + * @param mixed $value The value + * @param bool $to_screen Display to screen? + * @param string $level The debug level + * * @return void * @since 1.7.0 */ @@ -1426,9 +1541,12 @@ function elgg_dump($value, $to_screen = TRUE, $level = 'NOTICE') { * @warning This function should never be called directly. * * @see http://www.php.net/set-exception-handler + * * @param Exception $exception The exception being handled + * + * @return void */ -function __elgg_php_exception_handler($exception) { +function _elgg_php_exception_handler($exception) { error_log("*** FATAL EXCEPTION *** : " . $exception); // Wipe any existing output buffer @@ -1462,6 +1580,7 @@ $DATALIST_CACHE = array(); * @tip Use datalists to store information common to a full installation. * * @param string $name The name of the datalist element + * * @return string|false The datalist value or false if it doesn't exist. */ function datalist_get($name) { @@ -1491,7 +1610,10 @@ function datalist_get($name) { return $value; } - // [Marcus Povey 20090217 : Now retrieving all datalist values on first load as this saves about 9 queries per page] + // [Marcus Povey 20090217 : Now retrieving all datalist values on first + // load as this saves about 9 queries per page] + // This also causes OOM problems when the datalists table is large + // @todo make a list of datalists that we want to get in one grab $result = get_data("SELECT * from {$CONFIG->dbprefix}datalists"); if ($result) { foreach ($result as $row) { @@ -1514,8 +1636,9 @@ function datalist_get($name) { /** * Set the value for a datalist element. * - * @param string $name The name of the datalist + * @param string $name The name of the datalist * @param string $value The new value + * * @return true */ function datalist_set($name, $value) { @@ -1534,7 +1657,9 @@ function datalist_set($name, $value) { $datalist_memcache->delete($name); } - insert_data("INSERT into {$CONFIG->dbprefix}datalists set name = '{$name}', value = '{$value}' ON DUPLICATE KEY UPDATE value='{$value}'"); + insert_data("INSERT into {$CONFIG->dbprefix}datalists" + . " set name = '{$name}', value = '{$value}'" + . " ON DUPLICATE KEY UPDATE value='{$value}'"); $DATALIST_CACHE[$name] = $value; @@ -1558,8 +1683,10 @@ function datalist_set($name, $value) { * * @internal A datalist entry $functioname is created with the value of time(). * - * @param string $functionname The name of the function you want to run. - * @param int $timelastupdatedcheck A UNIX timestamp. If time() is > than this, this function will be run again. + * @param string $functionname The name of the function you want to run. + * @param int $timelastupdatedcheck A UNIX timestamp. If time() is > than this, + * this function will be run again. + * * @return bool */ function run_function_once($functionname, $timelastupdatedcheck = 0) { @@ -1592,8 +1719,10 @@ function run_function_once($functionname, $timelastupdatedcheck = 0) { * This assumes we are releasing in order and deprecating according to policy. * * @see CODING.txt - * @param str $msg Message to log / display. - * @param str $version human-readable *release* version: 1.7, 1.7.3 + * + * @param str $msg Message to log / display. + * @param str $dep_version Human-readable *release* version: 1.7, 1.7.3 + * * @return bool * @since 1.7.0 */ @@ -1647,8 +1776,9 @@ function elgg_deprecated_notice($msg, $dep_version) { /** * Checks if code is being called from a certain function. * - * To use, call this function with the function name (and optional file location) that it has to be called - * from, it will either return true or false. + * To use, call this function with the function name (and optional + * file location) that it has to be called from, it will either + * return true or false. * * e.g. * @@ -1672,9 +1802,12 @@ function elgg_deprecated_notice($msg, $dep_version) { * my_secure_function(); * } * - * @param mixed $function The function that this function must have in its call stack, - * to test against a method pass an array containing a class and method name. - * @param string $file Optional file that the function must reside in. + * @param mixed $function The function that this function must have in its call stack, + * to test against a method pass an array containing a class and + * method name. + * @param string $file Optional file that the function must reside in. + * + * @return bool * @todo This is neat but is it necessary? */ function call_gatekeeper($function, $file = "") { @@ -1716,7 +1849,7 @@ function call_gatekeeper($function, $file = "") { $mirror = new ReflectionFunction($function); } - if ((!$mirror) || (strcmp($file,$mirror->getFileName())!=0)) { + if ((!$mirror) || (strcmp($file, $mirror->getFileName()) != 0)) { return false; } } @@ -1728,12 +1861,22 @@ function call_gatekeeper($function, $file = "") { * This function checks to see if it is being called at somepoint by a function defined somewhere * on a given path (optionally including subdirectories). * - * This function is similar to call_gatekeeper() but returns true if it is being called by a method or function which has been defined on a given path or by a specified file. + * This function is similar to call_gatekeeper() but returns true if it is being called + * by a method or function which has been defined on a given path or by a specified file. + * + * @param string $path The full path and filename that this function must have + * in its call stack If a partial path is given and + * $include_subdirs is true, then the function will return + * true if called by any function in or below the specified path. + * @param bool $include_subdirs Are subdirectories of the path ok, or must you specify an + * absolute path and filename. + * @param bool $strict_mode If true then the calling method or function must be directly + * called by something on $path, if false the whole call stack is + * searched. * - * @param string $path The full path and filename that this function must have in its call stack If a partial path is given and $include_subdirs is true, then the function will return true if called by any function in or below the specified path. - * @param bool $include_subdirs Are subdirectories of the path ok, or must you specify an absolute path and filename. - * @param bool $strict_mode If true then the calling method or function must be directly called by something on $path, if false the whole call stack is searched. * @todo Again, very neat, but is it necessary? + * + * @return void */ function callpath_gatekeeper($path, $include_subdirs = true, $strict_mode = false) { global $CONFIG; @@ -1744,20 +1887,22 @@ function callpath_gatekeeper($path, $include_subdirs = true, $strict_mode = fals $callstack = debug_backtrace(); foreach ($callstack as $call) { - $call['file'] = str_replace("\\","/",$call['file']); + $call['file'] = str_replace("\\", "/", $call['file']); if ($include_subdirs) { if (strpos($call['file'], $path) === 0) { if ($strict_mode) { - $callstack[1]['file'] = str_replace("\\","/",$callstack[1]['file']); - if ($callstack[1] === $call) { return true; } + $callstack[1]['file'] = str_replace("\\", "/", $callstack[1]['file']); + if ($callstack[1] === $call) { + return true; + } } else { return true; } } } else { - if (strcmp($path, $call['file'])==0) { + if (strcmp($path, $call['file']) == 0) { if ($strict_mode) { if ($callstack[1] === $call) { return true; @@ -1773,7 +1918,8 @@ function callpath_gatekeeper($path, $include_subdirs = true, $strict_mode = fals } if (isset($CONFIG->debug)) { - system_message("Gatekeeper'd function called from {$callstack[1]['file']}:{$callstack[1]['line']}\n\nStack trace:\n\n" . print_r($callstack, true)); + system_message("Gatekeeper'd function called from {$callstack[1]['file']}:" + . "{$callstack[1]['line']}\n\nStack trace:\n\n" . print_r($callstack, true)); } return false; @@ -1785,6 +1931,7 @@ function callpath_gatekeeper($path, $include_subdirs = true, $strict_mode = fals * Normalizes the setting to bool. * * @param string $ini_get_arg The INI setting + * * @return true|false Depending on whether it's on or off */ function ini_get_bool($ini_get_arg) { @@ -1801,12 +1948,13 @@ function ini_get_bool($ini_get_arg) { * * Function to be used in array_filter which returns true if $string is not null. * - * @param string $string + * @param string $string The string to test + * * @return bool * @todo This is used once in metadata.php. Use a lambda function instead. */ function is_not_null($string) { - if (($string==='') || ($string===false) || ($string===null)) { + if (($string === '') || ($string === false) || ($string === null)) { return false; } @@ -1820,8 +1968,9 @@ function is_not_null($string) { * Used in elgg_get_entities*() functions to support shortcutting plural * names by singular names. * - * @param array $options The options array. $options['keys'] = 'values'; + * @param array $options The options array. $options['keys'] = 'values'; * @param array $singulars A list of sinular words to pluralize by adding 's'. + * * @return array * @since 1.7.0 */ @@ -1851,25 +2000,28 @@ function elgg_normalise_plural_options_array($options, $singulars) { */ function full_url() { $s = empty($_SERVER["HTTPS"]) ? '' : ($_SERVER["HTTPS"] == "on") ? "s" : ""; - $protocol = substr(strtolower($_SERVER["SERVER_PROTOCOL"]), 0, strpos(strtolower($_SERVER["SERVER_PROTOCOL"]), "/")) . $s; - $port = ($_SERVER["SERVER_PORT"] == "80" || $_SERVER["SERVER_PORT"] == "443") ? "" : (":".$_SERVER["SERVER_PORT"]); + $protocol = substr(strtolower($_SERVER["SERVER_PROTOCOL"]), 0, + strpos(strtolower($_SERVER["SERVER_PROTOCOL"]), "/")) . $s; + + $port = ($_SERVER["SERVER_PORT"] == "80" || $_SERVER["SERVER_PORT"] == "443") ? + "" : (":" . $_SERVER["SERVER_PORT"]); // This is here to prevent XSS in poorly written browsers used by 80% of the population. // {@trac [5813]} $quotes = array('\'', '"'); $encoded = array('%27', '%22'); - return $protocol . "://" . $_SERVER['SERVER_NAME'] . $port . str_replace($quotes, $encoded, $_SERVER['REQUEST_URI']); + return $protocol . "://" . $_SERVER['SERVER_NAME'] . $port . + str_replace($quotes, $encoded, $_SERVER['REQUEST_URI']); } /** * Does nothing. * - * @param $range - * @param $ip * @deprecated 1.7 + * @return 0 */ -function test_ip($range, $ip) { +function test_ip() { elgg_deprecated_notice('test_ip() was removed because of licensing issues.', 1.7); return 0; @@ -1878,12 +2030,10 @@ function test_ip($range, $ip) { /** * Does nothing. * - * @param array $networks - * @param string $ip * @return bool * @deprecated 1.7 */ -function is_ip_in_array(array $networks, $ip) { +function is_ip_in_array() { elgg_deprecated_notice('is_ip_in_array() was removed because of licensing issues.', 1.7); return false; @@ -1894,8 +2044,9 @@ function is_ip_in_array(array $networks, $ip) { * * @note If only partial information is passed, a partial URL will be returned. * - * @param array $parts Associative array of URL components like parse_url() returns - * @param bool $htmlencode HTML Encode the url? + * @param array $parts Associative array of URL components like parse_url() returns + * @param bool $html_encode HTML Encode the url? + * * @return str Full URL * @since 1.7.0 */ @@ -1927,8 +2078,9 @@ function elgg_http_build_url(array $parts, $html_encode = TRUE) { * add tokens to the action. The form view automatically handles * tokens. * - * @param str $link Full action URL - * @param bool $htmlencode html encode the url? + * @param str $url Full action URL + * @param bool $html_encode HTML encode the url? + * * @return str URL with action tokens * @since 1.7.0 * @link http://docs.elgg.org/Tutorials/Actions @@ -1959,10 +2111,15 @@ function elgg_add_action_tokens_to_url($url, $html_encode = TRUE) { /** * Add action tokens to URL. * + * @param string $url URL + * + * @return string + * * @deprecated 1.7 final */ function elgg_validate_action_url($url) { - elgg_deprecated_notice('elgg_validate_action_url had a short life. Use elgg_add_action_tokens_to_url() instead.', '1.7b'); + elgg_deprecated_notice('elgg_validate_action_url() deprecated by elgg_add_action_tokens_to_url().', + '1.7b'); return elgg_add_action_tokens_to_url($url); } @@ -1973,8 +2130,9 @@ function elgg_validate_action_url($url) { * * @note You can send a partial URL string. * - * @param string $url - * @param string $element + * @param string $url Full URL + * @param string $element The element to remove + * * @return string The new URL with the query element removed. * @since 1.7.0 */ @@ -2000,8 +2158,9 @@ function elgg_http_remove_url_query_element($url, $element) { /** * Adds an element or elements to a URL's query string. * - * @param str $url The URL - * @param array $elements key/value pairs to add to the URL + * @param str $url The URL + * @param array $elements Key/value pairs to add to the URL + * * @return str The new URL with the query strings added * @since 1.7.0 */ @@ -2028,7 +2187,10 @@ function elgg_http_add_url_query_elements($url, array $elements) { * Adds a breadcrumb to the breadcrumbs stack. * * @param string $title The title to display - * @param string $link Optional. The link for the title. + * @param string $link Optional. The link for the title. + * + * @return void + * * @link http://docs.elgg.org/Tutorials/UI/Breadcrumbs */ function elgg_push_breadcrumb($title, $link = NULL) { @@ -2075,6 +2237,9 @@ function elgg_get_breadcrumbs() { * Call this from an action when you want all your submitted variables * available if the submission fails validation and is sent back to the form * + * @param string $form_name Name of the sticky form + * + * @return void * @link http://docs.elgg.org/Tutorials/UI/StickyForms */ function elgg_make_sticky_form($form_name) { @@ -2088,7 +2253,7 @@ function elgg_make_sticky_form($form_name) { } $_SESSION['sticky_forms'][$form_name] = array(); - foreach($_REQUEST as $key => $var) { + foreach ($_REQUEST as $key => $var) { // will go through XSS filtering on the get function $_SESSION['sticky_forms'][$form_name][$key] = $var; } @@ -2101,7 +2266,9 @@ function elgg_make_sticky_form($form_name) { * when they sticky values have been used to repopulate the form * after a validation error. * - * @param string $name Form namespace + * @param string $form_name Form namespace + * + * @return void * @link http://docs.elgg.org/Tutorials/UI/StickyForms */ function elgg_clear_sticky_form($form_name) { @@ -2111,7 +2278,8 @@ function elgg_clear_sticky_form($form_name) { /** * Has this form been made sticky? * - * @param string $name Form namespace + * @param string $form_name Form namespace + * * @return boolean * @link http://docs.elgg.org/Tutorials/UI/StickyForms */ @@ -2122,15 +2290,17 @@ function elgg_is_sticky_form($form_name) { /** * Get a specific sticky variable * - * @param string $variable The name of the variable - * @param mixed $default Default value if the variable does not exist in sticky cache + * @param string $form_name The name of the form + * @param string $variable The name of the variable + * @param mixed $default Default value if the variable does not exist in sticky cache * @param boolean $filter_result Filter for bad input if true + * * @return mixed * * @todo should this filter the default value? * @link http://docs.elgg.org/Tutorials/UI/StickyForms */ -function elgg_get_sticky_value($form_name, $variable='', $default = NULL, $filter_result = true) { +function elgg_get_sticky_value($form_name, $variable = '', $default = NULL, $filter_result = true) { if (isset($_SESSION['sticky_forms'][$form_name][$variable])) { $value = $_SESSION['sticky_forms'][$form_name][$variable]; if ($filter_result) { @@ -2145,7 +2315,10 @@ function elgg_get_sticky_value($form_name, $variable='', $default = NULL, $filte /** * Clear a specific sticky variable * - * @param string $variable The name of the variable to clear + * @param string $form_name The name of the form + * @param string $variable The name of the variable to clear + * + * @return void * @link http://docs.elgg.org/Tutorials/UI/StickyForms */ function elgg_clear_sticky_value($form_name, $variable) { @@ -2154,6 +2327,7 @@ function elgg_clear_sticky_value($form_name, $variable) { /** * Returns the current active sticky form. + * * @return mixed Str | FALSE * @link http://docs.elgg.org/Tutorials/UI/StickyForms */ @@ -2172,7 +2346,9 @@ function elgg_get_active_sticky_form() { /** * Sets the active sticky form. * - * @param string $form_name + * @param string $form_name The name of the form + * + * @return void * @link http://docs.elgg.org/Tutorials/UI/StickyForms */ function elgg_set_active_sticky_form($form_name) { @@ -2186,7 +2362,8 @@ function elgg_set_active_sticky_form($form_name) { * * @tip Use this for arithmetic when determining if a file can be uploaded. * - * @param str $setting + * @param str $setting The php.ini setting + * * @return int * @since 1.7.0 * @link http://www.php.net/manual/en/function.ini-get.php @@ -2196,7 +2373,7 @@ function elgg_get_ini_setting_in_bytes($setting) { $val = ini_get($setting); // convert INI setting when shorthand notation is used - $last = strtolower($val[strlen($val)-1]); + $last = strtolower($val[strlen($val) - 1]); switch($last) { case 'g': $val *= 1024; @@ -2216,17 +2393,18 @@ function elgg_get_ini_setting_in_bytes($setting) { * Searches for views under js/ and outputs them with special * headers for caching control. * - * @param $page - * @return unknown_type + * @param array $page The page array + * + * @return void * @elgg_pagehandler js */ function js_page_handler($page) { if (is_array($page) && sizeof($page)) { - $js = str_replace('.js','',$page[0]); + $js = str_replace('.js', '', $page[0]); $return = elgg_view('js/' . $js); header('Content-type: text/javascript'); - header('Expires: ' . date('r',time() + 864000)); + header('Expires: ' . date('r', time() + 864000)); header("Pragma: public"); header("Cache-Control: public"); header("Content-Length: " . strlen($return)); @@ -2241,12 +2419,14 @@ function js_page_handler($page) { * * @tip Register for the shutdown:system event to perform functions at the end of page loads. * - * @warning Using this event to perform long-running functions is not very useful. Servers will hold pages until processing is done - * before sending them out to the browser. + * @warning Using this event to perform long-running functions is not very + * useful. Servers will hold pages until processing is done before sending + * them out to the browser. * + * @return void * @see register_shutdown_hook() */ -function __elgg_shutdown_hook() { +function _elgg_shutdown_hook() { global $START_MICROTIME; trigger_elgg_event('shutdown', 'system'); @@ -2262,10 +2442,11 @@ function __elgg_shutdown_hook() { * Handles core actions for comments and likes, the JS pagehandler, and the shutdown function. * * @elgg_event_handler init system + * @return void */ function elgg_init() { global $CONFIG; - + register_action('comments/add'); register_action('comments/delete'); register_action('likes/add'); @@ -2274,7 +2455,7 @@ function elgg_init() { register_page_handler('js', 'js_page_handler'); // Trigger the shutdown:system event upon PHP shutdown. - register_shutdown_function('__elgg_shutdown_hook'); + register_shutdown_function('_elgg_shutdown_hook'); // Sets a blacklist of words in the current language. // This is a comma separated list in word:blacklist. @@ -2293,6 +2474,7 @@ function elgg_init() { * * @link http://docs.elgg.org/Tutorials/WalledGarden * @elgg_plugin_hook index system + * @return void */ function elgg_walled_garden_index() { $login = elgg_view('account/forms/login_walled_garden'); @@ -2306,7 +2488,13 @@ function elgg_walled_garden_index() { /** * Adds unit tests for the general API. * + * @param string $hook unit_test + * @param string $type system + * @param array $value array of test files + * @param array $params empty + * * @elgg_plugin_hook unit_tests system + * @return void */ function elgg_api_test($hook, $type, $value, $params) { global $CONFIG; @@ -2374,6 +2562,7 @@ function elgg_get_nav_items() { * @since 1.8 * @link http://docs.elgg.org/Tutorials/UI/SiteMenu * @elgg_event_handler init system + * @return void */ function add_custom_menu_items() { if ($custom_items = get_config('menu_items_custom_items')) { @@ -2390,9 +2579,10 @@ function add_custom_menu_items() { * * @tip The order of GET params doesn't matter. * - * @param string $url1 - * @param string $url2 - * @param array $ignore_params - GET params to ignore in the comparison + * @param string $url1 First URL + * @param string $url2 Second URL + * @param array $ignore_params GET params to ignore in the comparison + * * @return BOOL * @since 1.8 */ @@ -2424,7 +2614,8 @@ function elgg_http_url_is_identical($url1, $url2, $ignore_params = array('offset $parts = array('scheme', 'host', 'path'); foreach ($parts as $part) { - if ((isset($url1_info[$part]) && isset($url2_info[$part])) && $url1_info[$part] != $url2_info[$part]) { + if ((isset($url1_info[$part]) && isset($url2_info[$part])) + && $url1_info[$part] != $url2_info[$part]) { return FALSE; } elseif (isset($url1_info[$part]) && !isset($url2_info[$part])) { return FALSE; @@ -2434,7 +2625,8 @@ function elgg_http_url_is_identical($url1, $url2, $ignore_params = array('offset } // quick compare of get params - if (isset($url1_info['query']) && isset($url2_info['query']) && $url1_info['query'] == $url2_info['query']) { + if (isset($url1_info['query']) && isset($url2_info['query']) + && $url1_info['query'] == $url2_info['query']) { return TRUE; } @@ -2489,13 +2681,14 @@ function elgg_http_url_is_identical($url1, $url2, $ignore_params = array('offset * @since 1.8 * @elgg_event_handler init system * @link http://docs.elgg.org/Tutorials/WalledGarden + * @return void */ function elgg_walled_garden() { global $CONFIG; // check for external page view if (isset($CONFIG->site) && $CONFIG->site instanceof ElggSite) { - $CONFIG->site->check_walled_garden(); + $CONFIG->site->checkWalledGarden(); } } @@ -2505,9 +2698,11 @@ function elgg_walled_garden() { * * Shorthand for $value = (isset($array['key'])) ? $array['key'] : 'default'; * - * @param string $key The key to check. - * @param array $array The array to check against. - * @param mixed $default Default value to return if nothing is found. + * @param string $key The key to check. + * @param array $array The array to check against. + * @param mixed $default Default value to return if nothing is found. + * + * @return void * @since 1.8 */ function elgg_get_array_value($key, array $array, $default = NULL) { @@ -2520,18 +2715,23 @@ function elgg_get_array_value($key, array $array, $default = NULL) { * @warning Will re-index numeric indexes. * * @note This operates the same as the built-in sort functions. - * ie, sorts the array and returns a bool for success. + * It sorts the array and returns a bool for success. * * Do this: elgg_sort_3d_array_by_value($my_array); * Not this: $my_array = elgg_sort_3d_array_by_value($my_array); * - * @param array $array Array to sort - * @param string $element Element to sort by - * @param $sort_order - * @param $sort_type + * @param array &$array Array to sort + * @param string $element Element to sort by + * @param int $sort_order PHP sort order + * {@see http://us2.php.net/array_multisort} + * @param int $sort_type PHP sort type + * {@see http://us2.php.net/sort} + * * @return bool */ -function elgg_sort_3d_array_by_value(&$array, $element, $sort_order = SORT_ASC, $sort_type = SORT_LOCALE_STRING) { +function elgg_sort_3d_array_by_value(&$array, $element, $sort_order = SORT_ASC, +$sort_type = SORT_LOCALE_STRING) { + $sort = array(); foreach ($array as $k => $v) { diff --git a/engine/lib/entities.php b/engine/lib/entities.php index e788018e0..50e41ab2c 100644 --- a/engine/lib/entities.php +++ b/engine/lib/entities.php @@ -25,6 +25,8 @@ $SUBTYPE_CACHE = NULL; /** * Initialise the entity cache. + * + * @return void * @todo remove this. * @access private */ @@ -40,6 +42,8 @@ function initialise_entity_cache() { * Invalidate this class's entry in the cache. * * @param int $guid The entity guid + * + * @return void * @access private */ function invalidate_cache_for_entity($guid) { @@ -56,6 +60,8 @@ function invalidate_cache_for_entity($guid) { * Stores an entity in $ENTITY_CACHE; * * @param ElggEntity $entity Entity to cache + * + * @return void * @see retrieve_cached_entity() * @see invalidate_cache_for_entity() * @access private @@ -70,6 +76,8 @@ function cache_entity(ElggEntity $entity) { * Retrieve a entity from the cache. * * @param int $guid The guid + * + * @return void * @see cache_entity() * @see invalidate_cache_for_entity() * @access private @@ -89,10 +97,12 @@ function retrieve_cached_entity($guid) { } /** - * As retrieve_cached_entity, but returns the result as a stdClass (compatible with load functions that - * expect a database row.) + * As retrieve_cached_entity, but returns the result as a stdClass + * (compatible with load functions that expect a database row.) * * @param int $guid The guid + * + * @return mixed * @todo unused * @access private */ @@ -129,8 +139,9 @@ function retrieve_cached_entity_row($guid) { * * @todo Move to a nicer place? * - * @param string $type - * @param string $subtype + * @param string $type Type + * @param string $subtype Subtype + * * @return int Subtype ID * @link http://docs.elgg.org/DataModel/Entities/Subtypes * @see get_subtype_from_id() @@ -142,7 +153,7 @@ function get_subtype_id($type, $subtype) { $type = sanitise_string($type); $subtype = sanitise_string($subtype); - if ($subtype=="") { + if ($subtype == "") { return FALSE; } @@ -167,7 +178,8 @@ function get_subtype_id($type, $subtype) { * * @todo Move to a nicer place? * - * @param int $subtype_id + * @param int $subtype_id Subtype ID + * * @return string Subtype name * @link http://docs.elgg.org/DataModel/Entities/Subtypes * @see get_subtype_from_id() @@ -206,8 +218,9 @@ function get_subtype_from_id($subtype_id) { * with {@link register_entity_subtype()}. This function returns * the class name if found, and NULL if not. * - * @param string $type The type + * @param string $type The type * @param string $subtype The subtype + * * @return string|null a class name or null * @see get_subtype_from_id() * @see get_subtype_class_from_id() @@ -239,6 +252,7 @@ function get_subtype_class($type, $subtype) { * Returns the classname for a subtype id. * * @param int $subtype_id The subtype id + * * @return string|null * @see get_subtype_class() * @see get_subtype_from_id() @@ -278,9 +292,11 @@ function get_subtype_class_from_id($subtype_id) { * it will be loaded as that class automatically when retrieved from the database with * {@link get_entity()}. * - * @param string $type The type you're subtyping (site, user, object, or group) + * @param string $type The type you're subtyping (site, user, object, or group) * @param string $subtype The subtype - * @param string $class Optional class name for the object + * @param string $class Optional class name for the object + * + * @return int * @link http://docs.elgg.org/Tutorials/Subclasses * @link http://docs.elgg.org/DataModel/Entities * @see update_subtype() @@ -300,8 +316,9 @@ function add_subtype($type, $subtype, $class = "") { $id = get_subtype_id($type, $subtype); - if ($id==0) { - return insert_data("insert into {$CONFIG->dbprefix}entity_subtypes (type, subtype, class) values ('$type','$subtype','$class')"); + if ($id == 0) { + return insert_data("insert into {$CONFIG->dbprefix}entity_subtypes" + . " (type, subtype, class) values ('$type','$subtype','$class')"); } return $id; @@ -310,8 +327,10 @@ function add_subtype($type, $subtype, $class = "") { /** * Removes a registered ElggEntity type, subtype, and classname. * - * @param string $type - * @param string $subtype + * @param string $type Type + * @param string $subtype Subtype + * + * @return bool * @see add_subtype() * @see update_subtype() */ @@ -321,15 +340,18 @@ function remove_subtype($type, $subtype) { $type = sanitise_string($type); $subtype = sanitise_string($subtype); - return delete_data("DELETE FROM {$CONFIG->dbprefix}entity_subtypes WHERE type = '$type' AND subtype = '$subtype'"); + return delete_data("DELETE FROM {$CONFIG->dbprefix}entity_subtypes" + . " WHERE type = '$type' AND subtype = '$subtype'"); } /** * Update a registered ElggEntity type, subtype, and classname * - * @param string $type - * @param string $subtype - * @param string $class + * @param string $type Type + * @param string $subtype Subtype + * @param string $class Class name to use when loading this entity + * + * @return bool */ function update_subtype($type, $subtype, $class = '') { global $CONFIG; @@ -354,10 +376,11 @@ function update_subtype($type, $subtype, $class = '') { * * @warning Plugin authors should never call this directly. Use ->save() instead. * - * @param int $guid - * @param int $owner_guid - * @param int $access_id - * @param int $container_guid + * @param int $guid The guid of the entity to update + * @param int $owner_guid The new owner guid + * @param int $access_id The new access id + * @param int $container_guid The new container guid + * * @return bool * @link http://docs.elgg.org/DataModel/Entities * @access private @@ -378,10 +401,12 @@ function update_entity($guid, $owner_guid, $access_id, $container_guid = null) { if ($entity && $entity->canEdit()) { if (trigger_elgg_event('update', $entity->type, $entity)) { - $ret = update_data("UPDATE {$CONFIG->dbprefix}entities set owner_guid='$owner_guid', access_id='$access_id', container_guid='$container_guid', time_updated='$time' WHERE guid=$guid"); + $ret = update_data("UPDATE {$CONFIG->dbprefix}entities" + . " set owner_guid='$owner_guid', access_id='$access_id'," + . " container_guid='$container_guid', time_updated='$time' WHERE guid=$guid"); if ($entity instanceof ElggObject) { - update_river_access_by_object($guid,$access_id); + update_river_access_by_object($guid, $access_id); } // If memcache is available then delete this entry from the cache @@ -394,7 +419,7 @@ function update_entity($guid, $owner_guid, $access_id, $container_guid = null) { } // Handle cases where there was no error BUT no rows were updated! - if ($ret===false) { + if ($ret === false) { return false; } @@ -412,8 +437,10 @@ function update_entity($guid, $owner_guid, $access_id, $container_guid = null) { * A plugin hook container_permissions_check:$entity_type is emitted to allow granular * access controls in plugins. * - * @param int $user_guid The user guid, or 0 for get_loggedin_userid() - * @param int $container_guid The container, or 0 for the current page owner. + * @param int $user_guid The user guid, or 0 for get_loggedin_userid() + * @param int $container_guid The container, or 0 for the current page owner. + * @param string $entity_type The type of entities. Defauts to 'all' + * * @return bool * @link http://docs.elgg.org/DataModel/Containers */ @@ -428,7 +455,7 @@ function can_write_to_container($user_guid = 0, $container_guid = 0, $entity_typ $container_guid = (int)$container_guid; if (!$container_guid) { - $container_guid = page_owner(); + $container_guid = get_page_owner_guid(); } if (!$container_guid) { @@ -470,17 +497,21 @@ function can_write_to_container($user_guid = 0, $container_guid = 0, $entity_typ * @warning Entities must have an entry in both the entities table and their type table * or they will throw an exception when loaded. * - * @param string $type The type of the entity (site, user, object, group). - * @param string $subtype The subtype of the entity. - * @param int $owner_guid The GUID of the object's owner. - * @param int $access_id The access control group to create the entity with. - * @param int $site_guid The site to add this entity to. Leave as 0 (default) for the current site. + * @param string $type The type of the entity (site, user, object, group). + * @param string $subtype The subtype of the entity. + * @param int $owner_guid The GUID of the object's owner. + * @param int $access_id The access control group to create the entity with. + * @param int $site_guid The site to add this entity to. 0 for current. + * @param int $container_guid The container GUID + * * @return int|false The new entity's GUID, or false on failure * @throws InvalidParameterException * @access private * @link http://docs.elgg.org/DataModel/Entities */ -function create_entity($type, $subtype, $owner_guid, $access_id, $site_guid = 0, $container_guid = 0) { +function create_entity($type, $subtype, $owner_guid, $access_id, $site_guid = 0, +$container_guid = 0) { + global $CONFIG; $type = sanitise_string($type); @@ -505,13 +536,16 @@ function create_entity($type, $subtype, $owner_guid, $access_id, $site_guid = 0, return false; } } - if ($type=="") { + if ($type == "") { throw new InvalidParameterException(elgg_echo('InvalidParameterException:EntityTypeNotSet')); } return insert_data("INSERT into {$CONFIG->dbprefix}entities - (type, subtype, owner_guid, site_guid, container_guid, access_id, time_created, time_updated, last_action) values - ('$type',$subtype, $owner_guid, $site_guid, $container_guid, $access_id, $time, $time, $time)"); + (type, subtype, owner_guid, site_guid, container_guid, + access_id, time_created, time_updated, last_action) + values + ('$type',$subtype, $owner_guid, $site_guid, $container_guid, + $access_id, $time, $time, $time)"); } /** @@ -523,6 +557,7 @@ function create_entity($type, $subtype, $owner_guid, $access_id, $site_guid = 0, * see {@link get_access_sql_suffix()}. * * @param int $guid The GUID of the object to extract + * * @return stdClass|false * @link http://docs.elgg.org/DataModel/Entities * @see entity_row_to_elggstar() @@ -546,7 +581,8 @@ function get_entity_as_row($guid) { * * Handles loading all tables into the correct class. * - * @param stdClass The row of the entry in the entities table. + * @param stdClass $row The row of the entry in the entities table. + * * @return object|false * @link http://docs.elgg.org/DataModel/Entities * @see get_entity_as_row() @@ -579,12 +615,13 @@ function entity_row_to_elggstar($row) { // load class for entity if one is registered $classname = get_subtype_class_from_id($row->subtype); - if ($classname!="") { + if ($classname != "") { if (class_exists($classname)) { $new_entity = new $classname($row); if (!($new_entity instanceof ElggEntity)) { - throw new ClassException(sprintf(elgg_echo('ClassException:ClassnameNotClass'), $classname, 'ElggEntity')); + $msg = sprintf(elgg_echo('ClassException:ClassnameNotClass'), $classname, 'ElggEntity'); + throw new ClassException($msg); } } else { error_log(sprintf(elgg_echo('ClassNotFoundException:MissingClass'), $classname)); @@ -606,7 +643,8 @@ function entity_row_to_elggstar($row) { $new_entity = new ElggSite($row); break; default: - throw new InstallationException(sprintf(elgg_echo('InstallationException:TypeNotSupported'), $row->type)); + $msg = sprintf(elgg_echo('InstallationException:TypeNotSupported'), $row->type); + throw new InstallationException($msg); } } @@ -622,6 +660,7 @@ function entity_row_to_elggstar($row) { * Loads and returns an entity object from a guid. * * @param int $guid The GUID of the entity + * * @return object The correct Elgg or custom object based upon entity type and subtype * @link http://docs.elgg.org/DataModel/Entities */ @@ -665,11 +704,13 @@ function get_entity($guid) { * * @param array $options Array in format: * - * types => NULL|STR entity type (SQL: type IN ('type1', 'type2') Joined with subtypes by AND...see below) + * types => NULL|STR entity type (type IN ('type1', 'type2') + * Joined with subtypes by AND. See below) * * subtypes => NULL|STR entity subtype (SQL: subtype IN ('subtype1', 'subtype2)) * - * type_subtype_pairs => NULL|ARR (array('type' => 'subtype')) (SQL: type = '$type' AND subtype = '$subtype') pairs + * type_subtype_pairs => NULL|ARR (array('type' => 'subtype')) + * (type = '$type' AND subtype = '$subtype') pairs * * owner_guids => NULL|INT entity guid * @@ -735,10 +776,12 @@ function elgg_get_entities(array $options = array()) { $options = array_merge($defaults, $options); - // can't use helper function with type_subtype_pair because it's already an array...just need to merge it + // can't use helper function with type_subtype_pair because + // it's already an array...just need to merge it if (isset($options['type_subtype_pair'])) { if (isset($options['type_subtype_pairs'])) { - $options['type_subtype_pairs'] = array_merge($options['type_subtype_pairs'], $options['type_subtype_pair']); + $options['type_subtype_pairs'] = array_merge($options['type_subtype_pairs'], + $options['type_subtype_pair']); } else { $options['type_subtype_pairs'] = $options['type_subtype_pair']; } @@ -754,7 +797,8 @@ function elgg_get_entities(array $options = array()) { $wheres = $options['wheres']; - $wheres[] = elgg_get_entity_type_subtype_where_sql('e', $options['types'], $options['subtypes'], $options['type_subtype_pairs']); + $wheres[] = elgg_get_entity_type_subtype_where_sql('e', $options['types'], + $options['subtypes'], $options['type_subtype_pairs']); $wheres[] = elgg_get_entity_site_where_sql('e', $options['site_guids']); $wheres[] = elgg_get_entity_owner_where_sql('e', $options['owner_guids']); $wheres[] = elgg_get_entity_container_where_sql('e', $options['container_guids']); @@ -846,22 +890,28 @@ function elgg_get_entities(array $options = array()) { } /** + * Returns entities. + * * @deprecated 1.7. Use elgg_get_entities(). - * @param $type - * @param $subtype - * @param $owner_guid - * @param $order_by - * @param $limit - * @param $offset - * @param $count - * @param $site_guid - * @param $container_guid - * @param $timelower - * @param $timeupper - * @return unknown_type - */ -function get_entities($type = "", $subtype = "", $owner_guid = 0, $order_by = "", $limit = 10, $offset = 0, -$count = false, $site_guid = 0, $container_guid = null, $timelower = 0, $timeupper = 0) { + * + * @param string $type Entity type + * @param string $subtype Entity subtype + * @param int $owner_guid Owner GUID + * @param string $order_by Order by clause + * @param int $limit Limit + * @param int $offset Offset + * @param bool $count Return a count or an array of entities + * @param int $site_guid Site GUID + * @param int $container_guid Container GUID + * @param int $timelower Lower time limit + * @param int $timeupper Upper time limit + * + * @return array + */ +function get_entities($type = "", $subtype = "", $owner_guid = 0, $order_by = "", $limit = 10, +$offset = 0, $count = false, $site_guid = 0, $container_guid = null, $timelower = 0, +$timeupper = 0) { + elgg_deprecated_notice('get_entities() was deprecated by elgg_get_entities().', 1.7); // rewrite owner_guid to container_guid to emulate old functionality @@ -935,10 +985,11 @@ $count = false, $site_guid = 0, $container_guid = null, $timelower = 0, $timeupp /** * Returns SQL where clause for type and subtype on main entity table * - * @param string $table entity table prefix as defined in SELECT ... FROM prefix_entities $table - * @param NULL|$types - * @param NULL|array $subtypes - * @param NULL|array $pairs + * @param string $table Entity table prefix as defined in SELECT...FROM entities $table + * @param NULL|array $types Array of types or NULL if none. + * @param NULL|array $subtypes Array of subtypes or NULL if none + * @param NULL|array $pairs Array of pairs of types and subtypes + * * @return FALSE|string * @since 1.7.0 * @access private @@ -1052,8 +1103,11 @@ function elgg_get_entity_type_subtype_where_sql($table, $types, $subtypes, $pair if (is_array($paired_subtypes)) { $paired_subtype_ids = array(); foreach ($paired_subtypes as $paired_subtype) { - if (ELGG_ENTITIES_NO_VALUE === $paired_subtype || ($paired_subtype_id = get_subtype_id($paired_type, $paired_subtype))) { - $paired_subtype_ids[] = (ELGG_ENTITIES_NO_VALUE === $paired_subtype) ? ELGG_ENTITIES_NO_VALUE : $paired_subtype_id; + if (ELGG_ENTITIES_NO_VALUE === $paired_subtype + || ($paired_subtype_id = get_subtype_id($paired_type, $paired_subtype))) { + + $paired_subtype_ids[] = (ELGG_ENTITIES_NO_VALUE === $paired_subtype) ? + ELGG_ENTITIES_NO_VALUE : $paired_subtype_id; } else { $valid_pairs_subtypes_count--; elgg_log("Type-subtype $paired_type:$paired_subtype' does not exist!", 'WARNING'); @@ -1069,7 +1123,8 @@ function elgg_get_entity_type_subtype_where_sql($table, $types, $subtypes, $pair if ($paired_subtype_ids_str = implode(',', $paired_subtype_ids)) { - $wheres[] = "({$table}.type = '$paired_type' AND {$table}.subtype IN ($paired_subtype_ids_str))"; + $wheres[] = "({$table}.type = '$paired_type'" + . " AND {$table}.subtype IN ($paired_subtype_ids_str))"; } } else { $wheres[] = "({$table}.type = '$paired_type')"; @@ -1090,8 +1145,10 @@ function elgg_get_entity_type_subtype_where_sql($table, $types, $subtypes, $pair * Returns SQL where clause for owner and containers. * * @todo Probably DRY up once things are settled. - * @param string $table entity table prefix as defined in SELECT ... FROM prefix_entities $table - * @param NULL|array $owner_guids + * + * @param string $table Entity table prefix as defined in SELECT...FROM entities $table + * @param NULL|array $owner_guids Owner GUIDs + * * @return FALSE|str * @since 1.7.0 * @access private @@ -1119,7 +1176,9 @@ function elgg_get_entity_owner_where_sql($table, $owner_guids) { $where = ''; // implode(',', 0) returns 0. - if (($owner_str = implode(',', $owner_guids_sanitised)) && ($owner_str !== FALSE) && ($owner_str !== '')) { + if (($owner_str = implode(',', $owner_guids_sanitised)) + && ($owner_str !== FALSE) && ($owner_str !== '')) { + $where = "({$table}.owner_guid IN ($owner_str))"; } @@ -1129,8 +1188,10 @@ function elgg_get_entity_owner_where_sql($table, $owner_guids) { /** * Returns SQL where clause for containers. * - * @param string $table entity table prefix as defined in SELECT ... FROM prefix_entities $table - * @param NULL|array $container_guids + * @param string $table Entity table prefix as defined in + * SELECT...FROM entities $table + * @param NULL|array $container_guids Array of container guids + * * @return FALSE|string * @since 1.7.0 * @access private @@ -1168,17 +1229,19 @@ function elgg_get_entity_container_where_sql($table, $container_guids) { /** * Returns SQL where clause for entity time limits. * - * @param string $table entity table prefix as defined in SELECT ... FROM prefix_entities $table - * @param NULL|int $time_created_upper - * @param NULL|int $time_created_lower - * @param NULL|int $time_updated_upper - * @param NULL|int $time_updated_lower + * @param string $table Entity table prefix as defined in + * SELECT...FROM entities $table + * @param NULL|int $time_created_upper Time crated upper limit + * @param NULL|int $time_created_lower Time created lower limit + * @param NULL|int $time_updated_upper Time updated upper limit + * @param NULL|int $time_updated_lower Time updated lower limit + * * @return FALSE|str FALSE on fail, string on success. * @since 1.7.0 * @access private */ -function elgg_get_entity_time_where_sql($table, $time_created_upper = NULL, $time_created_lower = NULL, - $time_updated_upper = NULL, $time_updated_lower = NULL) { +function elgg_get_entity_time_where_sql($table, $time_created_upper = NULL, +$time_created_lower = NULL, $time_updated_upper = NULL, $time_updated_lower = NULL) { $wheres = array(); @@ -1210,8 +1273,9 @@ function elgg_get_entity_time_where_sql($table, $time_created_upper = NULL, $tim /** * Returns SQL where clause for site entities * - * @param string $table entity table prefix as defined in SELECT ... FROM prefix_entities $table - * @param NULL|array $site_guids + * @param string $table Entity table prefix as defined in SELECT...FROM entities $table + * @param NULL|array $site_guids Array of site guids + * * @return FALSE|string * @since 1.7.0 * @access private @@ -1281,17 +1345,23 @@ function elgg_list_entities($options) { } /** + * Lists entities + * * @deprecated 1.7. Use elgg_list_entities(). - * @param $type - * @param $subtype - * @param $owner_guid - * @param $limit - * @param $fullview - * @param $viewtypetoggle - * @param $pagination - * @return unknown_type - */ -function list_entities($type= "", $subtype = "", $owner_guid = 0, $limit = 10, $fullview = true, $viewtypetoggle = false, $pagination = true) { + * + * @param string $type Entity type + * @param string $subtype Entity subtype + * @param int $owner_guid Owner GUID + * @param int $limit Limit + * @param bool $fullview Display entity full views? + * @param bool $viewtypetoggle Allow switching to gallery mode? + * @param bool $pagination Show pagination? + * + * @return string + */ +function list_entities($type= "", $subtype = "", $owner_guid = 0, $limit = 10, $fullview = true, +$viewtypetoggle = false, $pagination = true) { + elgg_deprecated_notice('list_entities() was deprecated by elgg_list_entities()!', 1.7); $options = array(); @@ -1327,26 +1397,33 @@ function list_entities($type= "", $subtype = "", $owner_guid = 0, $limit = 10, $ /** * Lists entities that belong to a group. * - * @warning This function is largely redundant. The preferred - * method of listing group entities is by setting the container - * guid option in {@link elgg_list_entities()}. - * - * @param string $subtype The arbitrary subtype of the entity - * @param int $owner_guid The GUID of the owning user - * @param int $container_guid The GUID of the containing group - * @param int $limit The number of entities to display per page (default: 10) - * @param true|false $fullview Whether or not to display the full view (default: true) - * @param true|false $viewtypetoggle Whether or not to allow gallery view (default: true) - * @param true|false $pagination Whether to display pagination (default: true) + * @warning This function is redundant and will be deprecated in 1.8. + * The preferred method of listing group entities is by setting the + * container guid option in {@link elgg_list_entities()}. + * + * @param string $subtype The arbitrary subtype of the entity + * @param int $owner_guid The GUID of the owning user + * @param int $container_guid The GUID of the containing group + * @param int $limit The number of entities to display per page (default: 10) + * @param bool $fullview Whether or not to display the full view (default: true) + * @param bool $viewtypetoggle Whether or not to allow gallery view (default: true) + * @param bool $pagination Whether to display pagination (default: true) + * * @return string List of parsed entities + * * @see elgg_list_entities() */ -function list_entities_groups($subtype = "", $owner_guid = 0, $container_guid = 0, $limit = 10, $fullview = true, $viewtypetoggle = true, $pagination = true) { +function list_entities_groups($subtype = "", $owner_guid = 0, $container_guid = 0, +$limit = 10, $fullview = true, $viewtypetoggle = true, $pagination = true) { + $offset = (int) get_input('offset'); - $count = get_objects_in_group($container_guid, $subtype, $owner_guid, 0, "", $limit, $offset, true); - $entities = get_objects_in_group($container_guid, $subtype, $owner_guid, 0, "", $limit, $offset); + $count = get_objects_in_group($container_guid, $subtype, $owner_guid, + 0, "", $limit, $offset, true); + $entities = get_objects_in_group($container_guid, $subtype, $owner_guid, + 0, "", $limit, $offset); - return elgg_view_entity_list($entities, $count, $offset, $limit, $fullview, $viewtypetoggle, $pagination); + return elgg_view_entity_list($entities, $count, $offset, $limit, + $fullview, $viewtypetoggle, $pagination); } /** @@ -1356,14 +1433,17 @@ function list_entities_groups($subtype = "", $owner_guid = 0, $container_guid = * * @warning Months are returned in the form YYYYMM. * - * @param string $type The type of entity - * @param string $subtype The subtype of entity - * @param int $container_guid The container GUID that the entinties belong to - * @param int $site_guid The site GUID - * @param str order_by SQL order by clause + * @param string $type The type of entity + * @param string $subtype The subtype of entity + * @param int $container_guid The container GUID that the entinties belong to + * @param int $site_guid The site GUID + * @param str $order_by Order_by SQL order by clause + * * @return array|false Either an array months as YYYYMM, or false on failure */ -function get_entity_dates($type = '', $subtype = '', $container_guid = 0, $site_guid = 0, $order_by = 'time_created') { +function get_entity_dates($type = '', $subtype = '', $container_guid = 0, $site_guid = 0, +$order_by = 'time_created') { + global $CONFIG; $site_guid = (int) $site_guid; @@ -1380,16 +1460,19 @@ function get_entity_dates($type = '', $subtype = '', $container_guid = 0, $site_ if (is_array($subtype)) { $tempwhere = ""; if (sizeof($subtype)) { - foreach($subtype as $typekey => $subtypearray) { - foreach($subtypearray as $subtypeval) { + foreach ($subtype as $typekey => $subtypearray) { + foreach ($subtypearray as $subtypeval) { $typekey = sanitise_string($typekey); if (!empty($subtypeval)) { - if (!$subtypeval = (int) get_subtype_id($typekey, $subtypeval)) + if (!$subtypeval = (int) get_subtype_id($typekey, $subtypeval)) { return false; + } } else { $subtypeval = 0; } - if (!empty($tempwhere)) $tempwhere .= " or "; + if (!empty($tempwhere)) { + $tempwhere .= " or "; + } $tempwhere .= "(type = '{$typekey}' and subtype = {$subtypeval})"; } } @@ -1409,10 +1492,10 @@ function get_entity_dates($type = '', $subtype = '', $container_guid = 0, $site_ if ($container_guid !== 0) { if (is_array($container_guid)) { - foreach($container_guid as $key => $val) { + foreach ($container_guid as $key => $val) { $container_guid[$key] = (int) $val; } - $where[] = "container_guid in (" . implode(",",$container_guid) . ")"; + $where[] = "container_guid in (" . implode(",", $container_guid) . ")"; } else { $container_guid = (int) $container_guid; $where[] = "container_guid = {$container_guid}"; @@ -1435,7 +1518,7 @@ function get_entity_dates($type = '', $subtype = '', $container_guid = 0, $site_ $sql .= "1=1 ORDER BY $order_by"; if ($result = get_data($sql)) { $endresult = array(); - foreach($result as $res) { + foreach ($result as $res) { $endresult[] = $res->yearmonth; } return $endresult; @@ -1456,9 +1539,10 @@ function get_entity_dates($type = '', $subtype = '', $container_guid = 0, $site_ * * @note Use ElggEntity::disable() instead. * - * @param int $guid The guid - * @param string $reason Optional reason - * @param bool $recursive Recursively disable all entities owned or contained by $guid? + * @param int $guid The guid + * @param string $reason Optional reason + * @param bool $recursive Recursively disable all entities owned or contained by $guid? + * * @return bool * @access private * @see access_show_hidden_entities() @@ -1471,7 +1555,7 @@ function disable_entity($guid, $reason = "", $recursive = true) { $reason = sanitise_string($reason); if ($entity = get_entity($guid)) { - if (trigger_elgg_event('disable',$entity->type,$entity)) { + if (trigger_elgg_event('disable', $entity->type, $entity)) { if ($entity->canEdit()) { if ($reason) { create_metadata($guid, 'disable_reason', $reason, '', 0, ACCESS_PUBLIC); @@ -1515,7 +1599,8 @@ function disable_entity($guid, $reason = "", $recursive = true) { * @warning In order to enable an entity using ElggEntity::enable(), * you must first use {@link access_show_hidden_entities()}. * - * @param int $guid + * @param int $guid GUID of entity to enable + * * @return bool */ function enable_entity($guid) { @@ -1528,7 +1613,7 @@ function enable_entity($guid) { access_show_hidden_entities(true); if ($entity = get_entity($guid)) { - if (trigger_elgg_event('enable',$entity->type,$entity)) { + if (trigger_elgg_event('enable', $entity->type, $entity)) { if ($entity->canEdit()) { access_show_hidden_entities($access_status); @@ -1561,9 +1646,12 @@ function enable_entity($guid) { * the entity. That means that if the container_guid = $guid, the item will be deleted * regardless of who owns it. * - * @param int $guid - * @param bool $recursive If true (default) then all entities which are owned or contained by $guid will also be deleted. + * @param int $guid The guid of the entity to delete + * @param bool $recursive If true (default) then all entities which are + * owned or contained by $guid will also be deleted. + * * @access private + * @return bool */ function delete_entity($guid, $recursive = true) { global $CONFIG, $ENTITY_CACHE; @@ -1641,13 +1729,17 @@ function delete_entity($guid, $recursive = true) { /** * Delete multiple entities that match a given query. - * This function iterates through and calls delete_entity on each one, this is somewhat inefficient but lets - * the 'delete' even be called for each entity. + * This function iterates through and calls delete_entity on + * each one, this is somewhat inefficient but lets + * the 'delete' event be called for each entity. * * @deprecated 1.7. This is a dangerous function as it defaults to deleting everything. - * @param string $type The type of entity (eg "user", "object" etc) - * @param string $subtype The arbitrary subtype of the entity - * @param int $owner_guid The GUID of the owning user + * + * @param string $type The type of entity (eg "user", "object" etc) + * @param string $subtype The arbitrary subtype of the entity + * @param int $owner_guid The GUID of the owning user + * + * @return false */ function delete_entities($type = "", $subtype = "", $owner_guid = 0) { elgg_deprecated_notice('delete_entities() was deprecated because no one should use it.', 1.7); @@ -1657,10 +1749,11 @@ function delete_entities($type = "", $subtype = "", $owner_guid = 0) { /** * Exports attributes generated on the fly (volatile) about an entity. * - * @param unknown_type $hook - * @param unknown_type $entity_type - * @param unknown_type $returnvalue - * @param unknown_type $params The parameters, passed 'guid' and 'varname' + * @param string $hook volatile + * @param string $entity_type metadata + * @param string $returnvalue Return value from previous hook + * @param array $params The parameters, passed 'guid' and 'varname' + * * @return null * @elgg_plugin_hook_handler volatile metadata * @todo investigate more. @@ -1698,8 +1791,13 @@ function volatile_data_export_plugin_hook($hook, $entity_type, $returnvalue, $pa * * @warning Only exports fields in the entity and entity type tables. * + * @param string $hook export + * @param string $entity_type all + * @param mixed $returnvalue Previous hook return value + * @param array $params Parameters + * * @elgg_event_handler export all - * @todo document + * @return mixed */ function export_entity_plugin_hook($hook, $entity_type, $returnvalue, $params) { // Sanity check values @@ -1716,7 +1814,8 @@ function export_entity_plugin_hook($hook, $entity_type, $returnvalue, $params) { // Get the entity $entity = get_entity($guid); if (!($entity instanceof ElggEntity)) { - throw new InvalidClassException(sprintf(elgg_echo('InvalidClassException:NotValidElggStar'), $guid, get_class())); + $msg = sprintf(elgg_echo('InvalidClassException:NotValidElggStar'), $guid, get_class()); + throw new InvalidClassException($msg); } $export = $entity->export(); @@ -1733,9 +1832,11 @@ function export_entity_plugin_hook($hook, $entity_type, $returnvalue, $params) { } /** - * Utility function used by import_entity_plugin_hook() to process an ODDEntity into an unsaved ElggEntity. + * Utility function used by import_entity_plugin_hook() to + * process an ODDEntity into an unsaved ElggEntity. * * @param ODDEntity $element The OpenDD element + * * @return ElggEntity the unsaved entity which should be populated by items. * @todo Remove this. */ @@ -1749,18 +1850,18 @@ function oddentity_to_elggentity(ODDEntity $element) { if (!$tmp) { // Construct new class with owner from session $classname = get_subtype_class($class, $subclass); - if ($classname!="") { + if ($classname != "") { if (class_exists($classname)) { $tmp = new $classname(); if (!($tmp instanceof ElggEntity)) { - throw new ClassException(sprintf(elgg_echo('ClassException:ClassnameNotClass', $classname, get_class()))); + $msg = sprintf(elgg_echo('ClassException:ClassnameNotClass', $classname, get_class())); + throw new ClassException($msg); } - } - else + } else { error_log(sprintf(elgg_echo('ClassNotFoundException:MissingClass'), $classname)); - } - else { + } + } else { switch ($class) { case 'object' : $tmp = new ElggObject($row); @@ -1775,14 +1876,16 @@ function oddentity_to_elggentity(ODDEntity $element) { $tmp = new ElggSite($row); break; default: - throw new InstallationException(sprintf(elgg_echo('InstallationException:TypeNotSupported'), $class)); + $msg = sprintf(elgg_echo('InstallationException:TypeNotSupported'), $class); + throw new InstallationException($msg); } } } if ($tmp) { if (!$tmp->import($element)) { - throw new ImportException(sprintf(elgg_echo('ImportException:ImportFailed'), $element->getAttribute('uuid'))); + $msg = sprintf(elgg_echo('ImportException:ImportFailed'), $element->getAttribute('uuid')); + throw new ImportException($msg); } return $tmp; @@ -1794,11 +1897,19 @@ function oddentity_to_elggentity(ODDEntity $element) { /** * Import an entity. * - * This function checks the passed XML doc (as array) to see if it is a user, if so it constructs a new - * elgg user and returns "true" to inform the importer that it's been handled. + * This function checks the passed XML doc (as array) to see if it is + * a user, if so it constructs a new elgg user and returns "true" + * to inform the importer that it's been handled. + * + * @param string $hook import + * @param string $entity_type all + * @param mixed $returnvalue Value from previous hook + * @param mixed $params Array of params * + * @return mixed * @elgg_plugin_hook_handler import all * @todo document + * */ function import_entity_plugin_hook($hook, $entity_type, $returnvalue, $params) { $element = $params['element']; @@ -1811,7 +1922,8 @@ function import_entity_plugin_hook($hook, $entity_type, $returnvalue, $params) { if ($tmp) { // Make sure its saved if (!$tmp->save()) { - throw new ImportException(sprintf(elgg_echo('ImportException:ProblemSaving'), $element->getAttribute('uuid'))); + sprintf(elgg_echo('ImportException:ProblemSaving'), $element->getAttribute('uuid')); + throw new ImportException($msg); } // Belts and braces @@ -1838,7 +1950,8 @@ function import_entity_plugin_hook($hook, $entity_type, $returnvalue, $params) { * @tip Use ElggEntity::canEdit() instead. * * @param int $entity_guid The GUID of the entity - * @param int $user_guid The GUID of the user + * @param int $user_guid The GUID of the user + * * @return bool * @link http://docs.elgg.org/Entities/AccessControl */ @@ -1888,9 +2001,10 @@ function can_edit_entity($entity_guid, $user_guid = 0) { * * @warning If a $user_guid isn't specified, the currently logged in user is used. * - * @param int $entity_guid The GUID of the entity - * @param int $user_guid The GUID of the user - * @param ElggMetadata $metadata The metadata to specifically check (if any; default null) + * @param int $entity_guid The GUID of the entity + * @param int $user_guid The GUID of the user + * @param ElggMetadata $metadata The metadata to specifically check (if any; default null) + * * @return bool * @see register_plugin_hook() */ @@ -1907,7 +2021,8 @@ function can_edit_entity_metadata($entity_guid, $user_guid = 0, $metadata = null } $user = get_entity($user_guid); - $return = trigger_plugin_hook('permissions_check:metadata',$entity->type,array('entity' => $entity, 'user' => $user, 'metadata' => $metadata),$return); + $params = array('entity' => $entity, 'user' => $user, 'metadata' => $metadata); + $return = trigger_plugin_hook('permissions_check:metadata', $entity->type, $parms, $return); return $return; } else { return false; @@ -1922,7 +2037,8 @@ function can_edit_entity_metadata($entity_guid, $user_guid = 0, $metadata = null * @internal This is passed an entity rather than a guid to handle non-created entities. * * @param ElggEntity $entity The entity - * @param string $size + * @param string $size Icon size + * * @return string URL to the entity icon. */ function get_entity_icon_url(ElggEntity $entity, $size = 'medium') { @@ -1960,7 +2076,8 @@ function get_entity_icon_url(ElggEntity $entity, $size = 'medium') { $viewtype = elgg_get_viewtype(); // Step one, see if anyone knows how to render this in the current view - $url = trigger_plugin_hook('entity:icon:url', $entity->getType(), array('entity' => $entity, 'viewtype' => $viewtype, 'size' => $size), $url); + $params = array('entity' => $entity, 'viewtype' => $viewtype, 'size' => $size); + $url = trigger_plugin_hook('entity:icon:url', $entity->getType(), $params, $url); // Fail, so use default if (!$url) { @@ -1968,13 +2085,13 @@ function get_entity_icon_url(ElggEntity $entity, $size = 'medium') { $subtype = $entity->getSubtype(); if (!empty($subtype)) { - $overrideurl = elgg_view("icon/{$type}/{$subtype}/{$size}",array('entity' => $entity)); + $overrideurl = elgg_view("icon/{$type}/{$subtype}/{$size}", array('entity' => $entity)); if (!empty($overrideurl)) { return $overrideurl; } } - $overrideurl = elgg_view("icon/{$type}/default/{$size}",array('entity' => $entity)); + $overrideurl = elgg_view("icon/{$type}/default/{$size}", array('entity' => $entity)); if (!empty($overrideurl)) { return $overrideurl; } @@ -1991,6 +2108,7 @@ function get_entity_icon_url(ElggEntity $entity, $size = 'medium') { * @tip Can be overridden with {@link register_entity_url_handler()}. * * @param int $entity_guid The GUID of the entity + * * @return string The URL of the entity * @see register_entity_url_handler() */ @@ -2001,17 +2119,17 @@ function get_entity_url($entity_guid) { $url = ""; if (isset($CONFIG->entity_url_handler[$entity->getType()][$entity->getSubType()])) { - $function = $CONFIG->entity_url_handler[$entity->getType()][$entity->getSubType()]; + $function = $CONFIG->entity_url_handler[$entity->getType()][$entity->getSubType()]; if (is_callable($function)) { $url = $function($entity); } } elseif (isset($CONFIG->entity_url_handler[$entity->getType()]['all'])) { - $function = $CONFIG->entity_url_handler[$entity->getType()]['all']; + $function = $CONFIG->entity_url_handler[$entity->getType()]['all']; if (is_callable($function)) { $url = $function($entity); } } elseif (isset($CONFIG->entity_url_handler['all']['all'])) { - $function = $CONFIG->entity_url_handler['all']['all']; + $function = $CONFIG->entity_url_handler['all']['all']; if (is_callable($function)) { $url = $function($entity); } @@ -2030,14 +2148,17 @@ function get_entity_url($entity_guid) { /** * Sets the URL handler for a particular entity type and subtype * - * @param string $function_name The function to register - * @param string $entity_type The entity type + * @param string $function_name The function to register + * @param string $entity_type The entity type * @param string $entity_subtype The entity subtype + * * @return true|false Depending on success * @see get_entity_url() * @see ElggEntity::getURL() */ -function register_entity_url_handler($function_name, $entity_type = "all", $entity_subtype = "all") { +function register_entity_url_handler($function_name, $entity_type = "all", +$entity_subtype = "all") { + global $CONFIG; if (!is_callable($function_name)) { @@ -2063,10 +2184,12 @@ function register_entity_url_handler($function_name, $entity_type = "all", $enti * @tip This will attempt to find a default entity for the current view and return a url. * This is registered at a high priority so that other handlers will pick it up first. * - * @param unknown_type $hook - * @param unknown_type $entity_type - * @param unknown_type $returnvalue - * @param unknown_type $params + * @param string $hook entity:icon:url + * @param string $entity_type all + * @param mixed $returnvalue Previous hook's return value + * @param array $params Array of params + * + * @return string|null String of URL for entity's icon * @elgg_plugin_hook_handler entity:icon:url all */ function default_entity_icon_hook($hook, $entity_type, $returnvalue, $params) { @@ -2085,7 +2208,7 @@ function default_entity_icon_hook($hook, $entity_type, $returnvalue, $params) { $url = "views/$viewtype/graphics/icons/$type/default/$size.png"; } - if(!@file_exists($CONFIG->path . $url)) { + if (!@file_exists($CONFIG->path . $url)) { $url = "views/$viewtype/graphics/icons/default/$size.png"; } @@ -2103,8 +2226,9 @@ function default_entity_icon_hook($hook, $entity_type, $returnvalue, $params) { * * @tip Add a language string item:type:subtype to make sure the items are display properly. * - * @param string $type The type of entity (object, site, user, group) + * @param string $type The type of entity (object, site, user, group) * @param string $subtype The subtype to register (may be blank) + * * @return true|false Depending on success * @see get_registered_entity_types() * @link http://docs.elgg.org/Search @@ -2139,8 +2263,9 @@ function register_entity_type($type, $subtype) { * @warning With a blank subtype, it unregisters that entity type including * all subtypes. This must be called after all subtypes have been registered. * - * @param string $type The type of entity (object, site, user, group) + * @param string $type The type of entity (object, site, user, group) * @param string $subtype The subtype to register (may be blank) + * * @return true|false Depending on success * @see register_entity_type() */ @@ -2178,6 +2303,7 @@ function unregister_entity_type($type, $subtype) { * Returns registered entity types and subtypes * * @param string $type The type of entity (object, site, user, group) or blank for all + * * @return array|false Depending on whether entities have been registered * @see register_entity_type() */ @@ -2204,8 +2330,9 @@ function get_registered_entity_types($type = '') { /** * Returns if the entity type and subtype have been registered with {@see register_entity_type()}. * - * @param string $type The type of entity (object, site, user, group) + * @param string $type The type of entity (object, site, user, group) * @param string $subtype The subtype (may be blank) + * * @return true|false Depending on whether or not the type has been registered */ function is_registered_entity_type($type, $subtype) { @@ -2227,26 +2354,33 @@ function is_registered_entity_type($type, $subtype) { * Page handler for generic entities view system * * @param array $page Page elements from pain page handler + * + * @return void * @elgg_page_handler view */ function entities_page_handler($page) { if (isset($page[0])) { global $CONFIG; - set_input('guid',$page[0]); + set_input('guid', $page[0]); include($CONFIG->path . "pages/entities/index.php"); } } /** + * Lists entities. + * + * @param int $owner_guid Owner GUID + * @param int $limit Limit + * @param bool $fullview Show entity full views + * @param bool $viewtypetoggle Show list type toggle + * @param bool $allowedtypes A string of the allowed types + * + * @return string * @deprecated 1.7. Use elgg_list_registered_entities(). - * @param $owner_guid - * @param $limit - * @param $fullview - * @param $viewtypetoggle - * @param $allowedtypes - * @return unknown_type - */ -function list_registered_entities($owner_guid = 0, $limit = 10, $fullview = true, $viewtypetoggle = false, $allowedtypes = true) { + */ +function list_registered_entities($owner_guid = 0, $limit = 10, $fullview = true, +$viewtypetoggle = false, $allowedtypes = true) { + elgg_deprecated_notice('list_registered_entities() was deprecated by elgg_list_registered_entities().', 1.7); $options = array(); @@ -2304,7 +2438,7 @@ function elgg_list_registered_entities($options) { $typearray = array(); if ($object_types = get_registered_entity_types()) { - foreach($object_types as $object_type => $subtype_array) { + foreach ($object_types as $object_type => $subtype_array) { if (in_array($object_type, $options['allowed_types']) || $options['allowed_types'] === TRUE) { $typearray[$object_type] = array(); @@ -2329,21 +2463,25 @@ function elgg_list_registered_entities($options) { /** * Get entities based on their private data. * - * @param string $name The name of the setting - * @param string $value The value of the setting - * @param string $type The type of entity (eg "user", "object" etc) - * @param string $subtype The arbitrary subtype of the entity - * @param int $owner_guid The GUID of the owning user - * @param string $order_by The field to order by; by default, time_created desc - * @param int $limit The number of entities to return; 10 by default - * @param int $offset The indexing offset, 0 by default - * @param boolean $count Set to true to get a count rather than the entities themselves (limits and offsets don't apply in this context). Defaults to false. - * @param int $site_guid The site to get entities for. Leave as 0 (default) for the current site; -1 for all sites. - * @param int|array $container_guid The container or containers to get entities from (default: all containers). + * @param string $name The name of the setting + * @param string $value The value of the setting + * @param string $type The type of entity (eg "user", "object" etc) + * @param string $subtype The arbitrary subtype of the entity + * @param int $owner_guid The GUID of the owning user + * @param string $order_by The field to order by; by default, time_created desc + * @param int $limit The number of entities to return; 10 by default + * @param int $offset The indexing offset, 0 by default + * @param boolean $count Return a count of entities + * @param int $site_guid The site to get entities for. 0 for current, -1 for any + * @param mixed $container_guid The container(s) GUIDs + * * @return array A list of entities. * @todo deprecate */ -function get_entities_from_private_setting($name = "", $value = "", $type = "", $subtype = "", $owner_guid = 0, $order_by = "", $limit = 10, $offset = 0, $count = false, $site_guid = 0, $container_guid = null) { +function get_entities_from_private_setting($name = "", $value = "", $type = "", $subtype = "", +$owner_guid = 0, $order_by = "", $limit = 10, $offset = 0, $count = false, $site_guid = 0, +$container_guid = null) { + global $CONFIG; if ($subtype === false || $subtype === null || $subtype === 0) { @@ -2369,8 +2507,8 @@ function get_entities_from_private_setting($name = "", $value = "", $type = "", if (is_array($type)) { $tempwhere = ""; if (sizeof($type)) { - foreach($type as $typekey => $subtypearray) { - foreach($subtypearray as $subtypeval) { + foreach ($type as $typekey => $subtypearray) { + foreach ($subtypearray as $subtypeval) { $typekey = sanitise_string($typekey); if (!empty($subtypeval)) { if (!$subtypeval = (int) get_subtype_id($typekey, $subtypeval)) { @@ -2379,7 +2517,9 @@ function get_entities_from_private_setting($name = "", $value = "", $type = "", } else { $subtypeval = 0; } - if (!empty($tempwhere)) $tempwhere .= " or "; + if (!empty($tempwhere)) { + $tempwhere .= " or "; + } $tempwhere .= "(e.type = '{$typekey}' and e.subtype = {$subtypeval})"; } } @@ -2396,7 +2536,7 @@ function get_entities_from_private_setting($name = "", $value = "", $type = "", if ($type != "") { $where[] = "e.type='$type'"; } - if ($subtype!=="") { + if ($subtype !== "") { $where[] = "e.subtype=$subtype"; } } @@ -2405,13 +2545,8 @@ function get_entities_from_private_setting($name = "", $value = "", $type = "", if (!is_array($owner_guid)) { $owner_array = array($owner_guid); $owner_guid = (int) $owner_guid; - // $where[] = "owner_guid = '$owner_guid'"; } else if (sizeof($owner_guid) > 0) { $owner_array = array_map('sanitise_int', $owner_guid); - // Cast every element to the owner_guid array to int - // $owner_guid = array_map("sanitise_int", $owner_guid); - // $owner_guid = implode(",",$owner_guid); - // $where[] = "owner_guid in ({$owner_guid})"; } if (is_null($container_guid)) { $container_guid = $owner_array; @@ -2424,19 +2559,21 @@ function get_entities_from_private_setting($name = "", $value = "", $type = "", if (!is_null($container_guid)) { if (is_array($container_guid)) { - foreach($container_guid as $key => $val) $container_guid[$key] = (int) $val; - $where[] = "e.container_guid in (" . implode(",",$container_guid) . ")"; + foreach ($container_guid as $key => $val) { + $container_guid[$key] = (int) $val; + } + $where[] = "e.container_guid in (" . implode(",", $container_guid) . ")"; } else { $container_guid = (int) $container_guid; $where[] = "e.container_guid = {$container_guid}"; } } - if ($name!="") { + if ($name != "") { $where[] = "s.name = '$name'"; } - if ($value!="") { + if ($value != "") { $where[] = "s.value='$value'"; } @@ -2472,21 +2609,24 @@ function get_entities_from_private_setting($name = "", $value = "", $type = "", /** * Get entities based on their private data by multiple keys. * - * @param string $name The name of the setting - * @param string $value The value of the setting - * @param string|array $type The type of entity (eg "user", "object" etc) or array(type1 => array('subtype1', ...'subtypeN'), ...) - * @param string $subtype The arbitrary subtype of the entity - * @param int $owner_guid The GUID of the owning user - * @param string $order_by The field to order by; by default, time_created desc - * @param int $limit The number of entities to return; 10 by default - * @param int $offset The indexing offset, 0 by default - * @param boolean $count Set to true to get a count rather than the entities themselves (limits and offsets don't apply in this context). Defaults to false. - * @param int $site_guid The site to get entities for. Leave as 0 (default) for the current site; -1 for all sites. - * @param int|array $container_guid The container or containers to get entities from (default: all containers). + * @param string $name The name of the setting + * @param mixed $type Entity type + * @param string $subtype Entity subtype + * @param int $owner_guid The GUID of the owning user + * @param string $order_by The field to order by; by default, time_created desc + * @param int $limit The number of entities to return; 10 by default + * @param int $offset The indexing offset, 0 by default + * @param bool $count Count entities + * @param int $site_guid Site GUID. 0 for current, -1 for any. + * @param mixed $container_guid Container GUID + * * @return array A list of entities. * @todo deprecate */ -function get_entities_from_private_setting_multi(array $name, $type = "", $subtype = "", $owner_guid = 0, $order_by = "", $limit = 10, $offset = 0, $count = false, $site_guid = 0, $container_guid = null) { +function get_entities_from_private_setting_multi(array $name, $type = "", $subtype = "", +$owner_guid = 0, $order_by = "", $limit = 10, $offset = 0, $count = false, +$site_guid = 0, $container_guid = null) { + global $CONFIG; if ($subtype === false || $subtype === null || $subtype === 0) { @@ -2509,8 +2649,8 @@ function get_entities_from_private_setting_multi(array $name, $type = "", $subty if (is_array($type)) { $tempwhere = ""; if (sizeof($type)) { - foreach($type as $typekey => $subtypearray) { - foreach($subtypearray as $subtypeval) { + foreach ($type as $typekey => $subtypearray) { + foreach ($subtypearray as $subtypeval) { $typekey = sanitise_string($typekey); if (!empty($subtypeval)) { if (!$subtypeval = (int) get_subtype_id($typekey, $subtypeval)) { @@ -2519,7 +2659,9 @@ function get_entities_from_private_setting_multi(array $name, $type = "", $subty } else { $subtypeval = 0; } - if (!empty($tempwhere)) $tempwhere .= " or "; + if (!empty($tempwhere)) { + $tempwhere .= " or "; + } $tempwhere .= "(e.type = '{$typekey}' and e.subtype = {$subtypeval})"; } } @@ -2538,7 +2680,7 @@ function get_entities_from_private_setting_multi(array $name, $type = "", $subty $where[] = "e.type='$type'"; } - if ($subtype!=="") { + if ($subtype !== "") { $where[] = "e.subtype=$subtype"; } } @@ -2547,13 +2689,8 @@ function get_entities_from_private_setting_multi(array $name, $type = "", $subty if (!is_array($owner_guid)) { $owner_array = array($owner_guid); $owner_guid = (int) $owner_guid; - // $where[] = "owner_guid = '$owner_guid'"; } else if (sizeof($owner_guid) > 0) { $owner_array = array_map('sanitise_int', $owner_guid); - // Cast every element to the owner_guid array to int - // $owner_guid = array_map("sanitise_int", $owner_guid); - // $owner_guid = implode(",",$owner_guid); - // $where[] = "owner_guid in ({$owner_guid})"; } if (is_null($container_guid)) { $container_guid = $owner_array; @@ -2565,8 +2702,10 @@ function get_entities_from_private_setting_multi(array $name, $type = "", $subty if (!is_null($container_guid)) { if (is_array($container_guid)) { - foreach($container_guid as $key => $val) $container_guid[$key] = (int) $val; - $where[] = "e.container_guid in (" . implode(",",$container_guid) . ")"; + foreach ($container_guid as $key => $val) { + $container_guid[$key] = (int) $val; + } + $where[] = "e.container_guid in (" . implode(",", $container_guid) . ")"; } else { $container_guid = (int) $container_guid; $where[] = "e.container_guid = {$container_guid}"; @@ -2624,8 +2763,9 @@ function get_entities_from_private_setting_multi(array $name, $type = "", $subty * @internal Private data is used to store settings for plugins * and user settings. * - * @param int $entity_guid The entity GUID - * @param string $name The name of the setting + * @param int $entity_guid The entity GUID + * @param string $name The name of the setting + * * @return mixed The setting value, or false on failure * @see set_private_setting() * @see get_all_private_settings() @@ -2638,7 +2778,11 @@ function get_private_setting($entity_guid, $name) { $entity_guid = (int) $entity_guid; $name = sanitise_string($name); - if ($setting = get_data_row("SELECT value from {$CONFIG->dbprefix}private_settings where name = '{$name}' and entity_guid = {$entity_guid}")) { + $query = "SELECT value from {$CONFIG->dbprefix}private_settings + where name = '{$name}' and entity_guid = {$entity_guid}"; + $setting = get_data_row($query); + + if ($setting) { return $setting->value; } return false; @@ -2648,6 +2792,7 @@ function get_private_setting($entity_guid, $name) { * Return an array of all private settings. * * @param int $entity_guid The entity GUID + * * @return array|false * @see set_private_setting() * @see get_private_settings() @@ -2660,7 +2805,8 @@ function get_all_private_settings($entity_guid) { $entity_guid = (int) $entity_guid; - $result = get_data("SELECT * from {$CONFIG->dbprefix}private_settings where entity_guid = {$entity_guid}"); + $query = "SELECT * from {$CONFIG->dbprefix}private_settings where entity_guid = {$entity_guid}"; + $result = get_data($query); if ($result) { $return = array(); foreach ($result as $r) { @@ -2676,9 +2822,10 @@ function get_all_private_settings($entity_guid) { /** * Sets a private setting for an entity. * - * @param int $entity_guid The entity GUID - * @param string $name The name of the setting - * @param string $value The value of the setting + * @param int $entity_guid The entity GUID + * @param string $name The name of the setting + * @param string $value The value of the setting + * * @return mixed The setting ID, or false on failure * @see get_private_setting() * @see get_all_private_settings() @@ -2706,8 +2853,9 @@ function set_private_setting($entity_guid, $name, $value) { /** * Deletes a private setting for an entity. * - * @param int $entity_guid The Entity GUID - * @param string $name The name of the setting + * @param int $entity_guid The Entity GUID + * @param string $name The name of the setting + * * @return true|false depending on success * @see get_private_setting() * @see get_all_private_settings() @@ -2730,6 +2878,7 @@ function remove_private_setting($entity_guid, $name) { * Deletes all private settings for an entity. * * @param int $entity_guid The Entity GUID + * * @return true|false depending on success * @see get_private_setting() * @see get_all_private_settings() @@ -2745,7 +2894,7 @@ function remove_all_private_settings($entity_guid) { where entity_guid = {$entity_guid}"); } -/* +/** * Check the recursive delete permissions token. * * If an entity is deleted recursively, a permissions override is required to allow @@ -2756,12 +2905,11 @@ function remove_all_private_settings($entity_guid) { * @elgg_plugin_hook_handler permissions_check all * @elgg_plugin_hook_handler permissions_check:metadata all */ -function recursive_delete_permissions_check($hook, $entity_type, $returnvalue, $params) { +function recursive_delete_permissions_check() { static $__RECURSIVE_DELETE_TOKEN; - $entity = $params['entity']; - - if ((isloggedin()) && ($__RECURSIVE_DELETE_TOKEN) && (strcmp($__RECURSIVE_DELETE_TOKEN, md5(get_loggedin_userid())))) { + if ((isloggedin()) && ($__RECURSIVE_DELETE_TOKEN) + && (strcmp($__RECURSIVE_DELETE_TOKEN, md5(get_loggedin_userid())))) { return true; } @@ -2775,9 +2923,11 @@ function recursive_delete_permissions_check($hook, $entity_type, $returnvalue, $ * @tip Use this function in actions and views to check that you are dealing * with the correct type of entity. * - * @param $entity - * @param $type - * @param $subtype + * @param mixed $entity Entity + * @param string $type Entity type + * @param string $subtype Entity subtype + * @param string $class Class name + * * @return Bool * @since 1.8 */ @@ -2808,10 +2958,12 @@ function elgg_instanceof($entity, $type = NULL, $subtype = NULL, $class = NULL) * @warning This is different to time_updated. Time_updated is automatically set, * while last_action is only set when explicitly called. * - * @param int $guid Entity annotation|relationship action carried out on + * @param int $guid Entity annotation|relationship action carried out on * @param int $posted Timestamp of last action + * + * @return bool **/ -function update_entity_last_action($guid, $posted = NULL){ +function update_entity_last_action($guid, $posted = NULL) { global $CONFIG; $guid = (int)$guid; @@ -2819,10 +2971,11 @@ function update_entity_last_action($guid, $posted = NULL){ $posted = time(); } - if ($guid){ + if ($guid) { //now add to the river updated table - $query = update_data("UPDATE {$CONFIG->dbprefix}entities SET last_action = {$posted} WHERE guid = {$guid}"); - if ($query) { + $query = "UPDATE {$CONFIG->dbprefix}entities SET last_action = {$posted} WHERE guid = {$guid}"; + $result = update_data($query); + if ($result) { return TRUE; } else { return FALSE; @@ -2835,13 +2988,10 @@ function update_entity_last_action($guid, $posted = NULL){ /** * Garbage collect stub and fragments from any broken delete/create calls * - * @param unknown_type $hook - * @param unknown_type $user - * @param unknown_type $returnvalue - * @param unknown_type $tag + * @return void * @elgg_plugin_hook_handler gc system */ -function entities_gc($hook, $user, $returnvalue, $tag) { +function entities_gc() { global $CONFIG; $tables = array ('sites_entity', 'objects_entity', 'groups_entity', 'users_entity'); @@ -2855,7 +3005,12 @@ function entities_gc($hook, $user, $returnvalue, $tag) { /** * Runs unit tests for the entity objects. * - * @elgg_plugin_hook_handler unit_test system + * @param sting $hook unit_test + * @param string $type system + * @param mixed $value Array of tests + * @param mixed $params Params + * + * @return array */ function entities_test($hook, $type, $value, $params) { global $CONFIG; @@ -2866,19 +3021,20 @@ function entities_test($hook, $type, $value, $params) { /** * Entities init function; establishes the default entity page handler * + * @return void * @elgg_event_handler init system */ function entities_init() { - register_page_handler('view','entities_page_handler'); + register_page_handler('view', 'entities_page_handler'); register_plugin_hook('unit_test', 'system', 'entities_test'); // Allow a permission override for recursive entity deletion // @todo Can this be done better? - register_plugin_hook('permissions_check','all','recursive_delete_permissions_check'); - register_plugin_hook('permissions_check:metadata','all','recursive_delete_permissions_check'); + register_plugin_hook('permissions_check', 'all', 'recursive_delete_permissions_check'); + register_plugin_hook('permissions_check:metadata', 'all', 'recursive_delete_permissions_check'); - register_plugin_hook('gc','system','entities_gc'); + register_plugin_hook('gc', 'system', 'entities_gc'); } /** Register the import hook */ diff --git a/engine/lib/export.php b/engine/lib/export.php index 667366cc4..eaf2fd3dd 100644 --- a/engine/lib/export.php +++ b/engine/lib/export.php @@ -2,14 +2,15 @@ /** * Elgg Data import export functionality. * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage DataModel.Export */ /** * Get a UUID from a given object. * - * @param $object The object either an ElggEntity, ElggRelationship or ElggExtender + * @param mixed $object The object either an ElggEntity, ElggRelationship or ElggExtender + * * @return the UUID or false */ function get_uuid_from_object($object) { @@ -18,9 +19,9 @@ function get_uuid_from_object($object) { } else if ($object instanceof ElggExtender) { $type = $object->type; if ($type == 'volatile') { - $uuid = guid_to_uuid($object->entity_guid). $type . "/{$object->name}/"; + $uuid = guid_to_uuid($object->entity_guid) . $type . "/{$object->name}/"; } else { - $uuid = guid_to_uuid($object->entity_guid). $type . "/{$object->id}/"; + $uuid = guid_to_uuid($object->entity_guid) . $type . "/{$object->id}/"; } return $uuid; @@ -35,6 +36,8 @@ function get_uuid_from_object($object) { * Generate a UUID from a given GUID. * * @param int $guid The GUID of an object. + * + * @return string */ function guid_to_uuid($guid) { global $CONFIG; @@ -44,7 +47,9 @@ function guid_to_uuid($guid) { /** * Test to see if a given uuid is for this domain, returning true if so. - * @param $uuid + * + * @param string $uuid A unique ID + * * @return bool */ function is_uuid_this_domain($uuid) { @@ -60,12 +65,15 @@ function is_uuid_this_domain($uuid) { /** * This function attempts to retrieve a previously imported entity via its UUID. * - * @param $uuid + * @param string $uuid A unique ID + * + * @return mixed */ function get_entity_from_uuid($uuid) { $uuid = sanitise_string($uuid); - $entities = elgg_get_entities_from_metadata(array('metadata_name' => 'import_uuid', 'metadata_value' => $uuid)); + $options = array('metadata_name' => 'import_uuid', 'metadata_value' => $uuid); + $entities = elgg_get_entities_from_metadata($options); if ($entities) { return $entities[0]; @@ -77,8 +85,9 @@ function get_entity_from_uuid($uuid) { /** * Tag a previously created guid with the uuid it was imported on. * - * @param int $guid - * @param string $uuid + * @param int $guid A GUID + * @param string $uuid A Unique ID + * * @return bool */ function add_uuid_to_guid($guid, $uuid) { @@ -100,8 +109,10 @@ $IMPORTED_OBJECT_COUNTER = 0; * If nobody processes the top level element, the sub level elements are processed. * * @param ODD $odd The odd element to process + * + * @return bool */ -function __process_element(ODD $odd) { +function _process_element(ODD $odd) { global $IMPORTED_DATA, $IMPORTED_OBJECT_COUNTER; // See if anyone handles this element, return true if it is. @@ -122,17 +133,22 @@ function __process_element(ODD $odd) { return false; } +/** + * Exports an entity as an array + * + * @param int $guid Entity GUID + * + * @return array + * @throws ExportException + */ function exportAsArray($guid) { $guid = (int)$guid; - // Initialise the array - $to_be_serialised = array(); - // Trigger a hook to - $to_be_serialised = trigger_plugin_hook("export", "all", array("guid" => $guid), $to_be_serialised); + $to_be_serialised = trigger_plugin_hook("export", "all", array("guid" => $guid), array()); // Sanity check - if ((!is_array($to_be_serialised)) || (count($to_be_serialised)==0)) { + if ((!is_array($to_be_serialised)) || (count($to_be_serialised) == 0)) { throw new ExportException(sprintf(elgg_echo('ExportException:NoSuchEntity'), $guid)); } @@ -147,10 +163,10 @@ function exportAsArray($guid) { * This function makes use of the "serialise" plugin hook, which is passed an array to which plugins * should add data to be serialised to. * - * @see ElggEntity for an example of its usage. * @param int $guid The GUID. - * @param ODDWrapperFactory $wrapper Optional wrapper permitting the export process to embed ODD in other document formats. + * * @return xml + * @see ElggEntity for an example of its usage. */ function export($guid) { $odd = new ODDDocument(exportAsArray($guid)); @@ -162,7 +178,8 @@ function export($guid) { * Import an XML serialisation of an object. * This will make a best attempt at importing a given xml doc. * - * @param string $xml + * @param string $xml XML string + * * @return bool * @throws Exception if there was a problem importing the data. */ @@ -178,10 +195,10 @@ function import($xml) { } foreach ($document as $element) { - __process_element($element); + _process_element($element); } - if ($IMPORTED_OBJECT_COUNTER!= count($IMPORTED_DATA)) { + if ($IMPORTED_OBJECT_COUNTER != count($IMPORTED_DATA)) { throw new ImportException(elgg_echo('ImportException:NotAllImported')); } @@ -191,6 +208,8 @@ function import($xml) { /** * Register the OpenDD import action + * + * @return void */ function export_init() { global $CONFIG; diff --git a/engine/lib/extender.php b/engine/lib/extender.php index 8fe9958c6..0f7ab24ea 100644 --- a/engine/lib/extender.php +++ b/engine/lib/extender.php @@ -3,8 +3,8 @@ * Elgg Entity Extender. * This file contains ways of extending an Elgg entity in custom ways. * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage DataModel.Extender */ /** @@ -13,12 +13,13 @@ * * @todo Make better! * - * @param mixed $value + * @param mixed $value The value * @param string $value_type If specified, overrides the detection. + * * @return string */ function detect_extender_valuetype($value, $value_type = "") { - if ($value_type!="") { + if ($value_type != "") { return $value_type; } @@ -35,11 +36,13 @@ function detect_extender_valuetype($value, $value_type = "") { } /** - * Utility function used by import_extender_plugin_hook() to process an ODDMetaData and add it to an entity. - * This function does not hit ->save() on the entity (this lets you construct in memory) + * Utility function used by import_extender_plugin_hook() to process + * an ODDMetaData and add it to an entity. This function does not + * hit ->save() on the entity (this lets you construct in memory) * - * @param ElggEntity The entity to add the data to. + * @param ElggEntity $entity The entity to add the data to. * @param ODDMetaData $element The OpenDD element + * * @return bool */ function oddmetadata_to_elggextender(ElggEntity $entity, ODDMetaData $element) { @@ -73,6 +76,16 @@ function oddmetadata_to_elggextender(ElggEntity $entity, ODDMetaData $element) { /** * Handler called by trigger_plugin_hook on the "import" event. + * + * @param string $hook volatile + * @param string $entity_type metadata + * @param string $returnvalue Return value from previous hook + * @param array $params The parameters + * + * @return null + * @elgg_plugin_hook_handler volatile metadata + * @todo investigate more. + * @access private */ function import_extender_plugin_hook($hook, $entity_type, $returnvalue, $params) { $element = $params['element']; @@ -91,7 +104,8 @@ function import_extender_plugin_hook($hook, $entity_type, $returnvalue, $params) // Save if (!$entity->save()) { - throw new ImportException(sprintf(elgg_echo('ImportException:ProblemUpdatingMeta'), $attr_name, $entity_uuid)); + $msg = sprintf(elgg_echo('ImportException:ProblemUpdatingMeta'), $attr_name, $entity_uuid); + throw new ImportException($msg); } return true; @@ -101,9 +115,10 @@ function import_extender_plugin_hook($hook, $entity_type, $returnvalue, $params) /** * Determines whether or not the specified user can edit the specified piece of extender * - * @param int $extender_id The ID of the piece of extender - * @param string $type 'metadata' or 'annotation' - * @param int $user_guid The GUID of the user + * @param int $extender_id The ID of the piece of extender + * @param string $type 'metadata' or 'annotation' + * @param int $user_guid The GUID of the user + * * @return true|false */ function can_edit_extender($extender_id, $type, $user_guid = 0) { @@ -124,7 +139,7 @@ function can_edit_extender($extender_id, $type, $user_guid = 0) { return false; } - if (!is_a($extender,"ElggExtender")) { + if (!is_a($extender, "ElggExtender")) { return false; } @@ -134,25 +149,29 @@ function can_edit_extender($extender_id, $type, $user_guid = 0) { } // If the user can edit the entity this is attached to, great! They can edit. - if (can_edit_entity($extender->entity_guid,$user->getGUID())) { + if (can_edit_entity($extender->entity_guid, $user->getGUID())) { return true; } // Trigger plugin hooks - return trigger_plugin_hook('permissions_check',$type,array('entity' => $entity, 'user' => $user),false); + $params = array('entity' => $entity, 'user' => $user); + return trigger_plugin_hook('permissions_check', $type, $params, false); } /** * Sets the URL handler for a particular extender type and name. - * It is recommended that you do not call this directly, instead use one of the wrapper functions in the - * subtype files. + * It is recommended that you do not call this directly, instead use + * one of the wrapper functions in the subtype files. * * @param string $function_name The function to register * @param string $extender_type Extender type * @param string $extender_name The name of the extender + * * @return true|false Depending on success */ -function register_extender_url_handler($function_name, $extender_type = "all", $extender_name = "all") { +function register_extender_url_handler($function_name, $extender_type = "all", +$extender_name = "all") { + global $CONFIG; if (!is_callable($function_name)) { @@ -174,7 +193,9 @@ function register_extender_url_handler($function_name, $extender_type = "all", $ * Get the URL of a given elgg extender. * Used by get_annotation_url and get_metadata_url. * - * @param ElggExtender $extender + * @param ElggExtender $extender An extender object + * + * @return string */ function get_extender_url(ElggExtender $extender) { global $CONFIG; @@ -206,7 +227,7 @@ function get_extender_url(ElggExtender $extender) { if ($url == "") { $nameid = $extender->id; if ($type == 'volatile') { - $nameid== $extender->name; + $nameid == $extender->name; } $url = $CONFIG->wwwroot . "export/$view/$guid/$type/$nameid/"; } diff --git a/engine/lib/filestore.php b/engine/lib/filestore.php index 2e133690c..0c9f8107c 100644 --- a/engine/lib/filestore.php +++ b/engine/lib/filestore.php @@ -1,28 +1,30 @@ <?php /** * Elgg filestore. - * This file contains classes, interfaces and functions for saving and retrieving data to various file - * stores. + * This file contains classes, interfaces and functions for + * saving and retrieving data to various file stores. * - * @package Elgg - * @subpackage API + * @package Elgg.Core + * @subpackage DataModel.FileStorage */ /** * Get the size of the specified directory. * - * @param string $dir The full path of the directory + * @param string $dir The full path of the directory + * @param int $totalsize Add to current dir size + * * @return int The size of the directory. */ -function get_dir_size($dir, $totalsize = 0){ +function get_dir_size($dir, $totalsize = 0) { $handle = @opendir($dir); - while ($file = @readdir ($handle)){ + while ($file = @readdir ($handle)) { if (eregi("^\.{1,2}$", $file)) { continue; } - if(is_dir($dir . $file)) { + if (is_dir($dir . $file)) { $totalsize = get_dir_size($dir . $file . "/", $totalsize); - } else{ + } else { $totalsize += filesize($dir . $file); } } @@ -36,6 +38,7 @@ function get_dir_size($dir, $totalsize = 0){ * (Returns false if there was an issue.) * * @param string $input_name The name of the file input field on the submission form + * * @return mixed|false The contents of the file, or false on failure. */ function get_uploaded_file($input_name) { @@ -51,17 +54,24 @@ function get_uploaded_file($input_name) { * (Returns false if the uploaded file was not an image) * * @param string $input_name The name of the file input field on the submission form - * @param int $maxwidth The maximum width of the resized image - * @param int $maxheight The maximum height of the resized image - * @param true|false $square If set to true, will take the smallest of maxwidth and maxheight and use it to set the dimensions on all size; the image will be cropped. - * @param true|false $upscale Resize images smaller than $maxwidth x $maxheight? + * @param int $maxwidth The maximum width of the resized image + * @param int $maxheight The maximum height of the resized image + * @param bool $square If set to true, will take the smallest + * of maxwidth and maxheight and use it to set the + * dimensions on all size; the image will be cropped. + * @param bool $upscale Resize images smaller than $maxwidth x $maxheight? + * * @return false|mixed The contents of the resized image, or false on failure */ -function get_resized_image_from_uploaded_file($input_name, $maxwidth, $maxheight, $square = false, $upscale = false) { +function get_resized_image_from_uploaded_file($input_name, $maxwidth, $maxheight, +$square = false, $upscale = false) { + // If our file exists ... if (isset($_FILES[$input_name]) && $_FILES[$input_name]['error'] == 0) { - return get_resized_image_from_existing_file($_FILES[$input_name]['tmp_name'], $maxwidth, $maxheight, $square, 0, 0, 0, 0, $upscale); + return get_resized_image_from_existing_file($_FILES[$input_name]['tmp_name'], $maxwidth, + $maxheight, $square, 0, 0, 0, 0, $upscale); } + return false; } @@ -70,21 +80,24 @@ function get_resized_image_from_uploaded_file($input_name, $maxwidth, $maxheight * (Returns false if the file was not an image) * * @param string $input_name The name of the file on the disk - * @param int $maxwidth The desired width of the resized image - * @param int $maxheight The desired height of the resized image - * @param true|false $square If set to true, takes the smallest of maxwidth and - * maxheight and use it to set the dimensions on the new image. If no - * crop parameters are set, the largest square that fits in the image - * centered will be used for the resize. If square, the crop must be a - * square region. - * @param int $x1 x coordinate for top, left corner - * @param int $y1 y coordinate for top, left corner - * @param int $x2 x coordinate for bottom, right corner - * @param int $y2 y coordinate for bottom, right corner - * @param bool $upscale Resize images smaller than $maxwidth x $maxheight? + * @param int $maxwidth The desired width of the resized image + * @param int $maxheight The desired height of the resized image + * @param bool $square If set to true, takes the smallest of maxwidth and + * maxheight and use it to set the dimensions on the new image. + * If no crop parameters are set, the largest square that fits + * in the image centered will be used for the resize. If square, + * the crop must be a square region. + * @param int $x1 x coordinate for top, left corner + * @param int $y1 y coordinate for top, left corner + * @param int $x2 x coordinate for bottom, right corner + * @param int $y2 y coordinate for bottom, right corner + * @param bool $upscale Resize images smaller than $maxwidth x $maxheight? + * * @return false|mixed The contents of the resized image, or false on failure */ -function get_resized_image_from_existing_file($input_name, $maxwidth, $maxheight, $square = FALSE, $x1 = 0, $y1 = 0, $x2 = 0, $y2 = 0, $upscale = FALSE) { +function get_resized_image_from_existing_file($input_name, $maxwidth, $maxheight, $square = FALSE, +$x1 = 0, $y1 = 0, $x2 = 0, $y2 = 0, $upscale = FALSE) { + // Get the size information from the image $imgsizearray = getimagesize($input_name); if ($imgsizearray == FALSE) { @@ -164,9 +177,10 @@ function get_resized_image_from_existing_file($input_name, $maxwidth, $maxheight /** * Calculate the parameters for resizing an image * - * @param int $width Width of the original image - * @param int $height Height of the original image + * @param int $width Width of the original image + * @param int $height Height of the original image * @param array $options See $defaults for the options + * * @return array or FALSE * @since 1.7.2 */ @@ -175,7 +189,7 @@ function get_image_resize_parameters($width, $height, $options) { $defaults = array( 'maxwidth' => 100, 'maxheight' => 100, - + 'square' => FALSE, 'upscale' => FALSE, @@ -278,7 +292,13 @@ function get_image_resize_parameters($width, $height, $options) { return $params; } -// putting these here for now +/** + * Delete an ElggFile file + * + * @param int $guid ElggFile GUID + * + * @return bool + */ function file_delete($guid) { if ($file = get_entity($guid)) { if ($file->canEdit()) { @@ -317,6 +337,7 @@ function file_delete($guid) { * Returns an overall file type from the mimetype * * @param string $mimetype The MIME type + * * @return string The overall type */ function file_get_general_file_type($mimetype) { @@ -330,30 +351,41 @@ function file_get_general_file_type($mimetype) { break; } - if (substr_count($mimetype,'text/')) { + if (substr_count($mimetype, 'text/')) { return "document"; } - if (substr_count($mimetype,'audio/')) { + if (substr_count($mimetype, 'audio/')) { return "audio"; } - if (substr_count($mimetype,'image/')) { + if (substr_count($mimetype, 'image/')) { return "image"; } - if (substr_count($mimetype,'video/')) { + if (substr_count($mimetype, 'video/')) { return "video"; } - if (substr_count($mimetype,'opendocument')) { + if (substr_count($mimetype, 'opendocument')) { return "document"; } return "general"; } -function file_handle_upload($prefix,$subtype,$plugin) { +/** + * Not currently used + * + * @todo remove + * + * @param string $prefix Unknown + * @param string $subtype Unknown + * @param string $plugin Unknown + * + * @return void + */ +function file_handle_upload($prefix, $subtype, $plugin) { $desc = get_input("description"); $tags = get_input("tags"); $tags = explode(",", $tags); @@ -370,31 +402,42 @@ function file_handle_upload($prefix,$subtype,$plugin) { // Extract file from, save to default filestore (for now) // see if a plugin has set a quota for this user - $file_quota = trigger_plugin_hook("$plugin:quotacheck",'user',array('container_guid'=>$container_guid)); + $params = array('container_guid'=>$container_guid); + $file_quota = trigger_plugin_hook("$plugin:quotacheck", 'user', $param); + if (!$file_quota) { // no, see if there is a generic quota set $file_quota = get_plugin_setting('quota', $plugin); } if ($file_quota) { // convert to megabytes - $file_quota = $file_quota*1000*1024; + $file_quota = $file_quota * 1000 * 1024; } // handle uploaded files - $number_of_files = get_input('number_of_files',0); + $number_of_files = get_input('number_of_files', 0); $quota_exceeded = false; $bad_mime_type = false; for ($i = 0; $i < $number_of_files; $i++) { - $title = get_input("title_".$i); - $uploaded = $_FILES["upload_".$i]; + $title = get_input("title_" . $i); + $uploaded = $_FILES["upload_" . $i]; if (!$uploaded || !$uploaded['name']) { // no such file, so skip it continue; } if ($plugin == "photo") { // do a mime type test - if (in_array($uploaded['type'],array('image/jpeg','image/gif','image/png','image/jpg','image/jpe','image/pjpeg','image/x-png'))) { + $supported_types = array( + 'image/jpeg', + 'image/gif', + 'image/png', + 'image/jpg', + 'image/jpe', + 'image/pjpeg', + 'image/x-png' + ); + if (in_array($uploaded['type'], $supported_types)) { $file = new PhotoPluginFile(); } else { $bad_mime_type = true; @@ -403,9 +446,9 @@ function file_handle_upload($prefix,$subtype,$plugin) { } else { $file = new FilePluginFile(); } - $dir_size = $file->getFilestoreSize($prefix,$container_guid); - $filestorename = strtolower(time().$uploaded['name']); - $file->setFilename($prefix.$filestorename); + $dir_size = $file->getFilestoreSize($prefix, $container_guid); + $filestorename = strtolower(time() . $uploaded['name']); + $file->setFilename($prefix . $filestorename); $file->setMimeType($uploaded['type']); $file->originalfilename = $uploaded['name']; @@ -414,7 +457,7 @@ function file_handle_upload($prefix,$subtype,$plugin) { $file->access_id = $access_id; - $uf = get_uploaded_file('upload_'.$i); + $uf = get_uploaded_file('upload_' . $i); if ($file_quota) { $file_size = strlen($uf); @@ -447,39 +490,43 @@ function file_handle_upload($prefix,$subtype,$plugin) { if ($result) { // Generate thumbnail (if image) - if (substr_count($file->getMimeType(),'image/')) { - $thumbnail = get_resized_image_from_existing_file($file->getFilenameOnFilestore(),60,60, true); - $thumbsmall = get_resized_image_from_existing_file($file->getFilenameOnFilestore(),153,153, true); - $thumblarge = get_resized_image_from_existing_file($file->getFilenameOnFilestore(),600,600, false); + if (substr_count($file->getMimeType(), 'image/')) { + $thumbnail = get_resized_image_from_existing_file($file->getFilenameOnFilestore(), 60, + 60, true); + $thumbsmall = get_resized_image_from_existing_file($file->getFilenameOnFilestore(), 153, + 153, true); + $thumblarge = get_resized_image_from_existing_file($file->getFilenameOnFilestore(), 600, + 600, false); + if ($thumbnail) { $thumb = new ElggFile(); $thumb->setMimeType($uploaded['type']); - $thumb->setFilename($prefix."thumb".$filestorename); + $thumb->setFilename($prefix . "thumb" . $filestorename); $thumb->open("write"); $thumb->write($thumbnail); $thumb->close(); - $file->thumbnail = $prefix."thumb".$filestorename; + $file->thumbnail = $prefix . "thumb" . $filestorename; - $thumb->setFilename($prefix."smallthumb".$filestorename); + $thumb->setFilename($prefix . "smallthumb" . $filestorename); $thumb->open("write"); $thumb->write($thumbsmall); $thumb->close(); - $file->smallthumb = $prefix."smallthumb".$filestorename; + $file->smallthumb = $prefix . "smallthumb" . $filestorename; - $thumb->setFilename($prefix."largethumb".$filestorename); + $thumb->setFilename($prefix . "largethumb" . $filestorename); $thumb->open("write"); $thumb->write($thumblarge); $thumb->close(); - $file->largethumb = $prefix."largethumb".$filestorename; + $file->largethumb = $prefix . "largethumb" . $filestorename; } } // add to this user's file folders - file_add_to_folders($folder,$container_guid,$plugin); + file_add_to_folders($folder, $container_guid, $plugin); - add_to_river("river/object/$plugin/create",'create',$_SESSION['user']->guid,$file->guid); + add_to_river("river/object/$plugin/create", 'create', $_SESSION['user']->guid, $file->guid); } else { break; } @@ -490,7 +537,7 @@ function file_handle_upload($prefix,$subtype,$plugin) { if ($quota_exceeded) { echo elgg_echo("$plugin:quotaexceeded"); - } else if ($bad_mime_type) { + } else if ($bad_mime_type) { echo elgg_echo("$plugin:badmimetype"); } else if ($result) { if ($number_of_files > 1) { @@ -507,19 +554,26 @@ function file_handle_upload($prefix,$subtype,$plugin) { } } -function file_add_to_folders($folder,$container_guid,$plugin) { +/** + * @todo remove + * + * @param unknown_type $folder + * @param unknown_type $container_guid + * @param unknown_type $plugin + */ +function file_add_to_folders($folder, $container_guid, $plugin) { if ($container_guid && ($container = get_entity($container_guid))) { - $folder_field_name = 'elgg_'.$plugin.'_folders'; + $folder_field_name = 'elgg_' . $plugin . '_folders'; $folders = $container->$folder_field_name; if ($folders) { if (is_array($folders)) { - if (!in_array($folder,$folders)) { + if (!in_array($folder, $folders)) { $folders[] = $folder; $container->$folder_field_name = $folders; } } else { if ($folders != $folder) { - $container->$folder_field_name = array($folders,$folder); + $container->$folder_field_name = array($folders, $folder); } } } else { @@ -528,7 +582,13 @@ function file_add_to_folders($folder,$container_guid,$plugin) { } } -function file_handle_save($forward,$plugin) { +/** + * @todo remove + * + * @param unknown_type $forward + * @param unknown_type $plugin + */ +function file_handle_save($forward, $plugin) { // Get variables $title = get_input("title"); $desc = get_input("description"); @@ -558,10 +618,10 @@ function file_handle_save($forward,$plugin) { $file->description = $desc; $file->folder = $folder; // add to this user's file folders - file_add_to_folders($folder,$container_guid,$plugin); + file_add_to_folders($folder, $container_guid, $plugin); // Save tags - $tags = explode(",", $tags); + $tags = explode(", ", $tags); $file->tags = $tags; $result = $file->save(); @@ -578,7 +638,9 @@ function file_handle_save($forward,$plugin) { /** * Manage a file download. * - * @param unknown_type $plugin + * @todo remove + * + * @param unknown_type $plugin Unknown * @param unknown_type $file_guid If not specified then file_guid will be found in input. */ function file_manage_download($plugin, $file_guid = "") { @@ -617,6 +679,7 @@ function file_manage_download($plugin, $file_guid = "") { /** * Manage the download of a file icon. * + * @todo remove * @param unknown_type $plugin * @param unknown_type $file_guid The guid, if not specified this is obtained from the input. */ @@ -672,7 +735,13 @@ function file_manage_icon_download($plugin, $file_guid = "") { } } -function file_display_thumbnail($file_guid,$size) { +/** + * @todo remove + * + * @param unknown_type $file_guid + * @param unknown_type $size + */ +function file_display_thumbnail($file_guid, $size) { // Get file entity if ($file = get_entity($file_guid)) { $simpletype = $file->simpletype; @@ -700,6 +769,11 @@ function file_display_thumbnail($file_guid,$size) { } } +/** + * @todo remove + * + * @param unknown_type $file + */ function file_set_page_owner($file) { $page_owner = page_owner_entity(); if ($page_owner === false || is_null($page_owner)) { @@ -718,9 +792,11 @@ function file_set_page_owner($file) { } /** - * Recursively delete a directory + * Delete a directory and all its contents * - * @param str $directory + * @param str $directory Directory to delete + * + * @return bool */ function delete_directory($directory) { // sanity check: must be a directory @@ -754,7 +830,11 @@ function delete_directory($directory) { /** * Removes all user files * - * @param ElggUser $user + * @warning This only deletes the physical files and not their entities. + * This will result in FileExceptions being thrown. Don't use this function. + * + * @param ElggUser $user And ElggUser + * * @return void */ function clear_user_files($user) { @@ -784,6 +864,10 @@ function get_default_filestore() { /** * Set the default filestore for the system. + * + * @param ElggFilestore $filestore An ElggFilestore object. + * + * @return true */ function set_default_filestore(ElggFilestore $filestore) { global $DEFAULT_FILE_STORE; @@ -794,7 +878,10 @@ function set_default_filestore(ElggFilestore $filestore) { } /** - * Run once and only once. + * Register entity type objects, subtype file as + * ElggFile. + * + * @return void */ function filestore_run_once() { // Register a class @@ -804,6 +891,8 @@ function filestore_run_once() { /** * Initialise the file modules. * Listens to system boot and registers any appropriate file types and classes + * + * @return void */ function filestore_init() { global $CONFIG; @@ -815,13 +904,25 @@ function filestore_init() { run_function_once("filestore_run_once"); } -// Register a startup event -register_elgg_event_handler('init', 'system', 'filestore_init', 100); - -// Unit testing -register_plugin_hook('unit_test', 'system', 'filestore_test'); +/** + * Unit tests for files + * + * @param sting $hook unit_test + * @param string $type system + * @param mixed $value Array of tests + * @param mixed $params Params + * + * @return array + */ function filestore_test($hook, $type, $value, $params) { global $CONFIG; $value[] = "{$CONFIG->path}engine/tests/objects/filestore.php"; return $value; } + + +// Register a startup event +register_elgg_event_handler('init', 'system', 'filestore_init', 100); + +// Unit testing +register_plugin_hook('unit_test', 'system', 'filestore_test');
\ No newline at end of file diff --git a/engine/lib/group.php b/engine/lib/group.php index 64299ff10..8c68e0aca 100644 --- a/engine/lib/group.php +++ b/engine/lib/group.php @@ -1,19 +1,19 @@ <?php /** * Elgg Groups. - * Groups contain other entities, or rather act as a placeholder for other entities to mark any given container - * as their container. + * Groups contain other entities, or rather act as a placeholder for other entities to + * mark any given container as their container. * - * @package Elgg - * @subpackage Core - - + * @package Elgg.Core + * @subpackage DataModel.Group */ /** * Get the group entity. * - * @param int $guid + * @param int $guid GUID for a group + * + * @return array|false */ function get_group_entity_as_row($guid) { global $CONFIG; @@ -27,9 +27,11 @@ function get_group_entity_as_row($guid) { * Create or update the extras table for a given group. * Call create_entity first. * - * @param int $guid - * @param string $name - * @param string $description + * @param int $guid GUID + * @param string $name Name + * @param string $description Description + * + * @return bool */ function create_group_entity($guid, $name, $description) { global $CONFIG; @@ -42,28 +44,32 @@ function create_group_entity($guid, $name, $description) { if ($row) { // Exists and you have access to it - if ($exists = get_data_row("SELECT guid from {$CONFIG->dbprefix}groups_entity WHERE guid = {$guid}")) { - $result = update_data("UPDATE {$CONFIG->dbprefix}groups_entity set name='$name', description='$description' where guid=$guid"); - if ($result!=false) { + $exists = get_data_row("SELECT guid from {$CONFIG->dbprefix}groups_entity WHERE guid = {$guid}"); + if ($exists) { + $query = "UPDATE {$CONFIG->dbprefix}groups_entity set" + . " name='$name', description='$description' where guid=$guid"; + $result = update_data($query); + if ($result != false) { // Update succeeded, continue $entity = get_entity($guid); - if (trigger_elgg_event('update',$entity->type,$entity)) { + if (trigger_elgg_event('update', $entity->type, $entity)) { return $guid; } else { $entity->delete(); - //delete_entity($guid); } } } else { // Update failed, attempt an insert. - $result = insert_data("INSERT into {$CONFIG->dbprefix}groups_entity (guid, name, description) values ($guid, '$name','$description')"); - if ($result!==false) { + $query = "INSERT into {$CONFIG->dbprefix}groups_entity" + . " (guid, name, description) values ($guid, '$name', '$description')"; + + $result = insert_data($query); + if ($result !== false) { $entity = get_entity($guid); - if (trigger_elgg_event('create',$entity->type,$entity)) { + if (trigger_elgg_event('create', $entity->type, $entity)) { return $guid; } else { $entity->delete(); - //delete_entity($guid); } } } @@ -79,6 +85,7 @@ function create_group_entity($guid, $name, $description) { * Delete a group's extra data. * * @param int $guid The guid of the group + * * @return bool */ function delete_group_entity($guid) { @@ -91,9 +98,11 @@ function delete_group_entity($guid) { /** * Add an object to the given group. * - * @param int $group_guid The group to add the object to. + * @param int $group_guid The group to add the object to. * @param int $object_guid The guid of the elgg object (must be ElggObject or a child thereof) + * * @return bool + * @throws InvalidClassException */ function add_object_to_group($group_guid, $object_guid) { $group_guid = (int)$group_guid; @@ -107,11 +116,13 @@ function add_object_to_group($group_guid, $object_guid) { } if (!($group instanceof ElggGroup)) { - throw new InvalidClassException(sprintf(elgg_echo('InvalidClassException:NotValidElggStar'), $group_guid, 'ElggGroup')); + $msg = sprintf(elgg_echo('InvalidClassException:NotValidElggStar'), $group_guid, 'ElggGroup'); + throw new InvalidClassException($msg); } if (!($object instanceof ElggObject)) { - throw new InvalidClassException(sprintf(elgg_echo('InvalidClassException:NotValidElggStar'), $object_guid, 'ElggObject')); + $msg = sprintf(elgg_echo('InvalidClassException:NotValidElggStar'), $object_guid, 'ElggObject'); + throw new InvalidClassException($msg); } $object->container_guid = $group_guid; @@ -121,8 +132,11 @@ function add_object_to_group($group_guid, $object_guid) { /** * Remove an object from the given group. * - * @param int $group_guid The group to remove the object from + * @param int $group_guid The group to remove the object from * @param int $object_guid The object to remove + * + * @return bool + * @throws InvalidClassException */ function remove_object_from_group($group_guid, $object_guid) { $group_guid = (int)$group_guid; @@ -136,11 +150,13 @@ function remove_object_from_group($group_guid, $object_guid) { } if (!($group instanceof ElggGroup)) { - throw new InvalidClassException(sprintf(elgg_echo('InvalidClassException:NotValidElggStar'), $group_guid, 'ElggGroup')); + $msg = sprintf(elgg_echo('InvalidClassException:NotValidElggStar'), $group_guid, 'ElggGroup'); + throw new InvalidClassException($msg); } if (!($object instanceof ElggObject)) { - throw new InvalidClassException(sprintf(elgg_echo('InvalidClassException:NotValidElggStar'), $object_guid, 'ElggObject')); + $msg = sprintf(elgg_echo('InvalidClassException:NotValidElggStar'), $object_guid, 'ElggObject'); + throw new InvalidClassException($msg); } $object->container_guid = $object->owner_guid; @@ -149,20 +165,25 @@ function remove_object_from_group($group_guid, $object_guid) { /** * Return an array of objects in a given container. + * * @see get_entities() * - * @param int $group_guid The container (defaults to current page owner) - * @param string $subtype The subtype - * @param int $owner_guid Owner - * @param int $site_guid The site - * @param string $order_by Order - * @param unknown_type $limit Limit on number of elements to return, by default 10. - * @param unknown_type $offset Where to start, by default 0. - * @param unknown_type $count Whether to return the entities or a count of them. + * @param int $group_guid The container (defaults to current page owner) + * @param string $subtype The subtype + * @param int $owner_guid Owner + * @param int $site_guid The site + * @param string $order_by Order + * @param int $limit Limit on number of elements to return, by default 10. + * @param int $offset Where to start, by default 0. + * @param bool $count Whether to return the entities or a count of them. + * + * @return array|false */ -function get_objects_in_group($group_guid, $subtype = "", $owner_guid = 0, $site_guid = 0, $order_by = "", $limit = 10, $offset = 0, $count = FALSE) { +function get_objects_in_group($group_guid, $subtype = "", $owner_guid = 0, $site_guid = 0, +$order_by = "", $limit = 10, $offset = 0, $count = FALSE) { + global $CONFIG; - + if ($subtype === FALSE || $subtype === null || $subtype === 0) { return FALSE; } @@ -186,7 +207,7 @@ function get_objects_in_group($group_guid, $subtype = "", $owner_guid = 0, $site $where = array(); $where[] = "e.type='object'"; - + if (!empty($subtype)) { if (!$subtype = get_subtype_id('object', $subtype)) { return FALSE; @@ -200,7 +221,7 @@ function get_objects_in_group($group_guid, $subtype = "", $owner_guid = 0, $site } else if (sizeof($owner_guid) > 0) { // Cast every element to the owner_guid array to int $owner_guid = array_map("sanitise_int", $owner_guid); - $owner_guid = implode(",",$owner_guid); + $owner_guid = implode(",", $owner_guid); $where[] = "e.container_guid in ({$owner_guid})"; } } @@ -213,9 +234,11 @@ function get_objects_in_group($group_guid, $subtype = "", $owner_guid = 0, $site } if (!$count) { - $query = "SELECT * from {$CONFIG->dbprefix}entities e join {$CONFIG->dbprefix}objects_entity o on e.guid=o.guid where "; + $query = "SELECT * from {$CONFIG->dbprefix}entities e" + . " join {$CONFIG->dbprefix}objects_entity o on e.guid=o.guid where "; } else { - $query = "SELECT count(e.guid) as total from {$CONFIG->dbprefix}entities e join {$CONFIG->dbprefix}objects_entity o on e.guid=o.guid where "; + $query = "SELECT count(e.guid) as total from {$CONFIG->dbprefix}entities e" + . " join {$CONFIG->dbprefix}objects_entity o on e.guid=o.guid where "; } foreach ($where as $w) { $query .= " $w and "; @@ -242,18 +265,23 @@ function get_objects_in_group($group_guid, $subtype = "", $owner_guid = 0, $site /** * Get all the entities from metadata from a group. * - * @param int $group_guid The ID of the group. - * @param mixed $meta_name - * @param mixed $meta_value - * @param string $entity_type The type of entity to look for, eg 'site' or 'object' + * @param int $group_guid The ID of the group. + * @param mixed $meta_name Metadata name + * @param mixed $meta_value Metadata value + * @param string $entity_type The type of entity to look for, eg 'site' or 'object' * @param string $entity_subtype The subtype of the entity. - * @param int $limit - * @param int $offset - * @param string $order_by Optional ordering. - * @param int $site_guid The site to get entities for. Leave as 0 (default) for the current site; -1 for all sites. - * @param true|false $count If set to true, returns the total number of entities rather than a list. (Default: false) + * @param int $owner_guid Owner guid + * @param int $limit Limit + * @param int $offset Offset + * @param string $order_by Optional ordering. + * @param int $site_guid Site GUID. 0 for current, -1 for any + * @param bool $count Return count instead of entities + * + * @return array|false */ -function get_entities_from_metadata_groups($group_guid, $meta_name, $meta_value = "", $entity_type = "", $entity_subtype = "", $owner_guid = 0, $limit = 10, $offset = 0, $order_by = "", $site_guid = 0, $count = false) { +function get_entities_from_metadata_groups($group_guid, $meta_name, $meta_value = "", +$entity_type = "", $entity_subtype = "", $owner_guid = 0, $limit = 10, $offset = 0, +$order_by = "", $site_guid = 0, $count = false) { global $CONFIG; $meta_n = get_metastring_id($meta_name); @@ -269,7 +297,7 @@ function get_entities_from_metadata_groups($group_guid, $meta_name, $meta_value $order_by = sanitise_string($order_by); $site_guid = (int) $site_guid; if (is_array($owner_guid)) { - foreach($owner_guid as $key => $guid) { + foreach ($owner_guid as $key => $guid) { $owner_guid[$key] = (int) $guid; } } else { @@ -284,20 +312,18 @@ function get_entities_from_metadata_groups($group_guid, $meta_name, $meta_value $container_guid = page_owner(); } - //$access = get_access_list(); - $where = array(); - if ($entity_type!="") { + if ($entity_type != "") { $where[] = "e.type='$entity_type'"; } if ($entity_subtype) { $where[] = "e.subtype=$entity_subtype"; } - if ($meta_name!="") { + if ($meta_name != "") { $where[] = "m.name_id='$meta_n'"; } - if ($meta_value!="") { + if ($meta_value != "") { $where[] = "m.value_id='$meta_v'"; } if ($site_guid > 0) { @@ -308,9 +334,10 @@ function get_entities_from_metadata_groups($group_guid, $meta_name, $meta_value } if (is_array($owner_guid)) { - $where[] = "e.container_guid in (".implode(",",$owner_guid).")"; - } else if ($owner_guid > 0) + $where[] = "e.container_guid in (" . implode(",", $owner_guid ) . ")"; + } else if ($owner_guid > 0) { $where[] = "e.container_guid = {$owner_guid}"; + } if (!$count) { $query = "SELECT distinct e.* "; @@ -318,7 +345,10 @@ function get_entities_from_metadata_groups($group_guid, $meta_name, $meta_value $query = "SELECT count(e.guid) as total "; } - $query .= "from {$CONFIG->dbprefix}entities e JOIN {$CONFIG->dbprefix}metadata m on e.guid = m.entity_guid join {$CONFIG->dbprefix}objects_entity o on e.guid = o.guid where"; + $query .= "from {$CONFIG->dbprefix}entities e" + . " JOIN {$CONFIG->dbprefix}metadata m on e.guid = m.entity_guid " + . " JOIN {$CONFIG->dbprefix}objects_entity o on e.guid = o.guid where"; + foreach ($where as $w) { $query .= " $w and "; } @@ -340,18 +370,23 @@ function get_entities_from_metadata_groups($group_guid, $meta_name, $meta_value /** * As get_entities_from_metadata_groups() but with multiple entities. * - * @param int $group_guid The ID of the group. - * @param array $meta_array Array of 'name' => 'value' pairs - * @param string $entity_type The type of entity to look for, eg 'site' or 'object' + * @param int $group_guid The ID of the group. + * @param array $meta_array Array of 'name' => 'value' pairs + * @param string $entity_type The type of entity to look for, eg 'site' or 'object' * @param string $entity_subtype The subtype of the entity. - * @param int $limit - * @param int $offset - * @param string $order_by Optional ordering. - * @param int $site_guid The site to get entities for. Leave as 0 (default) for the current site; -1 for all sites. - * @param true|false $count If set to true, returns the total number of entities rather than a list. (Default: false) + * @param int $owner_guid Owner GUID + * @param int $limit Limit + * @param int $offset Offset + * @param string $order_by Optional ordering. + * @param int $site_guid Site GUID. 0 for current, -1 for any + * @param bool $count Return count of entities instead of entities + * * @return int|array List of ElggEntities, or the total number if count is set to false */ -function get_entities_from_metadata_groups_multi($group_guid, $meta_array, $entity_type = "", $entity_subtype = "", $owner_guid = 0, $limit = 10, $offset = 0, $order_by = "", $site_guid = 0, $count = false) { +function get_entities_from_metadata_groups_multi($group_guid, $meta_array, $entity_type = "", +$entity_subtype = "", $owner_guid = 0, $limit = 10, $offset = 0, $order_by = "", +$site_guid = 0, $count = false) { + global $CONFIG; if (!is_array($meta_array) || sizeof($meta_array) == 0) { @@ -362,15 +397,17 @@ function get_entities_from_metadata_groups_multi($group_guid, $meta_array, $enti $mindex = 1; $join = ""; - foreach($meta_array as $meta_name => $meta_value) { + foreach ($meta_array as $meta_name => $meta_value) { $meta_n = get_metastring_id($meta_name); $meta_v = get_metastring_id($meta_value); - $join .= " JOIN {$CONFIG->dbprefix}metadata m{$mindex} on e.guid = m{$mindex}.entity_guid join {$CONFIG->dbprefix}objects_entity o on e.guid = o.guid "; - if ($meta_name!="") { + $join .= " JOIN {$CONFIG->dbprefix}metadata m{$mindex} on e.guid = m{$mindex}.entity_guid" + . " JOIN {$CONFIG->dbprefix}objects_entity o on e.guid = o.guid "; + + if ($meta_name != "") { $where[] = "m{$mindex}.name_id='$meta_n'"; } - if ($meta_value!="") { + if ($meta_value != "") { $where[] = "m{$mindex}.value_id='$meta_v'"; } @@ -394,7 +431,7 @@ function get_entities_from_metadata_groups_multi($group_guid, $meta_array, $enti //$access = get_access_list(); - if ($entity_type!="") { + if ($entity_type != "") { $where[] = "e.type = '{$entity_type}'"; } @@ -440,11 +477,12 @@ function get_entities_from_metadata_groups_multi($group_guid, $meta_array, $enti /** * Return a list of this group's members. * - * @param int $group_guid The ID of the container/group. - * @param int $limit The limit - * @param int $offset The offset - * @param int $site_guid The site - * @param bool $count Return the users (false) or the count of them (true) + * @param int $group_guid The ID of the container/group. + * @param int $limit The limit + * @param int $offset The offset + * @param int $site_guid The site + * @param bool $count Return the users (false) or the count of them (true) + * * @return mixed */ function get_group_members($group_guid, $limit = 10, $offset = 0, $site_guid = 0, $count = false) { @@ -470,7 +508,8 @@ function get_group_members($group_guid, $limit = 10, $offset = 0, $site_guid = 0 * Return whether a given user is a member of the group or not. * * @param int $group_guid The group ID - * @param int $user_guid The user guid + * @param int $user_guid The user guid + * * @return bool */ function is_group_member($group_guid, $user_guid) { @@ -486,11 +525,16 @@ function is_group_member($group_guid, $user_guid) { * Join a user to a group. * * @param int $group_guid The group. - * @param int $user_guid The user. + * @param int $user_guid The user. + * + * @return bool */ function join_group($group_guid, $user_guid) { $result = add_entity_relationship($user_guid, 'member', $group_guid); - trigger_elgg_event('join', 'group', array('group' => get_entity($group_guid), 'user' => get_entity($user_guid))); + + $param = array('group' => get_entity($group_guid), 'user' => get_entity($user_guid)); + trigger_elgg_event('join', 'group', $params); + return $result; } @@ -498,11 +542,15 @@ function join_group($group_guid, $user_guid) { * Remove a user from a group. * * @param int $group_guid The group. - * @param int $user_guid The user. + * @param int $user_guid The user. + * + * @return bool */ function leave_group($group_guid, $user_guid) { // event needs to be triggered while user is still member of group to have access to group acl - trigger_elgg_event('leave', 'group', array('group' => get_entity($group_guid), 'user' => get_entity($user_guid))); + $params = array('group' => get_entity($group_guid), 'user' => get_entity($user_guid)); + + trigger_elgg_event('leave', 'group', $params); $result = remove_entity_relationship($user_guid, 'member', $group_guid); return $result; } @@ -510,16 +558,25 @@ function leave_group($group_guid, $user_guid) { /** * Return all groups a user is a member of. * - * @param unknown_type $user_guid + * @param int $user_guid GUID of user + * + * @return array|false */ function get_users_membership($user_guid) { - return elgg_get_entities_from_relationship(array('relationship' => 'member', 'relationship_guid' => $user_guid, 'inverse_relationship' => FALSE)); + $options = array( + 'relationship' => 'member', + 'relationship_guid' => $user_guid, + 'inverse_relationship' => FALSE + ); + return elgg_get_entities_from_relationship($options); } /** * Checks access to a group. * - * @param boolean $forward If set to true (default), will forward the page; if set to false, will return true or false. + * @param boolean $forward If set to true (default), will forward the page; + * if set to false, will return true or false. + * * @return true|false If $forward is set to false. */ function group_gatekeeper($forward = true) { @@ -555,12 +612,13 @@ function group_gatekeeper($forward = true) { /** * Manages group tool options * - * @param string $name Name of the group tool option - * @param string $label Used for the group edit form + * @param string $name Name of the group tool option + * @param string $label Used for the group edit form * @param boolean $default_on True if this option should be active by default * + * @return void */ -function add_group_tool_option($name,$label,$default_on=true) { +function add_group_tool_option($name, $label, $default_on = true) { global $CONFIG; if (!isset($CONFIG->group_tool_options)) { @@ -579,11 +637,13 @@ function add_group_tool_option($name,$label,$default_on=true) { /** * Searches for a group based on a complete or partial name or description * - * @param string $criteria The partial or full name or description - * @param int $limit Limit of the search. - * @param int $offset Offset. - * @param string $order_by The order. - * @param boolean $count Whether to return the count of results or just the results. + * @param string $criteria The partial or full name or description + * @param int $limit Limit of the search. + * @param int $offset Offset. + * @param string $order_by The order. + * @param boolean $count Whether to return the count of results or just the results. + * + * @return mixed * @deprecated 1.7 */ function search_for_group($criteria, $limit = 10, $offset = 0, $order_by = "", $count = false) { @@ -606,8 +666,9 @@ function search_for_group($criteria, $limit = 10, $offset = 0, $order_by = "", $ } else { $query = "SELECT e.* "; } - $query .= "from {$CONFIG->dbprefix}entities e join {$CONFIG->dbprefix}groups_entity g on e.guid=g.guid where "; - // $query .= " match(u.name,u.username) against ('$criteria') "; + $query .= "from {$CONFIG->dbprefix}entities e" + . " JOIN {$CONFIG->dbprefix}groups_entity g on e.guid=g.guid where "; + $query .= "(g.name like \"%{$criteria}%\" or g.description like \"%{$criteria}%\")"; $query .= " and $access"; @@ -624,7 +685,15 @@ function search_for_group($criteria, $limit = 10, $offset = 0, $order_by = "", $ /** * Returns a formatted list of groups suitable for injecting into search. + * * @deprecated 1.7 + * + * @param string $hook Hook name + * @param string $user User + * @param mixed $returnvalue Previous hook's return value + * @param string $tag Tag to search on + * + * @return string */ function search_list_groups_by_name($hook, $user, $returnvalue, $tag) { elgg_deprecated_notice('search_list_groups_by_name() was deprecated by new search plugin', 1.7); @@ -634,14 +703,15 @@ function search_list_groups_by_name($hook, $user, $returnvalue, $tag) { $object = get_input('object'); if (!get_input('offset') && (empty($object) || $object == 'group')) { - if ($groups = search_for_group($tag,$threshold)) { - $countgroups = search_for_group($tag,0,0,"",true); + if ($groups = search_for_group($tag, $threshold)) { + $countgroups = search_for_group($tag, 0, 0, "", true); - $return = elgg_view('group/search/startblurb',array('count' => $countgroups, 'tag' => $tag)); - foreach($groups as $group) { + $return = elgg_view('group/search/startblurb', array('count' => $countgroups, 'tag' => $tag)); + foreach ($groups as $group) { $return .= elgg_view_entity($group); } - $return .= elgg_view('group/search/finishblurb',array('count' => $countgroups, 'threshold' => $threshold, 'tag' => $tag)); + $vars = array('count' => $countgroups, 'threshold' => $threshold, 'tag' => $tag); + $return .= elgg_view('group/search/finishblurb', $vars); return $return; } } @@ -652,8 +722,9 @@ function search_list_groups_by_name($hook, $user, $returnvalue, $tag) { * * @see elgg_view_entity_list * - * @param string $tag Search criteria - * @param int $limit The number of entities to display on a page + * @param string $tag Search criteria + * @param int $limit The number of entities to display on a page + * * @return string The list in a form suitable to display * @deprecated 1.7 */ @@ -671,10 +742,11 @@ function list_group_search($tag, $limit = 10) { /** * Performs initialisation functions for groups * + * @return void */ function group_init() { // Register an entity type - register_entity_type('group',''); + register_entity_type('group', ''); } -register_elgg_event_handler('init','system','group_init'); +register_elgg_event_handler('init', 'system', 'group_init'); diff --git a/engine/lib/input.php b/engine/lib/input.php index 9316b51f8..4ba6f500c 100644 --- a/engine/lib/input.php +++ b/engine/lib/input.php @@ -3,8 +3,8 @@ * Parameter input functions. * This file contains functions for getting input from get/post variables. * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage Input */ /** @@ -13,9 +13,11 @@ * Note: this function does not handle nested arrays (ex: form input of param[m][n]) * because of the filtering done in htmlawed from the filter_tags call. * - * @param $variable string The variable we want to return. - * @param $default mixed A default value for the variable if it is not found. - * @param $filter_result If true then the result is filtered for bad tags. + * @param string $variable The variable we want to return. + * @param mixed $default A default value for the variable if it is not found. + * @param bool $filter_result If true then the result is filtered for bad tags. + * + * @return string */ function get_input($variable, $default = NULL, $filter_result = TRUE) { @@ -54,7 +56,9 @@ function get_input($variable, $default = NULL, $filter_result = TRUE) { * Note: this function does not handle nested arrays (ex: form input of param[m][n]) * * @param string $variable The name of the variable - * @param string $value The value of the variable + * @param string $value The value of the variable + * + * @return void */ function set_input($variable, $value) { global $CONFIG; @@ -74,7 +78,8 @@ function set_input($variable, $value) { * Filter tags from a given string based on registered hooks. * * @param mixed $var Anything that does not include an object (strings, ints, arrays) - * This includes multi-dimensional arrays. + * This includes multi-dimensional arrays. + * * @return mixed The filtered result - everything will be strings */ function filter_tags($var) { @@ -85,6 +90,7 @@ function filter_tags($var) { * Validates an email address. * * @param string $address Email address. + * * @return bool */ function is_email_address($address) { @@ -94,7 +100,8 @@ function is_email_address($address) { /** * Page handler for autocomplete endpoint. * - * @param $page + * @param array $page Pages array + * * @return unknown_type */ function input_livesearch_page_handler($page) { @@ -139,7 +146,8 @@ function input_livesearch_page_handler($page) { case 'all': // only need to pull up title from objects. - if (!$entities = elgg_get_entities(array('owner_guid' => $owner_guid, 'limit' => $limit)) AND is_array($entities)) { + $options = array('owner_guid' => $owner_guid, 'limit' => $limit); + if (!$entities = elgg_get_entities($options) AND is_array($entities)) { $results = array_merge($results, $entities); } break; @@ -159,10 +167,11 @@ function input_livesearch_page_handler($page) { 'type' => 'user', 'name' => $entity->name, 'desc' => $entity->username, - 'icon' => '<img class="livesearch_icon" src="' . get_entity($entity->guid)->getIcon('tiny') . '" />', + 'icon' => '<img class="livesearch_icon" src="' . + get_entity($entity->guid)->getIcon('tiny') . '" />', 'guid' => $entity->guid )); - $results[$entity->name . rand(1,100)] = $json; + $results[$entity->name . rand(1, 100)] = $json; } } break; @@ -185,18 +194,22 @@ function input_livesearch_page_handler($page) { 'type' => 'group', 'name' => $entity->name, 'desc' => strip_tags($entity->description), - 'icon' => '<img class="livesearch_icon" src="' . get_entity($entity->guid)->getIcon('tiny') . '" />', + 'icon' => '<img class="livesearch_icon" src="' + . get_entity($entity->guid)->getIcon('tiny') . '" />', 'guid' => $entity->guid )); - //$results[$entity->name . rand(1,100)] = "$json|{$entity->guid}"; - $results[$entity->name . rand(1,100)] = $json; + + $results[$entity->name . rand(1, 100)] = $json; } } break; case 'friends': $access = get_access_sql_suffix(); - $query = "SELECT * FROM {$CONFIG->dbprefix}users_entity as ue, {$CONFIG->dbprefix}entity_relationships as er, {$CONFIG->dbprefix}entities as e + $query = "SELECT * FROM + {$CONFIG->dbprefix}users_entity as ue, + {$CONFIG->dbprefix}entity_relationships as er, + {$CONFIG->dbprefix}entities as e WHERE er.relationship = 'friend' AND er.guid_one = {$user->getGUID()} AND er.guid_two = ue.guid @@ -213,10 +226,11 @@ function input_livesearch_page_handler($page) { 'type' => 'user', 'name' => $entity->name, 'desc' => $entity->username, - 'icon' => '<img class="livesearch_icon" src="' . get_entity($entity->guid)->getIcon('tiny') . '" />', + 'icon' => '<img class="livesearch_icon" src="' + . get_entity($entity->guid)->getIcon('tiny') . '" />', 'guid' => $entity->guid )); - $results[$entity->name . rand(1,100)] = $json; + $results[$entity->name . rand(1, 100)] = $json; } } break; @@ -235,12 +249,24 @@ function input_livesearch_page_handler($page) { exit; } +/** + * Register input functions and sanitize input + * + * @return void + */ function input_init() { // register an endpoint for live search / autocomplete. register_page_handler('livesearch', 'input_livesearch_page_handler'); - if (ini_get_bool('magic_quotes_gpc') ) { - //do keys as well, cos array_map ignores them + if (ini_get_bool('magic_quotes_gpc')) { + + /** + * do keys as well, cos array_map ignores them + * + * @param array $array Array of values + * + * @return array Sanitized array + */ function stripslashes_arraykeys($array) { if (is_array($array)) { $array2 = array(); @@ -257,6 +283,13 @@ function input_init() { } } + /** + * Strip slashes on everything + * + * @param mixed $value The value to remove slashes from + * + * @return mixed + */ function stripslashes_deep($value) { if (is_array($value)) { $value = stripslashes_arraykeys($value); @@ -297,4 +330,4 @@ function input_init() { } } -register_elgg_event_handler('init','system','input_init'); +register_elgg_event_handler('init', 'system', 'input_init'); diff --git a/engine/lib/install.php b/engine/lib/install.php index 470f71d84..c47eedd40 100644 --- a/engine/lib/install.php +++ b/engine/lib/install.php @@ -4,8 +4,8 @@ * Elgg installation * Various functions to assist with installing and upgrading the system * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage Installation */ /** @@ -45,6 +45,12 @@ function is_installed() { return datalist_get('installed'); } +/** + * Check that installation has completed and the database is populated. + * + * @throws InstallationException + * @return void + */ function verify_installation() { $installed = FALSE; try { diff --git a/engine/lib/languages.php b/engine/lib/languages.php index 5dd98e893..3472d0d29 100644 --- a/engine/lib/languages.php +++ b/engine/lib/languages.php @@ -3,8 +3,8 @@ * Elgg language module * Functions to manage language and translations. * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage Languages */ /** @@ -15,8 +15,9 @@ * $english = array('message1' => 'message1', 'message2' => 'message2'); * $german = array('message1' => 'Nachricht1','message2' => 'Nachricht2'); * - * @param string $country_code Standard country code (eg 'en', 'nl', 'es') - * @param array $language_array Formatted array of strings + * @param string $country_code Standard country code (eg 'en', 'nl', 'es') + * @param array $language_array Formatted array of strings + * * @return true|false Depending on success */ function add_translation($country_code, $language_array) { @@ -85,7 +86,9 @@ function get_language() { * Given a message shortcode, returns an appropriately translated full-text string * * @param string $message_key The short message code - * @param string $language Optionally, the standard language code (defaults to site/user default, then English) + * @param string $language Optionally, the standard language code + * (defaults to site/user default, then English) + * * @return string Either the translated string or the original English string */ function elgg_echo($message_key, $language = "") { @@ -111,14 +114,19 @@ function elgg_echo($message_key, $language = "") { /** * When given a full path, finds translation files and loads them * - * @param string $path Full path - * @param bool $load_all If true all languages are loaded, if false only the current language + en are loaded + * @param string $path Full path + * @param bool $load_all If true all languages are loaded, if + * false only the current language + en are loaded + * + * @return void */ function register_translations($path, $load_all = false) { global $CONFIG; // Make a note of this path just incase we need to register this language later - if(!isset($CONFIG->language_paths)) $CONFIG->language_paths = array(); + if (!isset($CONFIG->language_paths)) { + $CONFIG->language_paths = array(); + } $CONFIG->language_paths[$path] = true; // Get the current language based on site defaults and user preference @@ -128,8 +136,8 @@ function register_translations($path, $load_all = false) { if ($handle = opendir($path)) { while ($language = readdir($handle)) { if ( - ((in_array($language, array('en.php', $current_language . '.php'))) /*&& (!is_dir($path . $language))*/) || - (($load_all) && (strpos($language, '.php')!==false)/* && (!is_dir($path . $language))*/) + ((in_array($language, array('en.php', $current_language . '.php'))) ) || + (($load_all) && (strpos($language, '.php') !== false)) ) { include_once($path . $language); } @@ -165,7 +173,10 @@ function reload_all_translations() { } /** - * Return an array of installed translations as an associative array "two letter code" => "native language name". + * Return an array of installed translations as an associative + * array "two letter code" => "native language name". + * + * @return array */ function get_installed_translations() { global $CONFIG; @@ -190,6 +201,10 @@ function get_installed_translations() { /** * Return the level of completeness for a given language code (compared to english) + * + * @param string $language Language + * + * @return int */ function get_language_completeness($language) { global $CONFIG; @@ -215,7 +230,12 @@ function get_language_completeness($language) { } /** - * Return the translation keys missing from a given language, or those that are identical to the english version. + * Return the translation keys missing from a given language, + * or those that are identical to the english version. + * + * @param string $language The language + * + * @return mixed */ function get_missing_language_keys($language) { global $CONFIG; @@ -239,4 +259,4 @@ function get_missing_language_keys($language) { return false; } -register_translations(dirname(dirname(dirname(__FILE__))) . "/languages/"); +register_translations(dirname(dirname(dirname(__FILE__))) . "/languages/");
\ No newline at end of file diff --git a/engine/lib/location.php b/engine/lib/location.php index 73f3c4dbd..f3aae709b 100644 --- a/engine/lib/location.php +++ b/engine/lib/location.php @@ -9,15 +9,19 @@ /** * Encode a location into a latitude and longitude, caching the result. * - * Works by triggering the 'geocode' 'location' plugin hook, and requires a geocoding module to be installed + * Works by triggering the 'geocode' 'location' plugin + * hook, and requires a geocoding module to be installed * activated in order to work. * * @param String $location The location, e.g. "London", or "24 Foobar Street, Gotham City" + * + * @return string */ function elgg_geocode_location($location) { global $CONFIG; - // Handle cases where we are passed an array (shouldn't be but can happen if location is a tag field) + // Handle cases where we are passed an array (shouldn't be + // but can happen if location is a tag field) if (is_array($location)) { $location = implode(', ', $location); } @@ -25,7 +29,8 @@ function elgg_geocode_location($location) { $location = sanitise_string($location); // Look for cached version - $cached_location = get_data_row("SELECT * from {$CONFIG->dbprefix}geocode_cache WHERE location='$location'"); + $query = "SELECT * from {$CONFIG->dbprefix}geocode_cache WHERE location='$location'"; + $cached_location = get_data_row($query); if ($cached_location) { return array('lat' => $cached_location->lat, 'long' => $cached_location->long); @@ -41,7 +46,10 @@ function elgg_geocode_location($location) { $long = (float)$return['long']; // Put into cache at the end of the page since we don't really care that much - execute_delayed_write_query("INSERT DELAYED INTO {$CONFIG->dbprefix}geocode_cache (location, lat, `long`) VALUES ('$location', '{$lat}', '{$long}') ON DUPLICATE KEY UPDATE lat='{$lat}', `long`='{$long}'"); + $query = "INSERT DELAYED INTO {$CONFIG->dbprefix}geocode_cache " + . " (location, lat, `long`) VALUES ('$location', '{$lat}', '{$long}')" + . " ON DUPLICATE KEY UPDATE lat='{$lat}', `long`='{$long}'"; + execute_delayed_write_query($query); } return $return; @@ -50,30 +58,33 @@ function elgg_geocode_location($location) { /** * Return entities within a given geographic area. * - * @param real $lat Latitude - * @param real $long Longitude - * @param real $radius The radius - * @param string $type The type of entity (eg "user", "object" etc) - * @param string $subtype The arbitrary subtype of the entity - * @param int $owner_guid The GUID of the owning user - * @param string $order_by The field to order by; by default, time_created desc - * @param int $limit The number of entities to return; 10 by default - * @param int $offset The indexing offset, 0 by default - * @param boolean $count Set to true to get a count rather than the entities themselves (limits and offsets don't apply in this context). Defaults to false. - * @param int $site_guid The site to get entities for. Leave as 0 (default) for the current site; -1 for all sites. - * @param int|array $container_guid The container or containers to get entities from (default: all containers). + * @param float $lat Latitude + * @param float $long Longitude + * @param float $radius The radius + * @param string $type The type of entity (eg "user", "object" etc) + * @param string $subtype The arbitrary subtype of the entity + * @param int $owner_guid The GUID of the owning user + * @param string $order_by The field to order by; by default, time_created desc + * @param int $limit The number of entities to return; 10 by default + * @param int $offset The indexing offset, 0 by default + * @param boolean $count Count entities + * @param int $site_guid Site GUID. 0 for current, -1 for any + * @param int|array $container_guid Container GUID + * * @return array A list of entities. */ -function get_entities_in_area($lat, $long, $radius, $type = "", $subtype = "", $owner_guid = 0, $order_by = "", $limit = 10, $offset = 0, $count = false, $site_guid = 0, $container_guid) { +function get_entities_in_area($lat, $long, $radius, $type = "", $subtype = "", $owner_guid = 0, +$order_by = "", $limit = 10, $offset = 0, $count = false, $site_guid = 0, $container_guid) { + global $CONFIG; if ($subtype === false || $subtype === null || $subtype === 0) { return false; } - $lat = (real)$lat; - $long = (real)$long; - $radius = (real)$radius; + $lat = (float)$lat; + $long = (float)$long; + $radius = (float)$radius; $order_by = sanitise_string($order_by); $limit = (int)$limit; @@ -88,15 +99,18 @@ function get_entities_in_area($lat, $long, $radius, $type = "", $subtype = "", $ if (is_array($type)) { $tempwhere = ""; if (sizeof($type)) { - foreach($type as $typekey => $subtypearray) { - foreach($subtypearray as $subtypeval) { + foreach ($type as $typekey => $subtypearray) { + foreach ($subtypearray as $subtypeval) { $typekey = sanitise_string($typekey); if (!empty($subtypeval)) { $subtypeval = (int) get_subtype_id($typekey, $subtypeval); } else { $subtypeval = 0; } - if (!empty($tempwhere)) $tempwhere .= " or "; + if (!empty($tempwhere)) { + $tempwhere .= " or "; + } + $tempwhere .= "(e.type = '{$typekey}' and e.subtype = {$subtypeval})"; } } @@ -112,7 +126,7 @@ function get_entities_in_area($lat, $long, $radius, $type = "", $subtype = "", $ $where[] = "e.type='$type'"; } - if ($subtype!=="") { + if ($subtype !== "") { $where[] = "e.subtype=$subtype"; } } @@ -125,7 +139,7 @@ function get_entities_in_area($lat, $long, $radius, $type = "", $subtype = "", $ } else if (sizeof($owner_guid) > 0) { $owner_array = array_map('sanitise_int', $owner_guid); // Cast every element to the owner_guid array to int - $owner_guid = implode(",",$owner_guid); // + $owner_guid = implode(",", $owner_guid); // $where[] = "e.owner_guid in ({$owner_guid})" ; // } if (is_null($container_guid)) { @@ -139,8 +153,10 @@ function get_entities_in_area($lat, $long, $radius, $type = "", $subtype = "", $ if (!is_null($container_guid)) { if (is_array($container_guid)) { - foreach($container_guid as $key => $val) $container_guid[$key] = (int) $val; - $where[] = "e.container_guid in (" . implode(",",$container_guid) . ")"; + foreach ($container_guid as $key => $val) { + $container_guid[$key] = (int) $val; + } + $where[] = "e.container_guid in (" . implode(",", $container_guid) . ")"; } else { $container_guid = (int) $container_guid; $where[] = "e.container_guid = {$container_guid}"; @@ -198,42 +214,51 @@ function get_entities_in_area($lat, $long, $radius, $type = "", $subtype = "", $ /** * List entities in a given location * - * @param string $location Location - * @param string $type The type of entity (eg "user", "object" etc) - * @param string $subtype The arbitrary subtype of the entity - * @param int $owner_guid The GUID of the owning user - * @param int $limit The number of entities to display per page (default: 10) - * @param true|false $fullview Whether or not to display the full view (default: true) - * @param true|false $viewtypetoggle Whether or not to allow gallery view - * @param true|false $pagination Display pagination? Default: true + * @param string $location Location + * @param string $type The type of entity (eg "user", "object" etc) + * @param string $subtype The arbitrary subtype of the entity + * @param int $owner_guid The GUID of the owning user + * @param int $limit The number of entities to display per page (default: 10) + * @param bool $fullview Whether or not to display the full view (default: true) + * @param bool $viewtypetoggle Whether or not to allow gallery view + * @param bool $navigation Display pagination? Default: true + * * @return string A viewable list of entities */ -function list_entities_location($location, $type= "", $subtype = "", $owner_guid = 0, $limit = 10, $fullview = true, $viewtypetoggle = false, $navigation = true) { - return list_entities_from_metadata('location', $location, $type, $subtype, $owner_guid, $limit, $fullview, $viewtypetoggle, $navigation); +function list_entities_location($location, $type= "", $subtype = "", $owner_guid = 0, $limit = 10, +$fullview = true, $viewtypetoggle = false, $navigation = true) { + + return list_entities_from_metadata('location', $location, $type, $subtype, $owner_guid, $limit, + $fullview, $viewtypetoggle, $navigation); } /** * List items within a given geographic area. * - * @param real $lat Latitude - * @param real $long Longitude - * @param real $radius The radius - * @param string $type The type of entity (eg "user", "object" etc) - * @param string $subtype The arbitrary subtype of the entity - * @param int $owner_guid The GUID of the owning user - * @param int $limit The number of entities to display per page (default: 10) - * @param true|false $fullview Whether or not to display the full view (default: true) - * @param true|false $viewtypetoggle Whether or not to allow gallery view - * @param true|false $pagination Display pagination? Default: true + * @param real $lat Latitude + * @param real $long Longitude + * @param real $radius The radius + * @param string $type The type of entity (eg "user", "object" etc) + * @param string $subtype The arbitrary subtype of the entity + * @param int $owner_guid The GUID of the owning user + * @param int $limit The number of entities to display per page (default: 10) + * @param bool $fullview Whether or not to display the full view (default: true) + * @param bool $viewtypetoggle Whether or not to allow gallery view + * @param bool $navigation Display pagination? Default: true + * * @return string A viewable list of entities */ -function list_entities_in_area($lat, $long, $radius, $type= "", $subtype = "", $owner_guid = 0, $limit = 10, $fullview = true, $viewtypetoggle = false, $navigation = true) { +function list_entities_in_area($lat, $long, $radius, $type= "", $subtype = "", $owner_guid = 0, +$limit = 10, $fullview = true, $viewtypetoggle = false, $navigation = true) { $offset = (int) get_input('offset'); - $count = get_entities_in_area($lat, $long, $radius, $type, $subtype, $owner_guid, "", $limit, $offset, true); - $entities = get_entities_in_area($lat, $long, $radius, $type, $subtype, $owner_guid, "", $limit, $offset); + $count = get_entities_in_area($lat, $long, $radius, $type, $subtype, $owner_guid, + "", $limit, $offset, true); + $entities = get_entities_in_area($lat, $long, $radius, $type, $subtype, $owner_guid, + "", $limit, $offset); - return elgg_view_entity_list($entities, $count, $offset, $limit, $fullview, $viewtypetoggle, $navigation); + return elgg_view_entity_list($entities, $count, $offset, $limit, $fullview, + $viewtypetoggle, $navigation); } // Some distances in degrees (approximate) diff --git a/engine/lib/memcache.php b/engine/lib/memcache.php index df65adc8a..6e905b0d4 100644 --- a/engine/lib/memcache.php +++ b/engine/lib/memcache.php @@ -4,8 +4,8 @@ * * Requires php5-memcache to work. * - * @package Elgg - * @subpackage API + * @package Elgg.Core + * @subpackage Cache.Memcache */ /** @@ -23,7 +23,7 @@ function is_memcache_available() { } // If we haven't set variable to something - if (($memcache_available!==true) && ($memcache_available!==false)) { + if (($memcache_available !== true) && ($memcache_available !== false)) { try { $tmp = new ElggMemcache(); // No exception thrown so we have memcache available diff --git a/engine/lib/metadata.php b/engine/lib/metadata.php index 37a00e6a2..b0117bfd0 100644 --- a/engine/lib/metadata.php +++ b/engine/lib/metadata.php @@ -3,14 +3,15 @@ * Elgg metadata * Functions to manage object metadata. * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage DataModel.Metadata */ /** * Convert a database row to a new ElggMetadata * - * @param stdClass $row + * @param stdClass $row An object from the database + * * @return stdClass or ElggMetadata */ function row_to_elggmetadata($row) { @@ -24,7 +25,9 @@ function row_to_elggmetadata($row) { /** * Get a specific item of metadata. * - * @param $id int The item of metadata being retrieved. + * @param int $id The item of metadata being retrieved. + * + * @return mixed */ function get_metadata($id) { global $CONFIG; @@ -33,16 +36,24 @@ function get_metadata($id) { $access = get_access_sql_suffix("e"); $md_access = get_access_sql_suffix("m"); - return row_to_elggmetadata(get_data_row("SELECT m.*, n.string as name, v.string as value from {$CONFIG->dbprefix}metadata m JOIN {$CONFIG->dbprefix}entities e on e.guid = m.entity_guid JOIN {$CONFIG->dbprefix}metastrings v on m.value_id = v.id JOIN {$CONFIG->dbprefix}metastrings n on m.name_id = n.id where m.id=$id and $access and $md_access")); + $query = "SELECT m.*, n.string as name, v.string as value from {$CONFIG->dbprefix}metadata m" + . " JOIN {$CONFIG->dbprefix}entities e on e.guid = m.entity_guid" + . " JOIN {$CONFIG->dbprefix}metastrings v on m.value_id = v.id" + . " JOIN {$CONFIG->dbprefix}metastrings n on m.name_id = n.id" + . " where m.id=$id and $access and $md_access"; + + + return row_to_elggmetadata(get_data_row($query)); } /** * Removes metadata on an entity with a particular name, optionally with a given value. * - * @param int $entity_guid The entity GUID - * @param string $name The name of the metadata - * @param string $value The optional value of the item (useful for removing a single item in a multiple set) - * @return true|false Depending on success + * @param int $entity_guid The entity GUID + * @param string $name The name of the metadata + * @param string $value The value of the item (useful to remove a single item of a set) + * + * @return bool Depending on success */ function remove_metadata($entity_guid, $name, $value = "") { global $CONFIG; @@ -50,13 +61,15 @@ function remove_metadata($entity_guid, $name, $value = "") { $name = sanitise_string($name); $value = sanitise_string($value); - $query = "SELECT * from {$CONFIG->dbprefix}metadata WHERE entity_guid = $entity_guid and name_id=" . add_metastring($name); - if ($value!="") { + $query = "SELECT * from {$CONFIG->dbprefix}metadata" + . " WHERE entity_guid = $entity_guid and name_id=" . add_metastring($name); + + if ($value != "") { $query .= " and value_id=" . add_metastring($value); } if ($existing = get_data($query)) { - foreach($existing as $ex) { + foreach ($existing as $ex) { delete_metadata($ex->id); } return true; @@ -71,16 +84,19 @@ function remove_metadata($entity_guid, $name, $value = "") { * Metadata can be an array by setting allow_multiple to TRUE, but it is an * indexed array with no control over the indexing. * - * @param int $entity_guid The entity to attach the metadata to - * @param string $name Name of the metadata - * @param string $value Value of the metadata - * @param string $value_type 'text', 'integer', or '' for automatic detection - * @param int $owner_guid GUID of entity that owns the metadata - * @param int $access_id Default is ACCESS_PRIVATE - * @param bool $allow_multiple Allow multiple values for one key. Default is FALSE + * @param int $entity_guid The entity to attach the metadata to + * @param string $name Name of the metadata + * @param string $value Value of the metadata + * @param string $value_type 'text', 'integer', or '' for automatic detection + * @param int $owner_guid GUID of entity that owns the metadata + * @param int $access_id Default is ACCESS_PRIVATE + * @param bool $allow_multiple Allow multiple values for one key. Default is FALSE + * * @return int/bool id of metadata or FALSE if failure */ -function create_metadata($entity_guid, $name, $value, $value_type, $owner_guid, $access_id = ACCESS_PRIVATE, $allow_multiple = false) { +function create_metadata($entity_guid, $name, $value, $value_type, $owner_guid, + $access_id = ACCESS_PRIVATE, $allow_multiple = false) { + global $CONFIG; $entity_guid = (int)$entity_guid; @@ -96,7 +112,7 @@ function create_metadata($entity_guid, $name, $value, $value_type, $owner_guid, return FALSE; } - if ($owner_guid==0) { + if ($owner_guid == 0) { $owner_guid = get_loggedin_userid(); } @@ -104,7 +120,10 @@ function create_metadata($entity_guid, $name, $value, $value_type, $owner_guid, $id = false; - $existing = get_data_row("SELECT * from {$CONFIG->dbprefix}metadata WHERE entity_guid = $entity_guid and name_id=" . add_metastring($name) . " limit 1"); + $query = "SELECT * from {$CONFIG->dbprefix}metadata" + . " WHERE entity_guid = $entity_guid and name_id=" . add_metastring($name) . " limit 1"; + + $existing = get_data_row($query); if ($existing && !$allow_multiple) { $id = (int)$existing->id; $result = update_metadata($id, $name, $value, $value_type, $owner_guid, $access_id); @@ -134,7 +153,11 @@ function create_metadata($entity_guid, $name, $value, $value_type, $owner_guid, } // If ok then add it - $id = insert_data("INSERT into {$CONFIG->dbprefix}metadata (entity_guid, name_id, value_id, value_type, owner_guid, time_created, access_id) VALUES ($entity_guid, '$name','$value','$value_type', $owner_guid, $time, $access_id)"); + $query = "INSERT into {$CONFIG->dbprefix}metadata" + . " (entity_guid, name_id, value_id, value_type, owner_guid, time_created, access_id)" + . " VALUES ($entity_guid, '$name','$value','$value_type', $owner_guid, $time, $access_id)"; + + $id = insert_data($query); if ($id !== false) { $obj = get_metadata($id); @@ -152,12 +175,14 @@ function create_metadata($entity_guid, $name, $value, $value_type, $owner_guid, /** * Update an item of metadata. * - * @param int $id - * @param string $name - * @param string $value - * @param string $value_type - * @param int $owner_guid - * @param int $access_id + * @param int $id Metadata id + * @param string $name Metadata name + * @param string $value Metadata value + * @param string $value_type Value type + * @param int $owner_guid Owner guid + * @param int $access_id Access ID + * + * @return bool */ function update_metadata($id, $name, $value, $value_type, $owner_guid, $access_id) { global $CONFIG; @@ -181,12 +206,10 @@ function update_metadata($id, $name, $value, $value_type, $owner_guid, $access_i $metabyname_memcache->delete("{$md->entity_guid}:{$md->name_id}"); } - //$name = sanitise_string(trim($name)); - //$value = sanitise_string(trim($value)); $value_type = detect_extender_valuetype($value, sanitise_string(trim($value_type))); $owner_guid = (int)$owner_guid; - if ($owner_guid==0) { + if ($owner_guid == 0) { $owner_guid = get_loggedin_userid(); } @@ -215,8 +238,12 @@ function update_metadata($id, $name, $value, $value_type, $owner_guid, $access_i } // If ok then add it - $result = update_data("UPDATE {$CONFIG->dbprefix}metadata set value_id='$value', value_type='$value_type', access_id=$access_id, owner_guid=$owner_guid where id=$id and name_id='$name'"); - if ($result!==false) { + $query = "UPDATE {$CONFIG->dbprefix}metadata" + . " set value_id='$value', value_type='$value_type', access_id=$access_id," + . " owner_guid=$owner_guid where id=$id and name_id='$name'"; + + $result = update_data($query); + if ($result !== false) { $obj = get_metadata($id); if (trigger_elgg_event('update', 'metadata', $obj)) { return true; @@ -235,16 +262,22 @@ function update_metadata($id, $name, $value, $value_type, $owner_guid, $access_i * allow_multiple set to TRUE. This creates an indexed array. It does not support * associative arrays and there is no guarantee on the ordering in the array. * - * @param int $entity_guid The entity to attach the metadata to + * @param int $entity_guid The entity to attach the metadata to * @param string $name_and_values Associative array - a value can be a string, number, bool - * @param string $value_type 'text', 'integer', or '' for automatic detection - * @param int $owner_guid GUID of entity that owns the metadata - * @param int $access_id Default is ACCESS_PRIVATE - * @param bool $allow_multiple Allow multiple values for one key. Default is FALSE + * @param string $value_type 'text', 'integer', or '' for automatic detection + * @param int $owner_guid GUID of entity that owns the metadata + * @param int $access_id Default is ACCESS_PRIVATE + * @param bool $allow_multiple Allow multiple values for one key. Default is FALSE + * + * @return bool */ -function create_metadata_from_array($entity_guid, array $name_and_values, $value_type, $owner_guid, $access_id = ACCESS_PRIVATE, $allow_multiple = false) { +function create_metadata_from_array($entity_guid, array $name_and_values, $value_type, $owner_guid, +$access_id = ACCESS_PRIVATE, $allow_multiple = false) { + foreach ($name_and_values as $k => $v) { - if (!create_metadata($entity_guid, $k, $v, $value_type, $owner_guid, $access_id, $allow_multiple)) { + $result = create_metadata($entity_guid, $k, $v, $value_type, $owner_guid, + $access_id, $allow_multiple); + if (!$result) { return false; } } @@ -254,7 +287,9 @@ function create_metadata_from_array($entity_guid, array $name_and_values, $value /** * Delete an item of metadata, where the current user has access. * - * @param $id int The item of metadata to delete. + * @param int $id The item of metadata to delete. + * + * @return bool */ function delete_metadata($id) { global $CONFIG; @@ -284,10 +319,12 @@ function delete_metadata($id) { /** * Return the metadata values that match your query. * - * @param string $meta_name + * @param int $entity_guid Entity GUID + * @param string $meta_name Metadata name + * * @return mixed either a value, an array of ElggMetadata or false. */ -function get_metadata_byname($entity_guid, $meta_name) { +function get_metadata_byname($entity_guid, $meta_name) { global $CONFIG; $meta_name = get_metastring_id($meta_name); @@ -300,7 +337,8 @@ function get_metadata_byname($entity_guid, $meta_name) { $access = get_access_sql_suffix("e"); $md_access = get_access_sql_suffix("m"); - // If memcache is available then cache this (cache only by name for now since this is the most common query) + // If memcache is available then cache this (cache only by name for now + // since this is the most common query) $meta = null; static $metabyname_memcache; if ((!$metabyname_memcache) && (is_memcache_available())) { @@ -313,7 +351,16 @@ function get_metadata_byname($entity_guid, $meta_name) { return $meta; } - $result = get_data("SELECT m.*, n.string as name, v.string as value from {$CONFIG->dbprefix}metadata m JOIN {$CONFIG->dbprefix}entities e ON e.guid = m.entity_guid JOIN {$CONFIG->dbprefix}metastrings v on m.value_id = v.id JOIN {$CONFIG->dbprefix}metastrings n on m.name_id = n.id where m.entity_guid=$entity_guid and m.name_id='$meta_name' and $access and $md_access ORDER BY m.id ASC", "row_to_elggmetadata"); + $query = "SELECT m.*, n.string as name, v.string as value" + . " from {$CONFIG->dbprefix}metadata m" + . " JOIN {$CONFIG->dbprefix}entities e ON e.guid = m.entity_guid" + . " JOIN {$CONFIG->dbprefix}metastrings v on m.value_id = v.id" + . " JOIN {$CONFIG->dbprefix}metastrings n on m.name_id = n.id" + . " where m.entity_guid=$entity_guid and m.name_id='$meta_name'" + . " and $access and $md_access ORDER BY m.id ASC" ; + + $result = get_data($query, "row_to_elggmetadata"); + if (!$result) { return false; } @@ -341,7 +388,9 @@ function get_metadata_byname($entity_guid, $meta_name) { /** * Return all the metadata for a given GUID. * - * @param int $entity_guid + * @param int $entity_guid Entity GUID + * + * @return mixed */ function get_metadata_for_entity($entity_guid) { global $CONFIG; @@ -350,22 +399,32 @@ function get_metadata_for_entity($entity_guid) { $access = get_access_sql_suffix("e"); $md_access = get_access_sql_suffix("m"); - return get_data("SELECT m.*, n.string as name, v.string as value from {$CONFIG->dbprefix}metadata m JOIN {$CONFIG->dbprefix}entities e ON e.guid = m.entity_guid JOIN {$CONFIG->dbprefix}metastrings v on m.value_id = v.id JOIN {$CONFIG->dbprefix}metastrings n on m.name_id = n.id where m.entity_guid=$entity_guid and $access and $md_access", "row_to_elggmetadata"); + $query = "SELECT m.*, n.string as name, v.string as value + from {$CONFIG->dbprefix}metadata m + JOIN {$CONFIG->dbprefix}entities e ON e.guid = m.entity_guid + JOIN {$CONFIG->dbprefix}metastrings v on m.value_id = v.id + JOIN {$CONFIG->dbprefix}metastrings n on m.name_id = n.id + where m.entity_guid=$entity_guid and $access and $md_access"; + + return get_data($query, "row_to_elggmetadata"); } /** * Get the metadata where the entities they are referring to match a given criteria. * - * @param mixed $meta_name - * @param mixed $meta_value - * @param string $entity_type The type of entity to look for, eg 'site' or 'object' + * @param mixed $meta_name Metadata name + * @param mixed $meta_value Metadata value + * @param string $entity_type The type of entity to look for, eg 'site' or 'object' * @param string $entity_subtype The subtype of the entity. - * @param int $limit - * @param int $offset - * @param string $order_by Optional ordering. - * @param int $site_guid The site to get entities for. Leave as 0 (default) for the current site; -1 for all sites. + * @param int $limit Limit + * @param int $offset Offset + * @param string $order_by Optional ordering. + * @param int $site_guid Site GUID. 0 for current, -1 for any + * + * @return mixed */ -function find_metadata($meta_name = "", $meta_value = "", $entity_type = "", $entity_subtype = "", $limit = 10, $offset = 0, $order_by = "", $site_guid = 0) { +function find_metadata($meta_name = "", $meta_value = "", $entity_type = "", $entity_subtype = "", + $limit = 10, $offset = 0, $order_by = "", $site_guid = 0) { global $CONFIG; $meta_n = get_metastring_id($meta_name); @@ -387,7 +446,7 @@ function find_metadata($meta_name = "", $meta_value = "", $entity_type = "", $en $where = array(); - if ($entity_type!="") { + if ($entity_type != "") { $where[] = "e.type='$entity_type'"; } @@ -395,14 +454,14 @@ function find_metadata($meta_name = "", $meta_value = "", $entity_type = "", $en $where[] = "e.subtype=$entity_subtype"; } - if ($meta_name!="") { + if ($meta_name != "") { if (!$meta_v) { // The value is set, but we didn't get a value... so something went wrong. return false; } $where[] = "m.name_id='$meta_n'"; } - if ($meta_value!="") { + if ($meta_value != "") { // The value is set, but we didn't get a value... so something went wrong. if (!$meta_v) { return false; @@ -413,7 +472,11 @@ function find_metadata($meta_name = "", $meta_value = "", $entity_type = "", $en $where[] = "e.site_guid = {$site_guid}"; } - $query = "SELECT m.*, n.string as name, v.string as value from {$CONFIG->dbprefix}entities e JOIN {$CONFIG->dbprefix}metadata m on e.guid = m.entity_guid JOIN {$CONFIG->dbprefix}metastrings v on m.value_id = v.id JOIN {$CONFIG->dbprefix}metastrings n on m.name_id = n.id where"; + $query = "SELECT m.*, n.string as name, v.string as value from {$CONFIG->dbprefix}entities e + JOIN {$CONFIG->dbprefix}metadata m on e.guid = m.entity_guid + JOIN {$CONFIG->dbprefix}metastrings v on m.value_id = v.id + JOIN {$CONFIG->dbprefix}metastrings n on m.name_id = n.id where"; + foreach ($where as $w) { $query .= " $w and "; } @@ -438,21 +501,34 @@ function find_metadata($meta_name = "", $meta_value = "", $entity_type = "", $en * * @see elgg_get_entities * @see elgg_get_entities_from_annotations + * * @param array $options Array in format: * * metadata_names => NULL|ARR metadata names * * metadata_values => NULL|ARR metadata values * - * metadata_name_value_pairs => NULL|ARR (name => 'name', value => 'value', 'operand' => '=', 'case_sensitive' => TRUE) entries. - * Currently if multiple values are sent via an array (value => array('value1', 'value2') the pair's operand will be forced to "IN". + * metadata_name_value_pairs => NULL|ARR ( + * name => 'name', + * value => 'value', + * 'operand' => '=', + * 'case_sensitive' => TRUE + * ) + * Currently if multiple values are sent via + * an array (value => array('value1', 'value2') + * the pair's operand will be forced to "IN". * - * metadata_name_value_pairs_operator => NULL|STR The operator to use for combining (name = value) OPERATOR (name = value); default AND + * metadata_name_value_pairs_operator => NULL|STR The operator to use for combining + * (name = value) OPERATOR (name = value); default AND * * metadata_case_sensitive => BOOL Overall Case sensitive * - * order_by_metadata => NULL|ARR (array('name' => 'metadata_text1', 'direction' => ASC|DESC, 'as' => text|integer), - * Also supports array('name' => 'metadata_text1') + * order_by_metadata => NULL|ARR array( + * 'name' => 'metadata_text1', + * 'direction' => ASC|DESC, + * 'as' => text|integer + * ) + * Also supports array('name' => 'metadata_text1') * * metadata_owner_guids => NULL|ARR guids for metadata owners * @@ -474,7 +550,9 @@ function elgg_get_entities_from_metadata(array $options = array()) { $options = array_merge($defaults, $options); - $singulars = array('metadata_name', 'metadata_value', 'metadata_name_value_pair', 'metadata_owner_guid'); + $singulars = array('metadata_name', 'metadata_value', + 'metadata_name_value_pair', 'metadata_owner_guid'); + $options = elgg_normalise_plural_options_array($options, $singulars); if (!$options = elgg_entities_get_metastrings_options('metadata', $options)) { @@ -487,8 +565,8 @@ function elgg_get_entities_from_metadata(array $options = array()) { /** * Returns options to pass to elgg_get_entities() for metastrings operations. * - * @param string $type Metastring type: annotations or metadata - * @param array $options Options + * @param string $type Metastring type: annotations or metadata + * @param array $options Options * * @return array * @since 1.7.0 @@ -503,11 +581,13 @@ function elgg_entities_get_metastrings_options($type, $options) { // is plural (elgg_annotations) so rewrite for the table name. $n_table = ($type == 'annotation') ? 'annotations' : $type; - $singulars = array("{$type}_name", "{$type}_value", "{$type}_name_value_pair", "{$type}_owner_guid"); + $singulars = array("{$type}_name", "{$type}_value", + "{$type}_name_value_pair", "{$type}_owner_guid"); $options = elgg_normalise_plural_options_array($options, $singulars); - $clauses = elgg_get_entity_metadata_where_sql('e', $n_table, $options["{$type}_names"], $options["{$type}_values"], - $options["{$type}_name_value_pairs"], $options["{$type}_name_value_pairs_operator"], $options["{$type}_case_sensitive"], + $clauses = elgg_get_entity_metadata_where_sql('e', $n_table, $options["{$type}_names"], + $options["{$type}_values"], $options["{$type}_name_value_pairs"], + $options["{$type}_name_value_pairs_operator"], $options["{$type}_case_sensitive"], $options["order_by_{$type}"], $options["{$type}_owner_guids"]); if ($clauses) { @@ -530,7 +610,7 @@ function elgg_entities_get_metastrings_options($type, $options) { $options['joins'] = array_merge($options['joins'], $clauses['joins']); if ($clauses['orders']) { - $order_by_metadata = implode(", ",$clauses['orders']); + $order_by_metadata = implode(", ", $clauses['orders']); if (isset($options['order_by']) && $options['order_by']) { $options['order_by'] = "$order_by_metadata, {$options['order_by']}"; } else { @@ -550,18 +630,24 @@ function elgg_entities_get_metastrings_options($type, $options) { * This function is reused for annotations because the tables are * exactly the same. * - * @param string $e_table Entities table name - * @param string $n_table Normalized metastrings table name (Where entities, values, and names are joined. annotations / metadata) - * @param ARR|NULL $names - * @param ARR|NULL $values - * @param ARR|NULL $pairs array of names / values / operands - * @param AND|OR $pair_operator Operator to use to join the where clauses for pairs - * @param BOOL $case_sensitive - * @param ARR|NULL $order_by_metadata array of names / direction + * @param string $e_table Entities table name + * @param string $n_table Normalized metastrings table name (Where entities, + * values, and names are joined. annotations / metadata) + * @param arr|null $names Array of names + * @param arr|null $values Array of values + * @param arr|null $pairs Array of names / values / operands + * @param and|or $pair_operator Operator to use to join the where clauses for pairs + * @param bool $case_sensitive Case sensitive metadata names? + * @param arr|null $order_by_metadata Array of names / direction + * @param arr|null $owner_guids Array of owner GUIDs + * * @return FALSE|array False on fail, array('joins', 'wheres') * @since 1.7.0 */ -function elgg_get_entity_metadata_where_sql($e_table, $n_table, $names = NULL, $values = NULL, $pairs = NULL, $pair_operator = 'AND', $case_sensitive = TRUE, $order_by_metadata = NULL, $owner_guids = NULL) { +function elgg_get_entity_metadata_where_sql($e_table, $n_table, $names = NULL, $values = NULL, +$pairs = NULL, $pair_operator = 'AND', $case_sensitive = TRUE, $order_by_metadata = NULL, +$owner_guids = NULL) { + global $CONFIG; // short circuit if nothing requested @@ -593,7 +679,8 @@ function elgg_get_entity_metadata_where_sql($e_table, $n_table, $names = NULL, $ ); // will always want to join these tables if pulling metastrings. - $return['joins'][] = "JOIN {$CONFIG->dbprefix}{$n_table} n_table on {$e_table}.guid = n_table.entity_guid"; + $return['joins'][] = "JOIN {$CONFIG->dbprefix}{$n_table} n_table on + {$e_table}.guid = n_table.entity_guid"; $wheres = array(); @@ -727,11 +814,15 @@ function elgg_get_entity_metadata_where_sql($e_table, $n_table, $names = NULL, $ $name = sanitise_string($pair['name']); // @todo The multiple joins are only needed when the operator is AND - $return['joins'][] = "JOIN {$CONFIG->dbprefix}{$n_table} n_table{$i} on {$e_table}.guid = n_table{$i}.entity_guid"; - $return['joins'][] = "JOIN {$CONFIG->dbprefix}metastrings msn{$i} on n_table{$i}.name_id = msn{$i}.id"; - $return['joins'][] = "JOIN {$CONFIG->dbprefix}metastrings msv{$i} on n_table{$i}.value_id = msv{$i}.id"; + $return['joins'][] = "JOIN {$CONFIG->dbprefix}{$n_table} n_table{$i} + on {$e_table}.guid = n_table{$i}.entity_guid"; + $return['joins'][] = "JOIN {$CONFIG->dbprefix}metastrings msn{$i} + on n_table{$i}.name_id = msn{$i}.id"; + $return['joins'][] = "JOIN {$CONFIG->dbprefix}metastrings msv{$i} + on n_table{$i}.value_id = msv{$i}.id"; - $pair_wheres[] = "(msn{$i}.string = '$name' AND {$pair_binary}msv{$i}.string $operand $value AND $access)"; + $pair_wheres[] = "(msn{$i}.string = '$name' AND {$pair_binary}msv{$i}.string + $operand $value AND $access)"; $i++; } @@ -770,9 +861,12 @@ function elgg_get_entity_metadata_where_sql($e_table, $n_table, $names = NULL, $ } else { $direction = 'ASC'; } - $return['joins'][] = "JOIN {$CONFIG->dbprefix}{$n_table} n_table{$i} on {$e_table}.guid = n_table{$i}.entity_guid"; - $return['joins'][] = "JOIN {$CONFIG->dbprefix}metastrings msn{$i} on n_table{$i}.name_id = msn{$i}.id"; - $return['joins'][] = "JOIN {$CONFIG->dbprefix}metastrings msv{$i} on n_table{$i}.value_id = msv{$i}.id"; + $return['joins'][] = "JOIN {$CONFIG->dbprefix}{$n_table} n_table{$i} + on {$e_table}.guid = n_table{$i}.entity_guid"; + $return['joins'][] = "JOIN {$CONFIG->dbprefix}metastrings msn{$i} + on n_table{$i}.name_id = msn{$i}.id"; + $return['joins'][] = "JOIN {$CONFIG->dbprefix}metastrings msv{$i} + on n_table{$i}.value_id = msv{$i}.id"; $access = get_access_sql_suffix("n_table{$i}"); @@ -794,22 +888,24 @@ function elgg_get_entity_metadata_where_sql($e_table, $n_table, $names = NULL, $ * Return a list of entities based on the given search criteria. * * @deprecated 1.7 use elgg_get_entities_from_metadata(). - * @param mixed $meta_name - * @param mixed $meta_value - * @param string $entity_type The type of entity to look for, eg 'site' or 'object' + * + * @param mixed $meta_name Metadat name + * @param mixed $meta_value Metadata value + * @param string $entity_type The type of entity to look for, eg 'site' or 'object' * @param string $entity_subtype The subtype of the entity. - * @param int $limit - * @param int $offset - * @param string $order_by Optional ordering. - * @param int $site_guid The site to get entities for. Leave as 0 (default) for the current site; -1 for all sites. - * @param true|false $count If set to true, returns the total number of entities rather than a list. (Default: false) - * @param true|false $case_sensitive If set to false this searches for the meta data without case sensitivity. (Default: true) + * @param int $owner_guid Owner GUID + * @param int $limit Limit + * @param int $offset Offset + * @param string $order_by Optional ordering. + * @param int $site_guid Site GUID. 0 for current, -1 for any. + * @param bool $count Return a count instead of entities + * @param bool $case_sensitive Metadata names case sensitivity * * @return int|array A list of entities, or a count if $count is set to true */ -function get_entities_from_metadata($meta_name, $meta_value = "", $entity_type = "", $entity_subtype = "", -$owner_guid = 0, $limit = 10, $offset = 0, $order_by = "", $site_guid = 0, -$count = FALSE, $case_sensitive = TRUE) { +function get_entities_from_metadata($meta_name, $meta_value = "", $entity_type = "", +$entity_subtype = "", $owner_guid = 0, $limit = 10, $offset = 0, $order_by = "", +$site_guid = 0, $count = FALSE, $case_sensitive = TRUE) { elgg_deprecated_notice('get_entities_from_metadata() was deprecated by elgg_get_entities_from_metadata()!', 1.7); @@ -869,18 +965,27 @@ $count = FALSE, $case_sensitive = TRUE) { * @see elgg_view_entity_list * * @deprecated 1.8 Use elgg_list_entities_from_metadata - * @param mixed $meta_name Metadata name to search on - * @param mixed $meta_value The value to match, optionally - * @param string $entity_type The type of entity to look for, eg 'site' or 'object' + * + * @param mixed $meta_name Metadata name to search on + * @param mixed $meta_value The value to match, optionally + * @param string $entity_type The type of entity to look for, eg 'site' or 'object' * @param string $entity_subtype The subtype of the entity - * @param int $limit Number of entities to display per page - * @param true|false $fullview Whether or not to display the full view (default: true) - * @param true|false $viewtypetoggle Whether or not to allow users to toggle to the gallery view. Default: true - * @param true|false $pagination Display pagination? Default: true + * @param int $owner_guid Owner GUID + * @param int $limit Number of entities to display per page + * @param bool $fullview WDisplay the full view (default: true) + * @param bool $viewtypetoggle Allow users to toggle to the gallery view. Default: true + * @param bool $pagination Display pagination? Default: true + * @param bool $case_sensitive Case sensitive metadata names? + * + * @return string * * @return string A list of entities suitable for display */ -function list_entities_from_metadata($meta_name, $meta_value = "", $entity_type = ELGG_ENTITIES_ANY_VALUE, $entity_subtype = ELGG_ENTITIES_ANY_VALUE, $owner_guid = 0, $limit = 10, $fullview = true, $viewtypetoggle = true, $pagination = true, $case_sensitive = true ) { +function list_entities_from_metadata($meta_name, $meta_value = "", +$entity_type = ELGG_ENTITIES_ANY_VALUE, $entity_subtype = ELGG_ENTITIES_ANY_VALUE, +$owner_guid = 0, $limit = 10, $fullview = true, $viewtypetoggle = true, +$pagination = true, $case_sensitive = true) { + elgg_deprecated_notice('list_entities_from_metadata() was deprecated by elgg_list_entities_from_metadata()!', 1.8); $offset = (int) get_input('offset'); @@ -901,7 +1006,8 @@ function list_entities_from_metadata($meta_name, $meta_value = "", $entity_type $options['count'] = FALSE; $entities = elgg_get_entities_from_metadata($options); - return elgg_view_entity_list($entities, $count, $offset, $limit, $fullview, $viewtypetoggle, $pagination); + return elgg_view_entity_list($entities, $count, $offset, $limit, + $fullview, $viewtypetoggle, $pagination); } /** @@ -909,7 +1015,9 @@ function list_entities_from_metadata($meta_name, $meta_value = "", $entity_type * * @see elgg_get_entities_from_metadata * - * @param array $options + * @param array $options Options array + * + * @return array * @since 1.7.0 */ function elgg_list_entities_from_metadata($options) { @@ -926,26 +1034,32 @@ function elgg_list_entities_from_metadata($options) { $count = elgg_get_entities_from_metadata(array_merge(array('count' => TRUE), $options)); $entities = elgg_get_entities_from_metadata($options); - return elgg_view_entity_list($entities, $count, $options['offset'], $options['limit'], $options['full_view'], $options['view_type_toggle'], $options['pagination']); + return elgg_view_entity_list($entities, $count, $options['offset'], $options['limit'], + $options['full_view'], $options['view_type_toggle'], $options['pagination']); } /** + * Return entities from metadata + * * @deprecated 1.7. Use elgg_get_entities_from_metadata(). - * @param $meta_array - * @param $entity_type - * @param $entity_subtype - * @param $owner_guid - * @param $limit - * @param $offset - * @param $order_by - * @param $site_guid - * @param $count - * @param $meta_array_operator - * @return unknown_type + * + * @param mixed $meta_array Metadata name + * @param string $entity_type The type of entity to look for, eg 'site' or 'object' + * @param string $entity_subtype The subtype of the entity. + * @param int $owner_guid Owner GUID + * @param int $limit Limit + * @param int $offset Offset + * @param string $order_by Optional ordering. + * @param int $site_guid Site GUID. 0 for current, -1 for any. + * @param bool $count Return a count instead of entities + * @param bool $meta_array_operator Operator for metadata values + * + * @return int|array A list of entities, or a count if $count is set to true */ function get_entities_from_metadata_multi($meta_array, $entity_type = "", $entity_subtype = "", $owner_guid = 0, $limit = 10, $offset = 0, $order_by = "", $site_guid = 0, $count = false, $meta_array_operator = 'and') { + elgg_deprecated_notice('get_entities_from_metadata_multi() was deprecated by elgg_get_entities_from_metadata()!', 1.7); if (!is_array($meta_array) || sizeof($meta_array) == 0) { @@ -1002,30 +1116,37 @@ $count = false, $meta_array_operator = 'and') { * * @see elgg_view_entity_list * - * @param array $meta_array Array of 'name' => 'value' pairs - * @param string $entity_type The type of entity to look for, eg 'site' or 'object' + * @param array $meta_array Array of 'name' => 'value' pairs + * @param string $entity_type The type of entity to look for, eg 'site' or 'object' * @param string $entity_subtype The subtype of the entity. - * @param int $limit - * @param int $offset - * @param string $order_by Optional ordering. - * @param true|false $fullview Whether or not to display the full view (default: true) - * @param true|false $viewtypetoggle Whether or not to allow users to toggle to the gallery view. Default: true - * @param true|false $pagination Display pagination? Default: true + * @param int $owner_guid Owner GUID + * @param int $limit Limit + * @param bool $fullview WDisplay the full view (default: true) + * @param bool $viewtypetoggle Allow users to toggle to the gallery view. Default: true + * @param bool $pagination Display pagination? Default: true + * * @return string List of ElggEntities suitable for display */ -function list_entities_from_metadata_multi($meta_array, $entity_type = "", $entity_subtype = "", $owner_guid = 0, $limit = 10, $fullview = true, $viewtypetoggle = true, $pagination = true) { +function list_entities_from_metadata_multi($meta_array, $entity_type = "", $entity_subtype = "", +$owner_guid = 0, $limit = 10, $fullview = true, $viewtypetoggle = true, $pagination = true) { + $offset = (int) get_input('offset'); $limit = (int) $limit; - $count = get_entities_from_metadata_multi($meta_array, $entity_type, $entity_subtype, $owner_guid, $limit, $offset, "", $site_guid, true); - $entities = get_entities_from_metadata_multi($meta_array, $entity_type, $entity_subtype, $owner_guid, $limit, $offset, "", $site_guid, false); + $count = get_entities_from_metadata_multi($meta_array, $entity_type, $entity_subtype, + $owner_guid, $limit, $offset, "", $site_guid, true); + $entities = get_entities_from_metadata_multi($meta_array, $entity_type, $entity_subtype, + $owner_guid, $limit, $offset, "", $site_guid, false); - return elgg_view_entity_list($entities, $count, $offset, $limit, $fullview, $viewtypetoggle, $pagination); + return elgg_view_entity_list($entities, $count, $offset, $limit, $fullview, + $viewtypetoggle, $pagination); } /** * Clear all the metadata for a given entity, assuming you have access to that metadata. * - * @param int $guid + * @param int $entity_guid Entity GUID + * + * @return bool */ function clear_metadata($entity_guid) { global $CONFIG; @@ -1043,6 +1164,8 @@ function clear_metadata($entity_guid) { * Clear all annotations belonging to a given owner_guid * * @param int $owner_guid The owner + * + * @return bool */ function clear_metadata_by_owner($owner_guid) { global $CONFIG; @@ -1066,6 +1189,13 @@ function clear_metadata_by_owner($owner_guid) { /** * Handler called by trigger_plugin_hook on the "export" event. + * + * @param string $hook export + * @param string $entity_type all + * @param mixed $returnvalue Value returned from previous hook + * @param mixed $params Params + * + * @return array */ function export_metadata_plugin_hook($hook, $entity_type, $returnvalue, $params) { // Sanity check values @@ -1092,17 +1222,23 @@ function export_metadata_plugin_hook($hook, $entity_type, $returnvalue, $params) } /** - * Takes in a comma-separated string and returns an array of tags which have been trimmed and set to lower case + * Takes in a comma-separated string and returns an array of tags + * which have been trimmed and set to lower case * * @param string $string Comma-separated tag string + * * @return array|false An array of strings, or false on failure */ function string_to_tag_array($string) { if (is_string($string)) { - $ar = explode(",",$string); - $ar = array_map('trim', $ar); // trim blank spaces - $ar = array_map('elgg_strtolower', $ar); // make lower case : [Marcus Povey 20090605 - Using mb wrapper function using UTF8 safe function where available] - $ar = array_filter($ar, 'is_not_null'); // Remove null values + $ar = explode(",", $string); + // trim blank spaces + $ar = array_map('trim', $ar); + // make lower case : [Marcus Povey 20090605 - Using mb wrapper function + // using UTF8 safe function where available] + $ar = array_map('elgg_strtolower', $ar); + // Remove null values + $ar = array_filter($ar, 'is_not_null'); return $ar; } return false; @@ -1110,16 +1246,18 @@ function string_to_tag_array($string) { } /** - * Takes a metadata array (which has all kinds of properties) and turns it into a simple array of strings + * Takes a metadata array (which has all kinds of properties) + * and turns it into a simple array of strings * * @param array $array Metadata array + * * @return array Array of strings */ function metadata_array_to_values($array) { $valuearray = array(); if (is_array($array)) { - foreach($array as $element) { + foreach ($array as $element) { $valuearray[] = $element->value; } } @@ -1128,9 +1266,12 @@ function metadata_array_to_values($array) { } /** - * Get the URL for this item of metadata, by default this links to the export handler in the current view. + * Get the URL for this item of metadata, by default this + * links to the export handler in the current view. + * + * @param int $id Metadata ID * - * @param int $id + * @return mixed */ function get_metadata_url($id) { $id = (int)$id; @@ -1145,8 +1286,10 @@ function get_metadata_url($id) { * Mark entities with a particular type and subtype as having access permissions * that can be changed independently from their parent entity * - * @param string $type The type - object, user, etc + * @param string $type The type - object, user, etc * @param string $subtype The subtype; all subtypes by default + * + * @return void */ function register_metadata_as_independent($type, $subtype = '*') { global $CONFIG; @@ -1160,9 +1303,10 @@ function register_metadata_as_independent($type, $subtype = '*') { * Determines whether entities of a given type and subtype should not change * their metadata in line with their parent entity * - * @param string $type The type - object, user, etc + * @param string $type The type - object, user, etc * @param string $subtype The entity subtype - * @return true|false + * + * @return bool */ function is_metadata_independent($type, $subtype) { global $CONFIG; @@ -1179,9 +1323,11 @@ function is_metadata_independent($type, $subtype) { /** * When an entity is updated, resets the access ID on all of its child metadata * - * @param string $event The name of the event - * @param string $object_type The type of object - * @param ElggEntity $object The entity itself + * @param string $event The name of the event + * @param string $object_type The type of object + * @param ElggEntity $object The entity itself + * + * @return true */ function metadata_update($event, $object_type, $object) { if ($object instanceof ElggEntity) { @@ -1189,7 +1335,8 @@ function metadata_update($event, $object_type, $object) { global $CONFIG; $access_id = (int) $object->access_id; $guid = (int) $object->getGUID(); - update_data("update {$CONFIG->dbprefix}metadata set access_id = {$access_id} where entity_guid = {$guid}"); + $query = "update {$CONFIG->dbprefix}metadata set access_id = {$access_id} where entity_guid = {$guid}"; + update_data($query); } } return true; @@ -1200,6 +1347,8 @@ function metadata_update($event, $object_type, $object) { * * @param string $function_name The function. * @param string $extender_name The name, default 'all'. + * + * @return bool */ function register_metadata_url_handler($function_name, $extender_name = "all") { return register_extender_url_handler($function_name, 'metadata', $extender_name); @@ -1207,11 +1356,23 @@ function register_metadata_url_handler($function_name, $extender_name = "all") { /** Register the hook */ register_plugin_hook("export", "all", "export_metadata_plugin_hook", 2); + /** Call a function whenever an entity is updated **/ -register_elgg_event_handler('update','all','metadata_update'); +register_elgg_event_handler('update', 'all', 'metadata_update'); // unit testing register_plugin_hook('unit_test', 'system', 'metadata_test'); + +/** + * Metadata unit test + * + * @param string $hook unit_test + * @param string $type system + * @param mixed $value Array of other tests + * @param mixed $params Params + * + * @return array + */ function metadata_test($hook, $type, $value, $params) { global $CONFIG; $value[] = $CONFIG->path . 'engine/tests/objects/metadata.php'; diff --git a/engine/lib/metastrings.php b/engine/lib/metastrings.php index 4ca4f1fe2..8a105b822 100644 --- a/engine/lib/metastrings.php +++ b/engine/lib/metastrings.php @@ -3,8 +3,8 @@ * Elgg metastrngs * Functions to manage object metastrings. * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage DataModel.MetaStrings */ /** Cache metastrings for a page */ @@ -16,20 +16,22 @@ $METASTRINGS_DEADNAME_CACHE = array(); /** * Return the meta string id for a given tag, or false. * - * @param string $string The value (whatever that is) to be stored - * @param bool $case_sensitive Do we want to make the query case sensitive? If not there may be more than one result - * @return int|array|false meta string id, array of ids or false if none found + * @param string $string The value to store + * @param bool $case_sensitive Do we want to make the query case sensitive? + * If not there may be more than one result + * + * @return int|array|false meta string id, array of ids or false if none found */ function get_metastring_id($string, $case_sensitive = TRUE) { global $CONFIG, $METASTRINGS_CACHE, $METASTRINGS_DEADNAME_CACHE; $string = sanitise_string($string); - - // caching doesn't work for case insensitive searches - if ($case_sensitive) { + + // caching doesn't work for case insensitive searches + if ($case_sensitive) { $result = array_search($string, $METASTRINGS_CACHE, true); - - if ($result!==false) { + + if ($result !== false) { elgg_log("** Returning id for string:$string from cache."); return $result; } @@ -38,7 +40,7 @@ function get_metastring_id($string, $case_sensitive = TRUE) { if (in_array($string, $METASTRINGS_DEADNAME_CACHE, true)) { return false; } - + // Experimental memcache $msfc = null; static $metastrings_memcache; @@ -65,7 +67,7 @@ function get_metastring_id($string, $case_sensitive = TRUE) { if (is_array($metaStrings)) { if (sizeof($metaStrings) > 1) { $ids = array(); - foreach($metaStrings as $metaString) { + foreach ($metaStrings as $metaString) { $ids[] = $metaString->id; } return $ids; @@ -73,7 +75,7 @@ function get_metastring_id($string, $case_sensitive = TRUE) { $row = $metaStrings[0]; } } - + if ($row) { $METASTRINGS_CACHE[$row->id] = $row->string; // Cache it @@ -96,6 +98,7 @@ function get_metastring_id($string, $case_sensitive = TRUE) { * When given an ID, returns the corresponding metastring * * @param int $id Metastring ID + * * @return string Metastring */ function get_metastring($id) { @@ -124,8 +127,9 @@ function get_metastring($id) { * Add a metastring. * It returns the id of the tag, whether by creating it or updating it. * - * @param string $string The value (whatever that is) to be stored - * @param bool $case_sensitive Do we want to make the query case sensitive? + * @param string $string The value (whatever that is) to be stored + * @param bool $case_sensitive Do we want to make the query case sensitive? + * * @return mixed Integer tag or false. */ function add_metastring($string, $case_sensitive = true) { @@ -152,6 +156,7 @@ function add_metastring($string, $case_sensitive = true) { /** * Delete any orphaned entries in metastrings. This is run by the garbage collector. * + * @return bool */ function delete_orphaned_metastrings() { global $CONFIG; diff --git a/engine/lib/notification.php b/engine/lib/notification.php index 98bdcbca5..cfb79715c 100644 --- a/engine/lib/notification.php +++ b/engine/lib/notification.php @@ -3,20 +3,19 @@ * Notifications * This file contains classes and functions which allow plugins to register and send notifications. * - * There are notification methods which are provided out of the box (see notification_init() ). Each method - * is identified by a string, e.g. "email". + * There are notification methods which are provided out of the box + * (see notification_init() ). Each method is identified by a string, e.g. "email". * - * To register an event use register_notification_handler() and pass the method name and a handler function. + * To register an event use register_notification_handler() and pass the method name and a + * handler function. * - * To send a notification call notify() passing it the method you wish to use combined with a number of method - * specific addressing parameters. + * To send a notification call notify() passing it the method you wish to use combined with a + * number of method specific addressing parameters. * * Catch NotificationException to trap errors. * - * @package Elgg - * @subpackage API - - + * @package Elgg.Core + * @subpackage Notifications */ /** Notification handlers */ @@ -25,9 +24,15 @@ $NOTIFICATION_HANDLERS = array(); /** * This function registers a handler for a given notification type (eg "email") * - * @param string $method The method - * @param string $handler The handler function, in the format "handler(ElggEntity $from, ElggUser $to, $subject, $message, array $params = NULL)". This function should return false on failure, and true/a tracking message ID on success. - * @param array $params A associated array of other parameters for this handler defining some properties eg. supported message length or rich text support. + * @param string $method The method + * @param string $handler The handler function, in the format + * "handler(ElggEntity $from, ElggUser $to, $subject, + * $message, array $params = NULL)". This function should + * return false on failure, and true/a tracking message ID on success. + * @param array $params An associated array of other parameters for this handler + * defining some properties eg. supported msg length or rich text support. + * + * @return bool */ function register_notification_handler($method, $handler, $params = NULL) { global $NOTIFICATION_HANDLERS; @@ -52,6 +57,8 @@ function register_notification_handler($method, $handler, $params = NULL) { * This function unregisters a handler for a given notification type (eg "email") * * @param string $method The method + * + * @return void * @since 1.7.1 */ function unregister_notification_handler($method) { @@ -65,13 +72,15 @@ function unregister_notification_handler($method) { /** * Notify a user via their preferences. * - * @param mixed $to Either a guid or an array of guid's to notify. - * @param int $from GUID of the sender, which may be a user, site or object. - * @param string $subject Message subject. - * @param string $message Message body. - * @param array $params Misc additional parameters specific to various methods. - * @param mixed $methods_override A string, or an array of strings specifying the delivery methods to use - or leave blank - * for delivery using the user's chosen delivery methods. + * @param mixed $to Either a guid or an array of guid's to notify. + * @param int $from GUID of the sender, which may be a user, site or object. + * @param string $subject Message subject. + * @param string $message Message body. + * @param array $params Misc additional parameters specific to various methods. + * @param mixed $methods_override A string, or an array of strings specifying the delivery + * methods to use - or leave blank for delivery using the + * user's chosen delivery methods. + * * @return array Compound array of each delivery user/delivery method's success or failure. * @throws NotificationException */ @@ -102,7 +111,7 @@ function notify_user($to, $from, $subject, $message, array $params = NULL, $meth if (!$methods) { $tmp = (array)get_user_notification_settings($guid); $methods = array(); - foreach($tmp as $k => $v) { + foreach ($tmp as $k => $v) { // Add method if method is turned on for user! if ($v) { $methods[] = $k; @@ -153,6 +162,7 @@ function notify_user($to, $from, $subject, $message, array $params = NULL, $meth * Get the notification settings for a given user. * * @param int $user_guid The user id + * * @return stdClass */ function get_user_notification_settings($user_guid = 0) { @@ -185,9 +195,10 @@ function get_user_notification_settings($user_guid = 0) { /** * Set a user notification pref. * - * @param int $user_guid The user id. - * @param string $method The delivery method (eg. email) - * @param bool $value On(true) or off(false). + * @param int $user_guid The user id. + * @param string $method The delivery method (eg. email) + * @param bool $value On(true) or off(false). + * * @return bool */ function set_user_notification_setting($user_guid, $method, $value) { @@ -213,26 +224,32 @@ function set_user_notification_setting($user_guid, $method, $value) { /** * Send a notification via email. * - * @param ElggEntity $from The from user/site/object - * @param ElggUser $to To which user? - * @param string $subject The subject of the message. - * @param string $message The message body - * @param array $params Optional parameters (none taken in this instance) + * @param ElggEntity $from The from user/site/object + * @param ElggUser $to To which user? + * @param string $subject The subject of the message. + * @param string $message The message body + * @param array $params Optional parameters (none taken in this instance) + * * @return bool */ -function email_notify_handler(ElggEntity $from, ElggUser $to, $subject, $message, array $params = NULL) { +function email_notify_handler(ElggEntity $from, ElggUser $to, $subject, $message, +array $params = NULL) { + global $CONFIG; if (!$from) { - throw new NotificationException(sprintf(elgg_echo('NotificationException:MissingParameter'), 'from')); + $msg = sprintf(elgg_echo('NotificationException:MissingParameter'), 'from'); + throw new NotificationException($msg); } if (!$to) { - throw new NotificationException(sprintf(elgg_echo('NotificationException:MissingParameter'), 'to')); + $msg = sprintf(elgg_echo('NotificationException:MissingParameter'), 'to'); + throw new NotificationException($msg); } - if ($to->email=="") { - throw new NotificationException(sprintf(elgg_echo('NotificationException:NoEmailAddress'), $to->guid)); + if ($to->email == "") { + $msg = sprintf(elgg_echo('NotificationException:NoEmailAddress'), $to->guid); + throw new NotificationException($msg); } // To @@ -257,11 +274,12 @@ function email_notify_handler(ElggEntity $from, ElggUser $to, $subject, $message /** * Send an email to any email address * - * @param string $from Email address or string: "name <email>" - * @param string $to Email address or string: "name <email>" + * @param string $from Email address or string: "name <email>" + * @param string $to Email address or string: "name <email>" * @param string $subject The subject of the message - * @param string $body The message body - * @param array $params Optional parameters (none used in this function) + * @param string $body The message body + * @param array $params Optional parameters (none used in this function) + * * @return bool * @since 1.7.2 */ @@ -269,19 +287,24 @@ function elgg_send_email($from, $to, $subject, $body, array $params = NULL) { global $CONFIG; if (!$from) { - throw new NotificationException(sprintf(elgg_echo('NotificationException:NoEmailAddress'), 'from')); + $msg = sprintf(elgg_echo('NotificationException:NoEmailAddress'), 'from'); + throw new NotificationException($msg); } if (!$to) { - throw new NotificationException(sprintf(elgg_echo('NotificationException:NoEmailAddress'), 'to')); + $msg = sprintf(elgg_echo('NotificationException:NoEmailAddress'), 'to'); + throw new NotificationException($msg); } // return TRUE/FALSE to stop elgg_send_email() from sending - $mail_params = array( 'to' => $to, + $mail_params = array( + 'to' => $to, 'from' => $from, 'subject' => $subject, 'body' => $body, - 'params' => $params); + 'params' => $params + ); + $result = trigger_plugin_hook('email', 'system', $mail_params, NULL); if ($result !== NULL) { return $result; @@ -294,7 +317,7 @@ function elgg_send_email($from, $to, $subject, $body, array $params = NULL) { } // Windows is somewhat broken, so we use just address for to and from - if (strtolower(substr(PHP_OS, 0 , 3)) == 'win') { + if (strtolower(substr(PHP_OS, 0, 3)) == 'win') { // strip name from to and from if (strpos($to, '<')) { preg_match('/<(.*)>/', $to, $matches); @@ -315,7 +338,7 @@ function elgg_send_email($from, $to, $subject, $body, array $params = NULL) { // Sanitise subject by stripping line endings $subject = preg_replace("/(\r\n|\r|\n)/", " ", $subject); if (is_callable('mb_encode_mimeheader')) { - $subject = mb_encode_mimeheader($subject,"UTF-8", "B"); + $subject = mb_encode_mimeheader($subject, "UTF-8", "B"); } // Format message @@ -330,6 +353,7 @@ function elgg_send_email($from, $to, $subject, $body, array $params = NULL) { /** * Correctly initialise notifications and register the email handler. * + * @return void */ function notification_init() { // Register a notification handler for the default email method @@ -338,11 +362,15 @@ function notification_init() { // Add settings view to user settings & register action extend_elgg_settings_page('notifications/settings/usersettings', 'usersettings/user'); - register_plugin_hook('usersettings:save','user','notification_user_settings_save'); - - //register_action("notifications/settings/usersettings/save"); + register_plugin_hook('usersettings:save', 'user', 'notification_user_settings_save'); } +/** + * Includes the action to save user notifications + * + * @return void + * @todo why can't this call action(...)? + */ function notification_user_settings_save() { global $CONFIG; include($CONFIG->path . "actions/notifications/settings/usersettings/save.php"); @@ -351,11 +379,13 @@ function notification_user_settings_save() { /** * Register an entity type and subtype to be eligible for notifications * - * @param string $entity_type The type of entity + * @param string $entity_type The type of entity * @param string $object_subtype Its subtype - * @param string $english_name It's English notification string (eg "New blog post") + * @param string $language_name Its localized notification string (eg "New blog post") + * + * @return void */ -function register_notification_object($entity_type, $object_subtype, $english_name) { +function register_notification_object($entity_type, $object_subtype, $language_name) { global $CONFIG; if ($entity_type == '') { @@ -373,14 +403,15 @@ function register_notification_object($entity_type, $object_subtype, $english_na $CONFIG->register_objects[$entity_type] = array(); } - $CONFIG->register_objects[$entity_type][$object_subtype] = $english_name; + $CONFIG->register_objects[$entity_type][$object_subtype] = $language_name; } /** * Establish a 'notify' relationship between the user and a content author * - * @param int $user_guid The GUID of the user who wants to follow a user's content + * @param int $user_guid The GUID of the user who wants to follow a user's content * @param int $author_guid The GUID of the user whose content the user wants to follow + * * @return true|false Depending on success */ function register_notification_interest($user_guid, $author_guid) { @@ -390,8 +421,9 @@ function register_notification_interest($user_guid, $author_guid) { /** * Remove a 'notify' relationship between the user and a content author * - * @param int $user_guid The GUID of the user who is following a user's content + * @param int $user_guid The GUID of the user who is following a user's content * @param int $author_guid The GUID of the user whose content the user wants to unfollow + * * @return true|false Depending on success */ function remove_notification_interest($user_guid, $author_guid) { @@ -403,6 +435,12 @@ function remove_notification_interest($user_guid, $author_guid) { * objects and attempts to send notifications to anybody who's interested * * @see register_notification_object + * + * @param string $event create + * @param string $object_type mixed + * @param mixed $object The object created + * + * @return void */ function object_notifications($event, $object_type, $object) { // We only want to trigger notification events for ElggEntities @@ -411,7 +449,7 @@ function object_notifications($event, $object_type, $object) { // Get config data global $CONFIG, $SESSION, $NOTIFICATION_HANDLERS; - $hookresult = trigger_plugin_hook('object:notifications',$object_type,array( + $hookresult = trigger_plugin_hook('object:notifications', $object_type, array( 'event' => $event, 'object_type' => $object_type, 'object' => $object, @@ -437,7 +475,7 @@ function object_notifications($event, $object_type, $object) { // Get users interested in content from this person and notify them // (Person defined by container_guid so we can also subscribe to groups if we want) - foreach($NOTIFICATION_HANDLERS as $method => $foo) { + foreach ($NOTIFICATION_HANDLERS as $method => $foo) { $interested_users = elgg_get_entities_from_relationship(array( 'relationship' => 'notify' . $method, 'relationship_guid' => $object->container_guid, @@ -447,19 +485,20 @@ function object_notifications($event, $object_type, $object) { )); if ($interested_users && is_array($interested_users)) { - foreach($interested_users as $user) { + foreach ($interested_users as $user) { if ($user instanceof ElggUser && !$user->isBanned()) { - if (($user->guid != $SESSION['user']->guid) && has_access_to_entity($object,$user) + if (($user->guid != $SESSION['user']->guid) && has_access_to_entity($object, $user) && $object->access_id != ACCESS_PRIVATE) { - $methodstring = trigger_plugin_hook('notify:entity:message',$object->getType(),array( + $methodstring = trigger_plugin_hook('notify:entity:message', $object->getType(), array( 'entity' => $object, 'to_entity' => $user, - 'method' => $method),$string); + 'method' => $method), $string); if (empty($methodstring) && $methodstring !== false) { $methodstring = $string; } if ($methodstring !== false) { - notify_user($user->guid,$object->container_guid,$descr,$methodstring,NULL,array($method)); + notify_user($user->guid, $object->container_guid, $descr, $methodstring, + NULL, array($method)); } } } @@ -471,5 +510,5 @@ function object_notifications($event, $object_type, $object) { } // Register a startup event -register_elgg_event_handler('init','system','notification_init',0); -register_elgg_event_handler('create','object','object_notifications'); +register_elgg_event_handler('init', 'system', 'notification_init', 0); +register_elgg_event_handler('create', 'object', 'object_notifications');
\ No newline at end of file diff --git a/engine/lib/objects.php b/engine/lib/objects.php index c078074c4..ae30edb13 100644 --- a/engine/lib/objects.php +++ b/engine/lib/objects.php @@ -10,7 +10,9 @@ /** * Return the object specific details of a object by a row. * - * @param int $guid + * @param int $guid The guid to retreive + * + * @return bool */ function get_object_entity_as_row($guid) { global $CONFIG; @@ -23,9 +25,11 @@ function get_object_entity_as_row($guid) { * Create or update the extras table for a given object. * Call create_entity first. * - * @param int $guid The guid of the entity you're creating (as obtained by create_entity) - * @param string $title The title of the object + * @param int $guid The guid of the entity you're creating (as obtained by create_entity) + * @param string $title The title of the object * @param string $description The object's description + * + * @return bool */ function create_object_entity($guid, $title, $description) { global $CONFIG; @@ -38,12 +42,16 @@ function create_object_entity($guid, $title, $description) { if ($row) { // Core entities row exists and we have access to it - if ($exists = get_data_row("SELECT guid from {$CONFIG->dbprefix}objects_entity where guid = {$guid}")) { - $result = update_data("UPDATE {$CONFIG->dbprefix}objects_entity set title='$title', description='$description' where guid=$guid"); - if ($result!=false) { + $query = "SELECT guid from {$CONFIG->dbprefix}objects_entity where guid = {$guid}"; + if ($exists = get_data_row($query)) { + $query = "UPDATE {$CONFIG->dbprefix}objects_entity + set title='$title', description='$description' where guid=$guid"; + + $result = update_data($query); + if ($result != false) { // Update succeeded, continue $entity = get_entity($guid); - if (trigger_elgg_event('update',$entity->type,$entity)) { + if (trigger_elgg_event('update', $entity->type, $entity)) { return $guid; } else { $entity->delete(); @@ -51,14 +59,16 @@ function create_object_entity($guid, $title, $description) { } } else { // Update failed, attempt an insert. - $result = insert_data("INSERT into {$CONFIG->dbprefix}objects_entity (guid, title, description) values ($guid, '$title','$description')"); - if ($result!==false) { + $query = "INSERT into {$CONFIG->dbprefix}objects_entity + (guid, title, description) values ($guid, '$title','$description')"; + + $result = insert_data($query); + if ($result !== false) { $entity = get_entity($guid); - if (trigger_elgg_event('create',$entity->type,$entity)) { + if (trigger_elgg_event('create', $entity->type, $entity)) { return $guid; } else { $entity->delete(); - //delete_entity($guid); } } } @@ -71,8 +81,12 @@ function create_object_entity($guid, $title, $description) { * THIS FUNCTION IS DEPRECATED. * * Delete a object's extra data. + * * @todo - this should be removed - was deprecated in 1.5 or earlier - * @param int $guid + * + * @param int $guid GUID + * + * @return 1 */ function delete_object_entity($guid) { system_message(sprintf(elgg_echo('deprecatedfunction'), 'delete_user_entity')); @@ -81,17 +95,20 @@ function delete_object_entity($guid) { } /** - * Searches for an object based on a complete or partial title or description using full text searching. + * Searches for an object based on a complete or partial title + * or description using full text searching. * * IMPORTANT NOTE: With MySQL's default setup: * 1) $criteria must be 4 or more characters long * 2) If $criteria matches greater than 50% of results NO RESULTS ARE RETURNED! * - * @param string $criteria The partial or full name or username. - * @param int $limit Limit of the search. - * @param int $offset Offset. - * @param string $order_by The order. - * @param boolean $count Whether to return the count of results or just the results. + * @param string $criteria The partial or full name or username. + * @param int $limit Limit of the search. + * @param int $offset Offset. + * @param string $order_by The order. + * @param boolean $count Whether to return the count of results or just the results. + * + * @return int|false * @deprecated 1.7 */ function search_for_object($criteria, $limit = 10, $offset = 0, $order_by = "", $count = false) { @@ -115,7 +132,9 @@ function search_for_object($criteria, $limit = 10, $offset = 0, $order_by = "", } else { $query = "SELECT e.* "; } - $query .= "from {$CONFIG->dbprefix}entities e join {$CONFIG->dbprefix}objects_entity o on e.guid=o.guid where match(o.title,o.description) against ('$criteria') and $access"; + $query .= "from {$CONFIG->dbprefix}entities e + join {$CONFIG->dbprefix}objects_entity o on e.guid=o.guid + where match(o.title,o.description) against ('$criteria') and $access"; if (!$count) { $query .= " order by $order_by limit $offset, $limit"; // Add order and limit @@ -132,8 +151,9 @@ function search_for_object($criteria, $limit = 10, $offset = 0, $order_by = "", * Get the sites this object is part of * * @param int $object_guid The object's GUID - * @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 false|array On success, an array of ElggSites */ function get_object_sites($object_guid, $limit = 10, $offset = 0) { @@ -152,6 +172,13 @@ function get_object_sites($object_guid, $limit = 10, $offset = 0) { /** * Runs unit tests for ElggObject + * + * @param sting $hook unit_test + * @param string $type system + * @param mixed $value Array of tests + * @param mixed $params Params + * + * @return array */ function objects_test($hook, $type, $value, $params) { global $CONFIG; @@ -162,8 +189,15 @@ function objects_test($hook, $type, $value, $params) { /** * Returns a formatted list of objects suitable for injecting into search. + * * @deprecated 1.7 * + * @param sting $hook Hook + * @param string $user user + * @param mixed $returnvalue Previous return value + * @param mixed $tag Search term + * + * @return array */ function search_list_objects_by_name($hook, $user, $returnvalue, $tag) { elgg_deprecated_notice('search_list_objects_by_name was deprecated by new search plugin.', 1.7); @@ -174,14 +208,16 @@ function search_list_objects_by_name($hook, $user, $returnvalue, $tag) { $object = get_input('object'); if (!get_input('offset') && (empty($object) || $object == 'user')) { - if ($users = search_for_user($tag,$threshold)) { - $countusers = search_for_user($tag,0,0,"",true); + if ($users = search_for_user($tag, $threshold)) { + $countusers = search_for_user($tag, 0, 0, "", true); - $return = elgg_view('user/search/startblurb',array('count' => $countusers, 'tag' => $tag)); - foreach($users as $user) { + $return = elgg_view('user/search/startblurb', array('count' => $countusers, 'tag' => $tag)); + foreach ($users as $user) { $return .= elgg_view_entity($user); } - $return .= elgg_view('user/search/finishblurb',array('count' => $countusers, 'threshold' => $threshold, 'tag' => $tag)); + $return .= elgg_view('user/search/finishblurb', + array('count' => $countusers, 'threshold' => $threshold, 'tag' => $tag)); + return $return; } @@ -189,4 +225,4 @@ function search_list_objects_by_name($hook, $user, $returnvalue, $tag) { } register_elgg_event_handler('init', 'system', 'objects_init', 0); -register_plugin_hook('unit_test', 'system', 'objects_test'); +register_plugin_hook('unit_test', 'system', 'objects_test');
\ No newline at end of file diff --git a/engine/lib/opendd.php b/engine/lib/opendd.php index f3f9f017d..d856806f5 100644 --- a/engine/lib/opendd.php +++ b/engine/lib/opendd.php @@ -2,8 +2,8 @@ /** * OpenDD PHP Library. * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage ODD * @version 0.4 */ @@ -11,21 +11,22 @@ * Attempt to construct an ODD object out of a XmlElement or sub-elements. * * @param XmlElement $element The element(s) + * * @return mixed An ODD object if the element can be handled, or false. */ -function ODD_factory(XmlElement $element) { +function ODD_factory (XmlElement $element) { $name = $element->name; $odd = false; switch ($name) { case 'entity' : - $odd = new ODDEntity("","",""); + $odd = new ODDEntity("", "", ""); break; case 'metadata' : - $odd = new ODDMetaData("","","",""); + $odd = new ODDMetaData("", "", "", ""); break; case 'relationship' : - $odd = new ODDRelationship("","",""); + $odd = new ODDRelationship("", "", ""); break; } @@ -33,15 +34,15 @@ function ODD_factory(XmlElement $element) { if ($odd) { // Attributes foreach ($element->attributes as $k => $v) { - $odd->setAttribute($k,$v); + $odd->setAttribute($k, $v); } // Body $body = $element->content; $a = stripos($body, "<![CDATA"); $b = strripos($body, "]]>"); - if (($body) && ($a!==false) && ($b!==false)) { - $body = substr($body, $a+8, $b-($a+8)); + if (($body) && ($a !== false) && ($b !== false)) { + $body = substr($body, $a + 8, $b - ($a + 8)); } $odd->setBody($body); @@ -54,6 +55,7 @@ function ODD_factory(XmlElement $element) { * Import an ODD document. * * @param string $xml The XML ODD. + * * @return ODDDocument */ function ODD_Import($xml) { @@ -92,7 +94,8 @@ function ODD_Import($xml) { * Export an ODD Document. * * @param ODDDocument $document The Document. - * @param ODDWrapperFactory $wrapper Optional wrapper permitting the export process to embed ODD in other document formats. + * + * @return string */ function ODD_Export(ODDDocument $document) { return "$document"; diff --git a/engine/lib/output.php b/engine/lib/output.php index b4311787a..6fd820486 100644 --- a/engine/lib/output.php +++ b/engine/lib/output.php @@ -11,6 +11,7 @@ * Takes a string and turns any URLs into formatted links * * @param string $text The input string + * * @return string The output stirng with formatted links **/ function parse_urls($text) { @@ -44,8 +45,10 @@ function parse_urls($text) { * Create paragraphs from text with line spacing * Borrowed from Wordpress. * - * @param string $pee - * @param bool $br + * @param string $pee The string + * @param bool $br Add BRs? + * + * @todo Rewrite * @return string **/ function autop($pee, $br = 1) { @@ -93,8 +96,9 @@ function autop($pee, $br = 1) { * If no spaces are found (like in Japanese) will crop off at the * n char mark. Adds ... if any text was chopped. * - * @param string $text - * @param int $num_chars Return a string up to $num_chars long + * @param string $text The full text to excerpt + * @param int $num_chars Return a string up to $num_chars long + * * @return string * @since 1.7.2 */ @@ -126,7 +130,8 @@ function elgg_get_excerpt($text, $num_chars = 250) { /** * Handles formatting of ampersands in urls * - * @param string $url + * @param string $url The URL + * * @return string * @since 1.7.1 */ @@ -138,6 +143,7 @@ function elgg_format_url($url) { * When given a title, returns a version suitable for inclusion in a URL * * @param string $title The title + * * @return string The optimised title * @deprecated 1.8 */ @@ -150,6 +156,7 @@ function friendly_title($title) { * When given a title, returns a version suitable for inclusion in a URL * * @param string $title The title + * * @return string The optimised title * @since 1.7.2 */ @@ -163,9 +170,9 @@ function elgg_get_friendly_title($title) { } //$title = iconv('UTF-8', 'ASCII//TRANSLIT', $title); - $title = preg_replace("/[^\w ]/","",$title); - $title = str_replace(" ","-",$title); - $title = str_replace("--","-",$title); + $title = preg_replace("/[^\w ]/", "", $title); + $title = str_replace(" ", "-", $title); + $title = str_replace("--", "-", $title); $title = trim($title); $title = strtolower($title); return $title; @@ -175,6 +182,7 @@ function elgg_get_friendly_title($title) { * Displays a UNIX timestamp in a friendly way (eg "less than a minute ago") * * @param int $time A UNIX epoch timestamp + * * @return string The friendly time * @deprecated 1.8 */ @@ -187,8 +195,9 @@ function friendly_time($time) { * Formats a UNIX timestamp in a friendly way (eg "less than a minute ago") * * @see elgg_view_friendly_time() - * + * * @param int $time A UNIX epoch timestamp + * * @return string The friendly time string * @since 1.7.2 */ @@ -251,6 +260,7 @@ function elgg_get_friendly_time($time) { * Original string included in $params['original_string'] * * @param string $string Formatted string + * * @return string String run through strip_tags() and any plugin hooks. */ function elgg_strip_tags($string) { @@ -266,7 +276,9 @@ function elgg_strip_tags($string) { * Filters a string into an array of significant words * * @deprecated 1.8 - * @param string $string + * + * @param string $string A string + * * @return array */ function filter_string($string) { @@ -278,17 +290,22 @@ function filter_string($string) { // Remove links and email addresses // match protocol://address/path/file.extension?some=variable&another=asf% - $string = preg_replace("/\s([a-zA-Z]+:\/\/[a-z][a-z0-9\_\.\-]*[a-z]{2,6}[a-zA-Z0-9\/\*\-\?\&\%\=]*)([\s|\.|\,])/iu"," ", $string); + $string = preg_replace("/\s([a-zA-Z]+:\/\/[a-z][a-z0-9\_\.\-]*[a-z]{2,6}" + . "[a-zA-Z0-9\/\*\-\?\&\%\=]*)([\s|\.|\,])/iu", " ", $string); + // match www.something.domain/path/file.extension?some=variable&another=asf% - $string = preg_replace("/\s(www\.[a-z][a-z0-9\_\.\-]*[a-z]{2,6}[a-zA-Z0-9\/\*\-\?\&\%\=]*)([\s|\.|\,])/iu"," ", $string); + $string = preg_replace("/\s(www\.[a-z][a-z0-9\_\.\-]*[a-z]{2,6}" + . "[a-zA-Z0-9\/\*\-\?\&\%\=]*)([\s|\.|\,])/iu", " ", $string); + // match name@address - $string = preg_replace("/\s([a-zA-Z][a-zA-Z0-9\_\.\-]*[a-zA-Z]*\@[a-zA-Z][a-zA-Z0-9\_\.\-]*[a-zA-Z]{2,6})([\s|\.|\,])/iu"," ", $string); + $string = preg_replace("/\s([a-zA-Z][a-zA-Z0-9\_\.\-]*[a-zA-Z]" + . "*\@[a-zA-Z][a-zA-Z0-9\_\.\-]*[a-zA-Z]{2,6})([\s|\.|\,])/iu", " ", $string); // Sanitise the string; remove unwanted characters $string = preg_replace('/\W/ui', ' ', $string); // Explode it into an array - $terms = explode(' ',$string); + $terms = explode(' ', $string); // Remove any blacklist terms //$terms = array_filter($terms, 'remove_blacklist'); @@ -300,7 +317,9 @@ function filter_string($string) { * Returns true if the word in $input is considered significant * * @deprecated 1.8 - * @param string $input + * + * @param string $input A word + * * @return true|false */ function remove_blacklist($input) { @@ -312,7 +331,7 @@ function remove_blacklist($input) { return $input; } - if (strlen($input) < 3 || in_array($input,$CONFIG->wordblacklist)) { + if (strlen($input) < 3 || in_array($input, $CONFIG->wordblacklist)) { return false; } diff --git a/engine/lib/pagehandler.php b/engine/lib/pagehandler.php index 53f68630b..5685ecd9f 100644 --- a/engine/lib/pagehandler.php +++ b/engine/lib/pagehandler.php @@ -2,8 +2,8 @@ /** * Elgg page handler functions * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage Routing */ /** @@ -12,7 +12,8 @@ * If a page handler returns FALSE, the request is handed over to the default_page_handler. * * @param string $handler The name of the handler type (eg 'blog') - * @param array $page The parameters to the page, as an array (exploded by '/' slashes) + * @param array $page The parameters to the page, as an array (exploded by '/' slashes) + * * @return true|false Depending on whether a registered page handler was found */ function page_handler($handler, $page) { @@ -20,7 +21,7 @@ function page_handler($handler, $page) { set_context($handler); - $page = explode('/',$page); + $page = explode('/', $page); // remove empty array element when page url ends in a / (see #1480) if ($page[count($page) - 1] === '') { array_pop($page); @@ -52,7 +53,7 @@ function page_handler($handler, $page) { * Registers a page handler for a particular identifier * * For example, you can register a function called 'blog_page_handler' for handler type 'blog' - * Now for all URLs of type http://yoururl/pg/blog/*, the blog_page_handler() function will be called. + * For all URLs http://yoururl/pg/blog/*, the blog_page_handler() function will be called. * The part of the URL marked with * above will be exploded on '/' characters and passed as an * array to that function. * For example, the URL http://yoururl/blog/username/friends/ would result in the call: @@ -66,8 +67,9 @@ function page_handler($handler, $page) { * The context is set to the page handler identifier before the registered * page handler function is called. For the above example, the context is set to 'blog'. * - * @param string $handler The page type to handle + * @param string $handler The page type to handle * @param string $function Your function name + * * @return true|false Depending on success */ function register_page_handler($handler, $function) { @@ -87,13 +89,15 @@ function register_page_handler($handler, $function) { * Unregister a page handler for an identifier * * Note: to replace a page handler, call register_page_handler() - * + * * @param string $handler The page type identifier + * * @since 1.7.2 + * @return void */ function unregister_page_handler($handler) { global $CONFIG; - + if (!isset($CONFIG->pagehandler)) { return; } @@ -105,8 +109,9 @@ function unregister_page_handler($handler) { * A default page handler * Tries to locate a suitable file to include. Only works for core pages, not plugins. * - * @param array $page The page URL elements + * @param array $page The page URL elements * @param string $handler The base handler + * * @return true|false Depending on success */ function default_page_handler($page, $handler) { @@ -116,7 +121,7 @@ function default_page_handler($page, $handler) { // protect against including arbitary files $page = str_replace("..", "", $page); - + $callpath = $CONFIG->path . $handler . "/" . $page; if (is_dir($callpath)) { $callpath = sanitise_filepath($callpath); diff --git a/engine/lib/pageowner.php b/engine/lib/pageowner.php index fb2e6255a..6b0ef491f 100644 --- a/engine/lib/pageowner.php +++ b/engine/lib/pageowner.php @@ -3,14 +3,15 @@ * Elgg page owner library * Contains functions for managing page ownership and context * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage PageOwner */ - /** * Gets the guid of the entity that owns the current page. + * * @param int $guid Optional parameter used by elgg_set_page_owner_guid(). + * * @return int The current page owner guid (0 if none). * @since 1.8 */ @@ -33,7 +34,11 @@ function elgg_get_page_owner_guid($guid = 0) { } /** + * Gets the guid of the entity that owns the current page. + * * @deprecated 1.8 Use get_page_owner_guid() + * + * @return int The current page owner guid (0 if none). */ function page_owner() { elgg_deprecated_notice('page_owner() was deprecated by elgg_get_page_owner_guid().', 1.8); @@ -42,7 +47,9 @@ function page_owner() { /** * Gets the owner entity for the current page. + * * @return ElggEntity|false The current page owner or false if none. + * * @since 1.8 */ function elgg_get_page_owner() { @@ -55,7 +62,12 @@ function elgg_get_page_owner() { } /** + * Gets the owner entity for the current page. + * * @deprecated 1.8 Use elgg_get_page_owner() + * @return ElggEntity|false The current page owner or false if none. + * + * @since 1.8 */ function page_owner_entity() { elgg_deprecated_notice('page_owner_entity() was deprecated by elgg_get_page_owner().', 1.8); @@ -64,8 +76,11 @@ function page_owner_entity() { /** * Set the guid of the entity that owns this page - * @param int $guid + * + * @param int $guid The guid of the page owner + * * @since 1.8 + * @return void */ function elgg_set_page_owner_guid($guid) { elgg_get_page_owner_guid($guid); @@ -73,14 +88,24 @@ function elgg_set_page_owner_guid($guid) { /** + * Registers a page owner handler function + * + * @param string $functionname The callback function + * * @deprecated 1.8 Use the 'page_owner', 'system' plugin hook + * @return void */ function add_page_owner_handler($functionname) { elgg_deprecated_notice("add_page_owner_handler() was deprecated by the plugin hook 'page_owner', 'system'.", 1.8); } /** + * Set a page owner entity + * + * @param int $entitytoset The GUID of the entity + * * @deprecated 1.8 Use elgg_set_page_owner_guid() + * @return void */ function set_page_owner($entitytoset = -1) { elgg_deprecated_notice('set_page_owner() was deprecated by elgg_set_page_owner_guid().', 1.8); @@ -91,6 +116,7 @@ function set_page_owner($entitytoset = -1) { * Sets the functional context of a page * * @param string $context The context of the page + * * @return string|false Either the context string, or false on failure */ function set_context($context) { @@ -121,12 +147,22 @@ function get_context() { return "main"; } +/** + * Handles default page owners + * + * @param string $hook page_owner + * @param string $entity_type system + * @param mixed $returnvalue Previous function's return value + * @param mixed $params Params + * + * @return int + */ function default_page_owner_handler($hook, $entity_type, $returnvalue, $params) { if ($returnvalue) { return $returnvalue; } - + $username = get_input("username"); if ($username) { if (substr_count($username, 'group:')) { @@ -152,6 +188,11 @@ function default_page_owner_handler($hook, $entity_type, $returnvalue, $params) return $returnvalue; } +/** + * Loads the page owner functions + * + * @return void + */ function page_owner_init() { register_plugin_hook('page_owner', 'system', 'default_page_owner_handler'); } diff --git a/engine/lib/pam.php b/engine/lib/pam.php index e0bb0cf21..21cfdbbb9 100644 --- a/engine/lib/pam.php +++ b/engine/lib/pam.php @@ -2,20 +2,20 @@ /** * Elgg Simple PAM library * Contains functions for managing authentication. - * This is not a full implementation of PAM. It supports a single facility + * This is not a full implementation of PAM. It supports a single facility * (authentication) and allows multiple policies (user authentication is the - * default). There are two control flags possible for each module: sufficient - * or required. The entire chain for a policy is processed (or until a - * required module fails). A module fails by returning false or throwing an - * exception. The order that modules are processed is determined by the order - * they are registered. For an example of a PAM, see pam_auth_userpass() in + * default). There are two control flags possible for each module: sufficient + * or required. The entire chain for a policy is processed (or until a + * required module fails). A module fails by returning false or throwing an + * exception. The order that modules are processed is determined by the order + * they are registered. For an example of a PAM, see pam_auth_userpass() in * sessions.php. - * + * * For more information on PAMs see: * http://www.freebsd.org/doc/en/articles/pam/index.html * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage Authentication.PAM */ $_PAM_HANDLERS = array(); @@ -24,10 +24,11 @@ $_PAM_HANDLERS_MSG = array(); /** * Register a PAM handler. * - * @param string $handler The handler function in the format - * pam_handler($credentials = NULL); + * @param string $handler The handler function in the format + * pam_handler($credentials = NULL); * @param string $importance The importance - "sufficient" (default) or "required" - * @param string $policy - the policy type, default is "user" + * @param string $policy The policy type, default is "user" + * * @return boolean */ function register_pam_handler($handler, $importance = "sufficient", $policy = "user") { @@ -37,7 +38,7 @@ function register_pam_handler($handler, $importance = "sufficient", $policy = "u if (!isset($_PAM_HANDLERS[$policy])) { $_PAM_HANDLERS[$policy] = array(); } - + if (is_callable($handler)) { $_PAM_HANDLERS[$policy][$handler] = new stdClass; @@ -54,7 +55,9 @@ function register_pam_handler($handler, $importance = "sufficient", $policy = "u * Unregisters a PAM handler. * * @param string $handler The PAM handler function name - * @param string $policy - the policy type, default is "user" + * @param string $policy The policy type, default is "user" + * + * @return void * @since 1.7.0 */ function unregister_pam_handler($handler, $policy = "user") { @@ -65,26 +68,27 @@ function unregister_pam_handler($handler, $policy = "user") { /** * Attempt to authenticate. - * This function will process all registered PAM handlers or stop when the first - * handler fails. A handler fails by either returning false or throwing an + * This function will process all registered PAM handlers or stop when the first + * handler fails. A handler fails by either returning false or throwing an * exception. The advantage of throwing an exception is that it returns a message - * through the global $_PAM_HANDLERS_MSG which can be used in communication with + * through the global $_PAM_HANDLERS_MSG which can be used in communication with * a user. The order that handlers are processed is determined by the order that * they were registered. * - * If $credentials are provided the PAM handler should authenticate using the - * provided credentials, if not then credentials should be prompted for or + * If $credentials are provided the PAM handler should authenticate using the + * provided credentials, if not then credentials should be prompted for or * otherwise retrieved (eg from the HTTP header or $_SESSION). * - * @param mixed $credentials Mixed PAM handler specific credentials (e.g. username, password) - * @param string $policy - the policy type, default is "user" + * @param mixed $credentials Mixed PAM handler specific credentials (e.g. username, password) + * @param string $policy The policy type, default is "user" + * * @return bool true if authenticated, false if not. */ function pam_authenticate($credentials = NULL, $policy = "user") { global $_PAM_HANDLERS, $_PAM_HANDLERS_MSG; $_PAM_HANDLERS_MSG = array(); - + $authenticated = false; foreach ($_PAM_HANDLERS[$policy] as $k => $v) { diff --git a/engine/lib/plugins.php b/engine/lib/plugins.php index e6a0132d6..e75a2993c 100644 --- a/engine/lib/plugins.php +++ b/engine/lib/plugins.php @@ -3,8 +3,8 @@ * Elgg plugins library * Contains functions for managing plugins * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage Plugins */ /// Cache enabled plugins per page @@ -62,6 +62,7 @@ function get_plugin_list() { * elgg_filepath_cache_reset(); * * @param array $pluginorder Optionally, a list of existing plugins and their orders + * * @return array The new list of plugins and their orders */ function regenerate_plugin_list($pluginorder = FALSE) { @@ -83,10 +84,11 @@ function regenerate_plugin_list($pluginorder = FALSE) { $max = 0; if (sizeof($pluginorder)) { - foreach($pluginorder as $key => $plugin) { + foreach ($pluginorder as $key => $plugin) { if (is_dir($CONFIG->pluginspath . "/" . $plugin)) { - if ($key > $max) + if ($key > $max) { $max = $key; + } } else { unset($pluginorder[$key]); } @@ -111,7 +113,7 @@ function regenerate_plugin_list($pluginorder = FALSE) { $key = 10; $plugins = array(); if (sizeof($pluginorder)) { - foreach($pluginorder as $plugin) { + foreach ($pluginorder as $plugin) { $plugins[$key] = $plugin; $key = $key + 10; } @@ -131,9 +133,10 @@ function regenerate_plugin_list($pluginorder = FALSE) { /** * For now, loads plugins directly * - * @todo Add proper plugin handler that launches plugins in an admin-defined order and activates them on admin request - * @package Elgg - * @subpackage Core + * @todo Add proper plugin handler that launches plugins in an + * admin-defined order and activates them on admin request + * + * @return void */ function load_plugins() { global $CONFIG; @@ -153,7 +156,7 @@ function load_plugins() { $plugins = get_plugin_list(); if (sizeof($plugins)) { - foreach($plugins as $mod) { + foreach ($plugins as $mod) { if (is_plugin_enabled($mod)) { if (file_exists($CONFIG->pluginspath . $mod)) { if (!include($CONFIG->pluginspath . $mod . "/start.php")) { @@ -189,7 +192,7 @@ function load_plugins() { if (is_dir($CONFIG->pluginspath . $mod . "/languages")) { register_translations($CONFIG->pluginspath . $mod . "/languages/"); } - + if (is_dir($CONFIG->pluginspath . "$mod/classes")) { elgg_register_classes($CONFIG->pluginspath . "$mod/classes"); } @@ -206,34 +209,37 @@ function load_plugins() { } /** - * Get the name of the most recent plugin to be called in the call stack (or the plugin that owns the current page, if any). + * Get the name of the most recent plugin to be called in the + * call stack (or the plugin that owns the current page, if any). * * i.e., if the last plugin was in /mod/foobar/, get_plugin_name would return foo_bar. * - * @param boolean $mainfilename If set to true, this will instead determine the context from the main script filename called by the browser. Default = false. + * @param boolean $mainfilename If set to true, this will instead determine the + * context from the main script filename called by + * the browser. Default = false. + * * @return string|false Plugin name, or false if no plugin name was called */ function get_plugin_name($mainfilename = false) { if (!$mainfilename) { if ($backtrace = debug_backtrace()) { - foreach($backtrace as $step) { + foreach ($backtrace as $step) { $file = $step['file']; - $file = str_replace("\\","/",$file); - $file = str_replace("//","/",$file); - if (preg_match("/mod\/([a-zA-Z0-9\-\_]*)\/start\.php$/",$file,$matches)) { + $file = str_replace("\\", "/", $file); + $file = str_replace("//", "/", $file); + if (preg_match("/mod\/([a-zA-Z0-9\-\_]*)\/start\.php$/", $file, $matches)) { return $matches[1]; } } } } else { - //if (substr_count($file,'handlers/pagehandler')) { - if (preg_match("/pg\/([a-zA-Z0-9\-\_]*)\//",$_SERVER['REQUEST_URI'],$matches)) { + if (preg_match("/pg\/([a-zA-Z0-9\-\_]*)\//", $_SERVER['REQUEST_URI'], $matches)) { return $matches[1]; } else { $file = $_SERVER["SCRIPT_NAME"]; - $file = str_replace("\\","/",$file); - $file = str_replace("//","/",$file); - if (preg_match("/mod\/([a-zA-Z0-9\-\_]*)\//",$file,$matches)) { + $file = str_replace("\\", "/", $file); + $file = str_replace("//", "/", $file); + if (preg_match("/mod\/([a-zA-Z0-9\-\_]*)\//", $file, $matches)) { return $matches[1]; } } @@ -263,12 +269,13 @@ function get_plugin_name($mainfilename = false) { * </plugin_manifest> * * @param string $plugin Plugin name. + * * @return array of values */ function load_plugin_manifest($plugin) { global $CONFIG; - $xml = xml_to_object(file_get_contents($CONFIG->pluginspath . $plugin. "/manifest.xml")); + $xml = xml_to_object(file_get_contents($CONFIG->pluginspath . $plugin . "/manifest.xml")); if ($xml) { // set up some defaults to normalize expected values to arrays @@ -308,7 +315,9 @@ function load_plugin_manifest($plugin) { /** * This function checks a plugin manifest 'elgg_version' value against the current install * returning TRUE if the elgg_version is >= the current install's version. - * @param $manifest_elgg_version_string The build version (eg 2009010201). + * + * @param string $manifest_elgg_version_string The build version (eg 2009010201). + * * @return bool */ function check_plugin_compatibility($manifest_elgg_version_string) { @@ -327,8 +336,10 @@ function check_plugin_compatibility($manifest_elgg_version_string) { /** * Shorthand function for finding the plugin settings. * - * @param string $plugin_name Optional plugin name, if not specified then it is detected from where you - * are calling from. + * @param string $plugin_name Optional plugin name, if not specified + * then it is detected from where you are calling from. + * + * @return mixed */ function find_plugin_settings($plugin_name = "") { $options = array('type' => 'object', 'subtype' => 'plugin', 'limit' => 9999); @@ -340,7 +351,7 @@ function find_plugin_settings($plugin_name = "") { if ($plugins) { foreach ($plugins as $plugin) { - if (strcmp($plugin->title, $plugin_name)==0) { + if (strcmp($plugin->title, $plugin_name) == 0) { return $plugin; } } @@ -353,7 +364,8 @@ function find_plugin_settings($plugin_name = "") { * Find the plugin settings for a user. * * @param string $plugin_name Plugin name. - * @param int $user_guid The guid who's settings to retrieve. + * @param int $user_guid The guid who's settings to retrieve. + * * @return array of settings in an associative array minus prefix. */ function find_plugin_usersettings($plugin_name = "", $user_guid = 0) { @@ -392,10 +404,13 @@ function find_plugin_usersettings($plugin_name = "", $user_guid = 0) { /** * Set a user specific setting for a plugin. * - * @param string $name The name - note, can't be "title". - * @param mixed $value The value. - * @param int $user_guid Optional user. - * @param string $plugin_name Optional plugin name, if not specified then it is detected from where you are calling from. + * @param string $name The name - note, can't be "title". + * @param mixed $value The value. + * @param int $user_guid Optional user. + * @param string $plugin_name Optional plugin name, if not specified then it + * is detected from where you are calling from. + * + * @return bool */ function set_plugin_usersetting($name, $value, $user_guid = 0, $plugin_name = "") { $plugin_name = sanitise_string($plugin_name); @@ -433,12 +448,13 @@ function set_plugin_usersetting($name, $value, $user_guid = 0, $plugin_name = "" /** * Clears a user-specific plugin setting * - * @param str $name Name of the plugin setting - * @param int $user_guid Defaults to logged in user + * @param str $name Name of the plugin setting + * @param int $user_guid Defaults to logged in user * @param str $plugin_name Defaults to contextual plugin name + * * @return bool Success */ -function clear_plugin_usersetting($name, $user_guid=0, $plugin_name='') { +function clear_plugin_usersetting($name, $user_guid = 0, $plugin_name = '') { $plugin_name = sanitise_string($plugin_name); $name = sanitise_string($name); @@ -463,8 +479,12 @@ function clear_plugin_usersetting($name, $user_guid=0, $plugin_name='') { /** * Get a user specific setting for a plugin. * - * @param string $name The name. - * @param string $plugin_name Optional plugin name, if not specified then it is detected from where you are calling from. + * @param string $name The name. + * @param int $user_guid Guid of owning user + * @param string $plugin_name Optional plugin name, if not specified + * then it is detected from where you are calling from. + * + * @return mixed */ function get_plugin_usersetting($name, $user_guid = 0, $plugin_name = "") { $plugin_name = sanitise_string($plugin_name); @@ -482,7 +502,7 @@ function get_plugin_usersetting($name, $user_guid = 0, $plugin_name = "") { if (($user) && ($user instanceof ElggUser)) { $prefix = "plugin:settings:$plugin_name:$name"; - return get_private_setting($user->guid, $prefix); //$user->$prefix; + return get_private_setting($user->guid, $prefix); } return false; @@ -491,9 +511,12 @@ function get_plugin_usersetting($name, $user_guid = 0, $plugin_name = "") { /** * Set a setting for a plugin. * - * @param string $name The name - note, can't be "title". - * @param mixed $value The value. - * @param string $plugin_name Optional plugin name, if not specified then it is detected from where you are calling from. + * @param string $name The name - note, can't be "title". + * @param mixed $value The value. + * @param string $plugin_name Optional plugin name, if not specified + * then it is detected from where you are calling from. + * + * @return int|false */ function set_plugin_setting($name, $value, $plugin_name = "") { if (!$plugin_name) { @@ -505,7 +528,7 @@ function set_plugin_setting($name, $value, $plugin_name = "") { $plugin = new ElggPlugin(); } - if ($name!='title') { + if ($name != 'title') { // Hook to validate setting $value = trigger_plugin_hook('plugin:setting', 'plugin', array( 'plugin' => $plugin_name, @@ -527,8 +550,11 @@ function set_plugin_setting($name, $value, $plugin_name = "") { /** * Get setting for a plugin. * - * @param string $name The name. - * @param string $plugin_name Optional plugin name, if not specified then it is detected from where you are calling from. + * @param string $name The name. + * @param string $plugin_name Optional plugin name, if not specified + * then it is detected from where you are calling from. + * + * @return mixed */ function get_plugin_setting($name, $plugin_name = "") { $plugin = find_plugin_settings($plugin_name); @@ -543,8 +569,11 @@ function get_plugin_setting($name, $plugin_name = "") { /** * Clear a plugin setting. * - * @param string $name The name. - * @param string $plugin_name Optional plugin name, if not specified then it is detected from where you are calling from. + * @param string $name The name. + * @param string $plugin_name Optional plugin name, if not specified + * then it is detected from where you are calling from. + * + * @return bool */ function clear_plugin_setting($name, $plugin_name = "") { $plugin = find_plugin_settings($plugin_name); @@ -559,7 +588,10 @@ function clear_plugin_setting($name, $plugin_name = "") { /** * Clear all plugin settings. * - * @param string $plugin_name Optional plugin name, if not specified then it is detected from where you are calling from. + * @param string $plugin_name Optional plugin name, if not specified + * then it is detected from where you are calling from. + * + * @return bool * @since 1.7.0 */ function clear_all_plugin_settings($plugin_name = "") { @@ -574,6 +606,8 @@ function clear_all_plugin_settings($plugin_name = "") { /** * Return an array of installed plugins. + * + * @return array */ function get_installed_plugins() { global $CONFIG; @@ -583,7 +617,7 @@ function get_installed_plugins() { if (!empty($CONFIG->pluginspath)) { $plugins = get_plugin_list(); - foreach($plugins as $mod) { + foreach ($plugins as $mod) { // require manifest. if (!$manifest = load_plugin_manifest($mod)) { continue; @@ -606,8 +640,11 @@ function get_installed_plugins() { * elgg_view_regenerate_simplecache(); * elgg_filepath_cache_reset(); * - * @param string $plugin The plugin name. - * @param int $site_guid The site id, if not specified then this is detected. + * @param string $plugin The plugin name. + * @param int $site_guid The site id, if not specified then this is detected. + * + * @return array + * @throws InvalidClassException */ function enable_plugin($plugin, $site_guid = 0) { global $CONFIG, $ENABLED_PLUGINS_CACHE; @@ -620,7 +657,8 @@ function enable_plugin($plugin, $site_guid = 0) { $site = get_entity($site_guid); if (!($site instanceof ElggSite)) { - throw new InvalidClassException(sprintf(elgg_echo('InvalidClassException:NotValidElggStar'), $site_guid, "ElggSite")); + $msg = sprintf(elgg_echo('InvalidClassException:NotValidElggStar'), $site_guid, "ElggSite"); + throw new InvalidClassException($msg); } if (!$plugin_info = load_plugin_manifest($plugin)) { @@ -642,7 +680,8 @@ function enable_plugin($plugin, $site_guid = 0) { if ($return = $site->setMetaData('enabled_plugins', $enabled)) { // for other plugins that want to hook into this. - if ($return && !trigger_elgg_event('enable', 'plugin', array('plugin' => $plugin, 'manifest' => $plugin_info))) { + $params = array('plugin' => $plugin, 'manifest' => $plugin_info); + if ($return && !trigger_elgg_event('enable', 'plugin', $params)) { $return = FALSE; } @@ -688,8 +727,11 @@ function enable_plugin($plugin, $site_guid = 0) { * elgg_view_regenerate_simplecache(); * elgg_filepath_cache_reset(); * - * @param string $plugin The plugin name. - * @param int $site_guid The site id, if not specified then this is detected. + * @param string $plugin The plugin name. + * @param int $site_guid The site id, if not specified then this is detected. + * + * @return bool + * @throws InvalidClassException */ function disable_plugin($plugin, $site_guid = 0) { global $CONFIG, $ENABLED_PLUGINS_CACHE; @@ -702,7 +744,8 @@ function disable_plugin($plugin, $site_guid = 0) { $site = get_entity($site_guid); if (!($site instanceof ElggSite)) { - throw new InvalidClassException(sprintf(elgg_echo('InvalidClassException:NotValidElggStar'), $site_guid, "ElggSite")); + $msg = sprintf(elgg_echo('InvalidClassException:NotValidElggStar'), $site_guid, "ElggSite"); + throw new InvalidClassException(); } if (!$plugin_info = load_plugin_manifest($plugin)) { @@ -731,7 +774,8 @@ function disable_plugin($plugin, $site_guid = 0) { if ($return) { // for other plugins that want to hook into this. - if ($return && !trigger_elgg_event('disable', 'plugin', array('plugin' => $plugin, 'manifest' => $plugin_info))) { + $params = array('plugin' => $plugin, 'manifest' => $plugin_info); + if ($return && !trigger_elgg_event('disable', 'plugin', $params)) { $return = FALSE; } @@ -761,9 +805,11 @@ function disable_plugin($plugin, $site_guid = 0) { /** * Return whether a plugin is enabled or not. * - * @param string $plugin The plugin name. - * @param int $site_guid The site id, if not specified then this is detected. + * @param string $plugin The plugin name. + * @param int $site_guid The site id, if not specified then this is detected. + * * @return bool + * @throws InvalidClassException */ function is_plugin_enabled($plugin, $site_guid = 0) { global $CONFIG, $ENABLED_PLUGINS_CACHE; @@ -780,7 +826,8 @@ function is_plugin_enabled($plugin, $site_guid = 0) { if (!$ENABLED_PLUGINS_CACHE) { $site = get_entity($site_guid); if (!($site instanceof ElggSite)) { - throw new InvalidClassException(sprintf(elgg_echo('InvalidClassException:NotValidElggStar'), $site_guid, "ElggSite")); + $msg = sprintf(elgg_echo('InvalidClassException:NotValidElggStar'), $site_guid, "ElggSite"); + throw new InvalidClassException($msg); } $enabled_plugins = $site->enabled_plugins; @@ -800,7 +847,9 @@ function is_plugin_enabled($plugin, $site_guid = 0) { } /** - * Run once and only once. + * Register object, plugin entities as ElggPlugin classes + * + * @return void */ function plugin_run_once() { // Register a class @@ -810,6 +859,8 @@ function plugin_run_once() { /** * Initialise the file modules. * Listens to system boot and registers any appropriate file types and classes + * + * @return void */ function plugin_init() { // Now run this stuff, but only once @@ -819,13 +870,13 @@ function plugin_init() { register_action("plugins/settings/save", false, "", true); register_action("plugins/usersettings/save"); - register_action('admin/plugins/enable', false, "", true); // Enable - register_action('admin/plugins/disable', false, "", true); // Disable - register_action('admin/plugins/enableall', false, "", true); // Enable all - register_action('admin/plugins/disableall', false, "", true); // Disable all + register_action('admin/plugins/enable', false, "", true); + register_action('admin/plugins/disable', false, "", true); + register_action('admin/plugins/enableall', false, "", true); + register_action('admin/plugins/disableall', false, "", true); - register_action('admin/plugins/reorder', false, "", true); // Reorder + register_action('admin/plugins/reorder', false, "", true); } // Register a startup event -register_elgg_event_handler('init','system','plugin_init'); +register_elgg_event_handler('init', 'system', 'plugin_init'); diff --git a/engine/lib/relationships.php b/engine/lib/relationships.php index 3a3b8c4c0..6c43b1757 100644 --- a/engine/lib/relationships.php +++ b/engine/lib/relationships.php @@ -3,14 +3,15 @@ * Elgg relationships. * Stub containing relationship functions, making import and export easier. * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage DataModel.Relationship */ /** * Convert a database row to a new ElggRelationship * - * @param stdClass $row + * @param stdClass $row Database row from the relationship table + * * @return stdClass or ElggMetadata */ function row_to_elggrelationship($row) { @@ -24,20 +25,25 @@ function row_to_elggrelationship($row) { /** * Return a relationship. * - * @param int $id + * @param int $id The ID of a relationship + * + * @return mixed */ function get_relationship($id) { global $CONFIG; $id = (int)$id; - return row_to_elggrelationship(get_data_row("SELECT * from {$CONFIG->dbprefix}entity_relationships where id=$id")); + $query = "SELECT * from {$CONFIG->dbprefix}entity_relationships where id=$id"; + return row_to_elggrelationship(get_data_row($query)); } /** * Delete a specific relationship. * - * @param int $id + * @param int $id The relationship ID + * + * @return bool */ function delete_relationship($id) { global $CONFIG; @@ -59,9 +65,11 @@ function delete_relationship($id) { * * This function lets you make the statement "$guid_one is a $relationship of $guid_two". * - * @param int $guid_one - * @param string $relationship - * @param int $guid_two + * @param int $guid_one First GUID + * @param string $relationship Relationship name + * @param int $guid_two Second GUID + * + * @return bool */ function add_entity_relationship($guid_one, $relationship, $guid_two) { global $CONFIG; @@ -76,11 +84,11 @@ function add_entity_relationship($guid_one, $relationship, $guid_two) { return false; } - $result = insert_data("INSERT into {$CONFIG->dbprefix}entity_relationships + $result = insert_data("INSERT into {$CONFIG->dbprefix}entity_relationships (guid_one, relationship, guid_two, time_created) values ($guid_one, '$relationship', $guid_two, $time)"); - if ($result!==false) { + if ($result !== false) { $obj = get_relationship($result); if (trigger_elgg_event('create', $relationship, $obj)) { return true; @@ -93,11 +101,13 @@ function add_entity_relationship($guid_one, $relationship, $guid_two) { } /** - * Determine whether or not a relationship between two entities exists and returns the relationship object if it does + * Determine if a relationship between two entities exists + * and returns the relationship object if it does * - * @param int $guid_one The GUID of the entity "owning" the relationship + * @param int $guid_one The GUID of the entity "owning" the relationship * @param string $relationship The type of relationship - * @param int $guid_two The GUID of the entity the relationship is with + * @param int $guid_two The GUID of the entity the relationship is with + * * @return object|false Depending on success */ function check_entity_relationship($guid_one, $relationship, $guid_two) { @@ -107,7 +117,13 @@ function check_entity_relationship($guid_one, $relationship, $guid_two) { $relationship = sanitise_string($relationship); $guid_two = (int)$guid_two; - if ($row = get_data_row("SELECT * FROM {$CONFIG->dbprefix}entity_relationships WHERE guid_one=$guid_one AND relationship='$relationship' AND guid_two=$guid_two limit 1")) { + $query = "SELECT * FROM {$CONFIG->dbprefix}entity_relationships + WHERE guid_one=$guid_one + AND relationship='$relationship' + AND guid_two=$guid_two limit 1"; + + $row = $row = get_data_row($query); + if ($row) { return $row; } @@ -117,9 +133,11 @@ function check_entity_relationship($guid_one, $relationship, $guid_two) { /** * Remove an arbitrary relationship between two entities. * - * @param int $guid_one - * @param string $relationship - * @param int $guid_two + * @param int $guid_one First GUID + * @param string $relationship Relationship name + * @param int $guid_two Second GUID + * + * @return bool */ function remove_entity_relationship($guid_one, $relationship, $guid_two) { global $CONFIG; @@ -134,7 +152,12 @@ function remove_entity_relationship($guid_one, $relationship, $guid_two) { } if (trigger_elgg_event('delete', $relationship, $obj)) { - return delete_data("DELETE from {$CONFIG->dbprefix}entity_relationships where guid_one=$guid_one and relationship='$relationship' and guid_two=$guid_two"); + $query = "DELETE from {$CONFIG->dbprefix}entity_relationships + where guid_one=$guid_one + and relationship='$relationship' + and guid_two=$guid_two"; + + return delete_data($query); } else { return false; } @@ -143,11 +166,12 @@ function remove_entity_relationship($guid_one, $relationship, $guid_two) { /** * Removes all arbitrary relationships originating from a particular entity * - * @param int $guid_one The GUID of the entity - * @param string $relationship The name of the relationship (optionally) - * @param true|false $inverse Whether we're deleting inverse relationships (default false) - * @param string $type The type of entity to limit this relationship delete to (defaults to all) - * @return true|false Depending on success + * @param int $guid_one The GUID of the entity + * @param string $relationship The name of the relationship (optional) + * @param bool $inverse Whether we're deleting inverse relationships (default false) + * @param string $type The type of entity to the delete to (defaults to all) + * + * @return bool Depending on success */ function remove_entity_relationships($guid_one, $relationship = "", $inverse = false, $type = '') { global $CONFIG; @@ -175,10 +199,16 @@ function remove_entity_relationships($guid_one, $relationship = "", $inverse = f } if (!$inverse) { - $sql = "DELETE er from {$CONFIG->dbprefix}entity_relationships as er {$join} where guid_one={$guid_one} {$where}"; + $sql = "DELETE er from {$CONFIG->dbprefix}entity_relationships as er + {$join} + where guid_one={$guid_one} {$where}"; + return delete_data($sql); } else { - $sql = "DELETE er from {$CONFIG->dbprefix}entity_relationships as er {$join} where guid_two={$guid_one} {$where}"; + $sql = "DELETE er from {$CONFIG->dbprefix}entity_relationships as er + {$join} where + guid_two={$guid_one} {$where}"; + return delete_data($sql); } } @@ -186,7 +216,10 @@ function remove_entity_relationships($guid_one, $relationship = "", $inverse = f /** * Get all the relationships for a given guid. * - * @param int $guid + * @param int $guid The GUID of the relationship owner + * @param bool $inverse_relationship Inverse relationship owners? + * + * @return mixed */ function get_entity_relationships($guid, $inverse_relationship = FALSE) { global $CONFIG; @@ -255,13 +288,17 @@ function elgg_get_entities_from_relationship($options) { * * @todo add support for multiple relationships and guids. * - * @param $table Entities table name - * @param $relationship relationship string - * @param $entity_guid entity guid to check + * @param string $table Entities table name + * @param string $relationship Relationship string + * @param int $relationship_guid Entity guid to check + * @param string $inverse_relationship Inverse relationship check? + * * @return mixed * @since 1.7.0 */ -function elgg_get_entity_relationship_where_sql($table, $relationship = NULL, $relationship_guid = NULL, $inverse_relationship = FALSE) { +function elgg_get_entity_relationship_where_sql($table, $relationship = NULL, +$relationship_guid = NULL, $inverse_relationship = FALSE) { + if ($relationship == NULL && $entity_guid == NULL) { return ''; } @@ -273,10 +310,8 @@ function elgg_get_entity_relationship_where_sql($table, $relationship = NULL, $r if ($inverse_relationship) { $joins[] = "JOIN {$CONFIG->dbprefix}entity_relationships r on r.guid_one = e.guid"; - //$wheres[] = "{$table}.guid = {$CONFIG->dbprefix}entity_relationships.guid_two"; } else { $joins[] = "JOIN {$CONFIG->dbprefix}entity_relationships r on r.guid_two = e.guid"; - //$wheres[] = "{$table}.guid = {$CONFIG->dbprefix}entity_relationships.guid_one"; } if ($relationship) { @@ -291,7 +326,7 @@ function elgg_get_entity_relationship_where_sql($table, $relationship = NULL, $r } } - if ($where_str = implode(' AND ' , $wheres)) { + if ($where_str = implode(' AND ', $wheres)) { return array('wheres' => array("($where_str)"), 'joins' => $joins); } @@ -300,23 +335,27 @@ function elgg_get_entity_relationship_where_sql($table, $relationship = NULL, $r } /** - * @deprecated 1.7. Use elgg_get_entities_from_relationship(). - * @param $relationship - * @param $relationship_guid - * @param $inverse_relationship - * @param $type - * @param $subtype - * @param $owner_guid - * @param $order_by - * @param $limit - * @param $offset - * @param $count - * @param $site_guid - * @return unknown_type + * Return entities from relationships + * + * @deprecated 1.7 Use elgg_get_entities_from_relationship() + * + * @param string $relationship The relationship type + * @param int $relationship_guid The GUID of the relationship owner + * @param bool $inverse_relationship Invert relationship? + * @param string $type Entity type + * @param string $subtype Entity subtype + * @param int $owner_guid Entity owner GUID + * @param string $order_by Order by clause + * @param int $limit Limit + * @param int $offset Offset + * @param bool $count Return a count instead of entities? + * @param int $site_guid Site GUID + * + * @return mixed */ -function get_entities_from_relationship($relationship, $relationship_guid, $inverse_relationship = false, -$type = "", $subtype = "", $owner_guid = 0, $order_by = "", $limit = 10, $offset = 0, -$count = false, $site_guid = 0) { +function get_entities_from_relationship($relationship, $relationship_guid, +$inverse_relationship = false, $type = "", $subtype = "", $owner_guid = 0, +$order_by = "", $limit = 10, $offset = 0, $count = false, $site_guid = 0) { elgg_deprecated_notice('get_entities_from_relationship() was deprecated by elgg_get_entities_from_relationship()!', 1.7); @@ -364,57 +403,67 @@ $count = false, $site_guid = 0) { * * @see elgg_view_entity_list * - * @param string $relationship The relationship eg "friends_of" - * @param int $relationship_guid The guid of the entity to use query - * @param bool $inverse_relationship Reverse the normal function of the query to instead say "give me all entities for whome $relationship_guid is a $relationship of" - * @param string $type The type of entity (eg 'object') - * @param string $subtype The entity subtype - * @param int $owner_guid The owner (default: all) - * @param int $limit The number of entities to display on a page - * @param true|false $fullview Whether or not to display the full view (default: true) - * @param true|false $viewtypetoggle Whether or not to allow gallery view - * @param true|false $pagination Whether to display pagination (default: true) + * @param string $relationship The relationship eg "friends_of" + * @param int $relationship_guid The guid of the entity to use query + * @param bool $inverse_relationship Invert relationship owner + * @param string $type The type of entity (eg 'object') + * @param string $subtype The entity subtype + * @param int $owner_guid The owner (default: all) + * @param int $limit The number of entities to display on a page + * @param bool $fullview Whether or not to display the full view (default: true) + * @param bool $viewtypetoggle Whether or not to allow gallery view + * @param bool $pagination Whether to display pagination (default: true) + * * @return string The viewable list of entities */ -function list_entities_from_relationship($relationship, $relationship_guid, $inverse_relationship = false, $type = ELGG_ENTITIES_ANY_VALUE, $subtype = ELGG_ENTITIES_ANY_VALUE, $owner_guid = 0, $limit = 10, $fullview = true, $viewtypetoggle = false, $pagination = true) { +function list_entities_from_relationship($relationship, $relationship_guid, +$inverse_relationship = false, $type = ELGG_ENTITIES_ANY_VALUE, +$subtype = ELGG_ENTITIES_ANY_VALUE, $owner_guid = 0, $limit = 10, +$fullview = true, $viewtypetoggle = false, $pagination = true) { + $limit = (int) $limit; $offset = (int) get_input('offset'); $options = array( - 'relationship' => $relationship, - 'relationship_guid' => $relationship_guid, - 'inverse_relationship' => $inverse_relationship, - 'types' => $type, - 'subtypes' => $subtype, - 'owner_guid' => $owner_guid, - 'order_by' => '', - 'limit' => $limit, - 'offset' => $offset, + 'relationship' => $relationship, + 'relationship_guid' => $relationship_guid, + 'inverse_relationship' => $inverse_relationship, + 'types' => $type, + 'subtypes' => $subtype, + 'owner_guid' => $owner_guid, + 'order_by' => '', + 'limit' => $limit, + 'offset' => $offset, 'count' => TRUE ); $count = elgg_get_entities_from_relationship($options); $options['count'] = FALSE; $entities = elgg_get_entities_from_relationship($options); - return elgg_view_entity_list($entities, $count, $offset, $limit, $fullview, $viewtypetoggle, $pagination); + return elgg_view_entity_list($entities, $count, $offset, $limit, + $fullview, $viewtypetoggle, $pagination); } /** * Gets the number of entities by a the number of entities related to them in a particular way. - * This is a good way to get out the users with the most friends, or the groups with the most members. - * - * @param string $relationship The relationship eg "friends_of" - * @param bool $inverse_relationship Reverse the normal function of the query to instead say "give me all entities for whome $relationship_guid is a $relationship of" (default: true) - * @param string $type The type of entity (default: all) - * @param string $subtype The entity subtype (default: all) - * @param int $owner_guid The owner of the entities (default: none) - * @param int $limit - * @param int $offset - * @param boolean $count Set to true if you want to count the number of entities instead (default false) - * @param int $site_guid The site to get entities for. Leave as 0 (default) for the current site; -1 for all sites. + * This is a good way to get out the users with the most friends, or the groups with the + * most members. + * + * @param string $relationship The relationship eg "friends_of" + * @param bool $inverse_relationship Inverse relationship owners + * @param string $type The type of entity (default: all) + * @param string $subtype The entity subtype (default: all) + * @param int $owner_guid The owner of the entities (default: none) + * @param int $limit Limit + * @param int $offset Offset + * @param bool $count Return a count instead of entities + * @param int $site_guid Site GUID + * * @return array|int|false An array of entities, or the number of entities, or false on failure */ -function get_entities_by_relationship_count($relationship, $inverse_relationship = true, $type = "", $subtype = "", $owner_guid = 0, $limit = 10, $offset = 0, $count = false, $site_guid = 0) { +function get_entities_by_relationship_count($relationship, $inverse_relationship = true, $type = "", +$subtype = "", $owner_guid = 0, $limit = 10, $offset = 0, $count = false, $site_guid = 0) { + global $CONFIG; $relationship = sanitise_string($relationship); @@ -436,7 +485,7 @@ function get_entities_by_relationship_count($relationship, $inverse_relationship $where = array(); - if ($relationship!="") { + if ($relationship != "") { $where[] = "r.relationship='$relationship'"; } @@ -467,18 +516,19 @@ function get_entities_by_relationship_count($relationship, $inverse_relationship $query = "SELECT e.*, count(e.guid) as total "; } - $query .= " from {$CONFIG->dbprefix}entity_relationships r JOIN {$CONFIG->dbprefix}entities e on {$on} where "; + $query .= " from {$CONFIG->dbprefix}entity_relationships r + JOIN {$CONFIG->dbprefix}entities e on {$on} where "; if (!empty($where)) { foreach ($where as $w) { $query .= " $w and "; } } - $query .= get_access_sql_suffix("e"); // Add access controls + $query .= get_access_sql_suffix("e"); if (!$count) { $query .= " group by e.guid "; - $query .= " order by total desc limit {$offset}, {$limit}"; // Add order and limit + $query .= " order by total desc limit {$offset}, {$limit}"; return get_data($query, "entity_row_to_elggstar"); } else { if ($count = get_data_row($query)) { @@ -492,46 +542,56 @@ function get_entities_by_relationship_count($relationship, $inverse_relationship /** * Displays a human-readable list of entities * - * @param string $relationship The relationship eg "friends_of" - * @param bool $inverse_relationship Reverse the normal function of the query to instead say "give me all entities for whome $relationship_guid is a $relationship of" (default: true) - * @param string $type The type of entity (eg 'object') - * @param string $subtype The entity subtype - * @param int $owner_guid The owner (default: all) - * @param int $limit The number of entities to display on a page - * @param true|false $fullview Whether or not to display the full view (default: true) - * @param true|false $viewtypetoggle Whether or not to allow gallery view - * @param true|false $pagination Whether to display pagination (default: true) + * @param string $relationship The relationship eg "friends_of" + * @param bool $inverse_relationship Inverse relationship owners + * @param string $type The type of entity (eg 'object') + * @param string $subtype The entity subtype + * @param int $owner_guid The owner (default: all) + * @param int $limit The number of entities to display on a page + * @param bool $fullview Whether or not to display the full view (default: true) + * @param bool $viewtypetoggle Whether or not to allow gallery view + * @param bool $pagination Whether to display pagination (default: true) + * * @return string The viewable list of entities */ -function list_entities_by_relationship_count($relationship, $inverse_relationship = true, $type = "", $subtype = "", $owner_guid = 0, $limit = 10, $fullview = true, $viewtypetoggle = false, $pagination = true) { +function list_entities_by_relationship_count($relationship, $inverse_relationship = true, +$type = "", $subtype = "", $owner_guid = 0, $limit = 10, $fullview = true, +$viewtypetoggle = false, $pagination = true) { + $limit = (int) $limit; $offset = (int) get_input('offset'); - $count = get_entities_by_relationship_count($relationship,$inverse_relationship,$type,$subtype,$owner_guid,0,0,true); - $entities = get_entities_by_relationship_count($relationship,$inverse_relationship,$type,$subtype,$owner_guid,$limit,$offset); + $count = get_entities_by_relationship_count($relationship, $inverse_relationship, + $type, $subtype, $owner_guid, 0, 0, true); + $entities = get_entities_by_relationship_count($relationship, $inverse_relationship, + $type, $subtype, $owner_guid, $limit, $offset); return elgg_view_entity_list($entities, $count, $offset, $limit, $fullview, $viewtypetoggle, $pagination); } /** - * Gets the number of entities by a the number of entities related to them in a particular way also constrained by - * metadata - * - * @param string $relationship The relationship eg "friends_of" - * @param int $relationship_guid The guid of the entity to use query - * @param bool $inverse_relationship Reverse the normal function of the query to instead say "give me all entities for whome $relationship_guid is a $relationship of" (default: true) - * @param String $meta_name The metadata name - * @param String $meta_value The metadata value - * @param string $type The type of entity (default: all) - * @param string $subtype The entity subtype (default: all) - * @param int $owner_guid The owner of the entities (default: none) - * @param int $limit - * @param int $offset - * @param boolean $count Set to true if you want to count the number of entities instead (default false) - * @param int $site_guid The site to get entities for. Leave as 0 (default) for the current site; -1 for all sites. + * Gets the number of entities by a the number of entities related to + * them in a particular way also constrained by metadata + * + * @param string $relationship The relationship eg "friends_of" + * @param int $relationship_guid The guid of the entity to use query + * @param bool $inverse_relationship Inverse relationship owner + * @param String $meta_name The metadata name + * @param String $meta_value The metadata value + * @param string $type The type of entity (default: all) + * @param string $subtype The entity subtype (default: all) + * @param int $owner_guid The owner of the entities (default: none) + * @param int $limit Limit + * @param int $offset Offset + * @param bool $count Return a count instead of entities + * @param int $site_guid Site GUID + * * @return array|int|false An array of entities, or the number of entities, or false on failure */ -function get_entities_from_relationships_and_meta($relationship, $relationship_guid, $inverse_relationship = false, $meta_name = "", $meta_value = "", $type = "", $subtype = "", $owner_guid = 0, $limit = 10, $offset = 0, $count = false, $site_guid = 0) { +function get_entities_from_relationships_and_meta($relationship, $relationship_guid, +$inverse_relationship = false, $meta_name = "", $meta_value = "", $type = "", +$subtype = "", $owner_guid = 0, $limit = 10, $offset = 0, $count = false, $site_guid = 0) { + elgg_deprecated_notice('get_entities_from_relationship_and_meta() was deprecated by elgg_get_entities_from_relationship()!', 1.7); $options = array(); @@ -552,7 +612,7 @@ function get_entities_from_relationships_and_meta($relationship, $relationship_g $options['types'] = $type; } - if (subtype) { + if ($subtype) { $options['subtypes'] = $subtype; } @@ -586,9 +646,10 @@ function get_entities_from_relationships_and_meta($relationship, $relationship_g /** * Sets the URL handler for a particular relationship type * - * @param string $function_name The function to register + * @param string $function_name The function to register * @param string $relationship_type The relationship type. - * @return true|false Depending on success + * + * @return bool Depending on success */ function register_relationship_url_handler($function_name, $relationship_type = "all") { global $CONFIG; @@ -609,8 +670,9 @@ function register_relationship_url_handler($function_name, $relationship_type = /** * Get the url for a given relationship. * - * @param unknown_type $id - * @return unknown + * @param int $id Relationship ID + * + * @return string */ function get_relationship_url($id) { global $CONFIG; @@ -650,16 +712,18 @@ function get_relationship_url($id) { } /**** HELPER FUNCTIONS FOR RELATIONSHIPS OF TYPE 'ATTACHED' ****/ +// @todo what is this? /** * Function to determine if the object trying to attach to other, has already done so + * * @param int $guid_one This is the target object * @param int $guid_two This is the object trying to attach to $guid_one - * @return true | false + * + * @return bool **/ - -function already_attached($guid_one, $guid_two){ - if ($attached = check_entity_relationship($guid_one, "attached", $guid_two)){ +function already_attached($guid_one, $guid_two) { + if ($attached = check_entity_relationship($guid_one, "attached", $guid_two)) { return true; } else { return false; @@ -668,37 +732,53 @@ function already_attached($guid_one, $guid_two){ /** * Function to get all objects attached to a particular object - * @param int $guid - * @param string $type - the type of object to return e.g. 'file', 'friend_of' etc + * + * @param int $guid Entity GUID + * @param string $type The type of object to return e.g. 'file', 'friend_of' etc + * * @return an array of objects **/ - -function get_attachments($guid, $type=""){ - $attached = elgg_get_entities_from_relationship(array('relationship' => 'attached', 'relationship_guid' => $guid, 'inverse_relationship' => $inverse_relationship = false, 'types' => $type, 'subtypes' => '', 'owner_guid' => 0, 'order_by' => 'time_created desc', 'limit' => 10, 'offset' => 0, 'count' => false, 'site_guid' => 0)); +function get_attachments($guid, $type = "") { + $options = array( + 'relationship' => 'attached', + 'relationship_guid' => $guid, + 'inverse_relationship' => false, + 'types' => $type, + 'subtypes' => '', + 'owner_guid' => 0, + 'order_by' => 'time_created desc', + 'limit' => 10, + 'offset' => 0, + 'count' => false, + 'site_guid' => 0 + ); + $attached = elgg_get_entities_from_relationship($options); return $attached; } /** * Function to remove a particular attachment between two objects + * * @param int $guid_one This is the target object * @param int $guid_two This is the object to remove from $guid_one - * @return a view + * + * @return void **/ - -function remove_attachment($guid_one, $guid_two){ - if(already_attached($guid_one, $guid_two)) { +function remove_attachment($guid_one, $guid_two) { + if (already_attached($guid_one, $guid_two)) { remove_entity_relationship($guid_one, "attached", $guid_two); } } /** * Function to start the process of attaching one object to another + * * @param int $guid_one This is the target object * @param int $guid_two This is the object trying to attach to $guid_one - * @return a view + * + * @return true|void **/ - -function make_attachment($guid_one, $guid_two){ +function make_attachment($guid_one, $guid_two) { if (!(already_attached($guid_one, $guid_two))) { if (add_entity_relationship($guid_one, "attached", $guid_two)) { return true; @@ -707,7 +787,15 @@ function make_attachment($guid_one, $guid_two){ } /** - * Handler called by trigger_plugin_hook on the "import" event. + * Handler called by trigger_plugin_hook on the "import" event. + * + * @param string $hook import + * @param string $entity_type all + * @param mixed $returnvalue Value from previous hook + * @param mixed $params Array of params + * + * @return mixed + * */ function import_relationship_plugin_hook($hook, $entity_type, $returnvalue, $params) { $element = $params['element']; @@ -723,7 +811,15 @@ function import_relationship_plugin_hook($hook, $entity_type, $returnvalue, $par } /** - * Handler called by trigger_plugin_hook on the "export" event. + * Handler called by trigger_plugin_hook on the "export" event. + * + * @param string $hook export + * @param string $entity_type all + * @param mixed $returnvalue Previous hook return value + * @param array $params Parameters + * + * @elgg_event_handler export all + * @return mixed */ function export_relationship_plugin_hook($hook, $entity_type, $returnvalue, $params) { global $CONFIG; @@ -753,9 +849,11 @@ function export_relationship_plugin_hook($hook, $entity_type, $returnvalue, $par /** * An event listener which will notify users based on certain events. * - * @param unknown_type $event - * @param unknown_type $object_type - * @param unknown_type $object + * @param string $event Event name + * @param string $object_type Object type + * @param mixed $object Object + * + * @return bool */ function relationship_notification_hook($event, $object_type, $object) { global $CONFIG; @@ -764,13 +862,13 @@ function relationship_notification_hook($event, $object_type, $object) { ($object instanceof ElggRelationship) && ($event == 'create') && ($object_type == 'friend') - ) - { + ) { $user_one = get_entity($object->guid_one); $user_two = get_entity($object->guid_two); // Notify target user - return notify_user($object->guid_two, $object->guid_one, sprintf(elgg_echo('friend:newfriend:subject'), $user_one->name), + return notify_user($object->guid_two, $object->guid_one, + sprintf(elgg_echo('friend:newfriend:subject'), $user_one->name), sprintf(elgg_echo("friend:newfriend:body"), $user_one->name, $user_one->getURL()) ); } @@ -783,4 +881,4 @@ register_plugin_hook("import", "all", "import_relationship_plugin_hook", 3); register_plugin_hook("export", "all", "export_relationship_plugin_hook", 3); /** Register event to listen to some events **/ -register_elgg_event_handler('create','friend','relationship_notification_hook'); +register_elgg_event_handler('create', 'friend', 'relationship_notification_hook'); diff --git a/engine/lib/river.php b/engine/lib/river.php index fefd56ef2..ad069d5cf 100644 --- a/engine/lib/river.php +++ b/engine/lib/river.php @@ -3,22 +3,26 @@ * Elgg river 2.0. * Functions for listening for and generating the river separately from the system log. * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage SocialModel.River */ /** * Adds an item to the river. * - * @param string $view The view that will handle the river item (must exist) - * @param string $action_type An arbitrary one-word string to define the action (eg 'comment', 'create') - * @param int $subject_guid The GUID of the entity doing the action - * @param int $object_guid The GUID of the entity being acted upon - * @param int $access_id The access ID of the river item (default: same as the object) - * @param int $posted The UNIX epoch timestamp of the river item (default: now) - * @return true|false Depending on success + * @param string $view The view that will handle the river item (must exist) + * @param string $action_type An arbitrary string to define the action (eg 'comment', 'create') + * @param int $subject_guid The GUID of the entity doing the action + * @param int $object_guid The GUID of the entity being acted upon + * @param int $access_id The access ID of the river item (default: same as the object) + * @param int $posted The UNIX epoch timestamp of the river item (default: now) + * @param int $annotation_id The annotation ID associated with this river entry + * + * @return bool Depending on success */ -function add_to_river($view,$action_type,$subject_guid,$object_guid,$access_id = "",$posted = 0, $annotation_id = 0) { +function add_to_river($view, $action_type, $subject_guid, $object_guid, $access_id = "", +$posted = 0, $annotation_id = 0) { + // use default viewtype for when called from REST api if (!elgg_view_exists($view, 'default')) { return false; @@ -59,7 +63,7 @@ function add_to_river($view,$action_type,$subject_guid,$object_guid,$access_id = " posted = {$posted} "); //update the entities which had the action carried out on it - if($insert_data){ + if ($insert_data) { update_entity_last_action($object_guid, $posted); return $insert_data; } @@ -69,7 +73,8 @@ function add_to_river($view,$action_type,$subject_guid,$object_guid,$access_id = * Removes all items relating to a particular acting entity from the river * * @param int $subject_guid The GUID of the entity - * @return true|false Depending on success + * + * @return bool Depending on success */ function remove_from_river_by_subject($subject_guid) { // Sanitise @@ -86,7 +91,8 @@ function remove_from_river_by_subject($subject_guid) { * Removes all items relating to a particular entity being acted upon from the river * * @param int $object_guid The GUID of the entity - * @return true|false Depending on success + * + * @return bool Depending on success */ function remove_from_river_by_object($object_guid) { // Sanitise @@ -102,8 +108,9 @@ function remove_from_river_by_object($object_guid) { /** * Removes all items relating to a particular annotation being acted upon from the river * - * @param int annotation_id The ID of the annotation - * @return true|false Depending on success + * @param int $annotation_id The ID of the annotation + * + * @return bool Depending on success * @since 1.7.0 */ function remove_from_river_by_annotation($annotation_id) { @@ -121,7 +128,8 @@ function remove_from_river_by_annotation($annotation_id) { * Removes a single river entry * * @param int $id The ID of the river entry - * @return true|false Depending on success + * + * @return bool Depending on success * @since 1.7.2 */ function remove_from_river_by_id($id) { @@ -137,8 +145,9 @@ function remove_from_river_by_id($id) { * Sets the access ID on river items for a particular object * * @param int $object_guid The GUID of the entity - * @param int $access_id The access ID - * @return true|false Depending on success + * @param int $access_id The access ID + * + * @return bool Depending on success */ function update_river_access_by_object($object_guid, $access_id) { // Sanitise @@ -149,28 +158,35 @@ function update_river_access_by_object($object_guid, $access_id) { global $CONFIG; // Remove - return update_data("update {$CONFIG->dbprefix}river set access_id = {$access_id} where object_guid = {$object_guid}"); + $query = "update {$CONFIG->dbprefix}river + set access_id = {$access_id} + where object_guid = {$object_guid}"; + return update_data($query); } /** * Retrieves items from the river. All parameters are optional. * - * @param int|array $subject_guid Acting entity to restrict to. Default: all - * @param int|array $object_guid Entity being acted on to restrict to. Default: all - * @param string $subject_relationship If set to a relationship type, this will use - * $subject_guid as the starting point and set the subjects to be all users this - * entity has this relationship with (eg 'friend'). Default: blank - * @param string $type The type of entity to restrict to. Default: all - * @param string $subtype The subtype of entity to restrict to. Default: all - * @param string $action_type The type of river action to restrict to. Default: all - * @param int $limit The number of items to retrieve. Default: 20 - * @param int $offset The page offset. Default: 0 - * @param int $posted_min The minimum time period to look at. Default: none - * @param int $posted_max The maximum time period to look at. Default: none + * @param int|array $subject_guid Acting entity to restrict to. Default: all + * @param int|array $object_guid Entity being acted on to restrict to. Default: all + * @param string $subject_relationship If set to a relationship type, this will use + * $subject_guid as the starting point and set the + * subjects to be all users this + * entity has this relationship with (eg 'friend'). + * Default: blank + * @param string $type The type of entity to restrict to. Default: all + * @param string $subtype The subtype of entity to restrict to. Default: all + * @param string $action_type The type of river action to restrict to. Default: all + * @param int $limit The number of items to retrieve. Default: 20 + * @param int $offset The page offset. Default: 0 + * @param int $posted_min The minimum time period to look at. Default: none + * @param int $posted_max The maximum time period to look at. Default: none + * * @return array|false Depending on success */ -function get_river_items($subject_guid = 0, $object_guid = 0, $subject_relationship = '', $type = '', - $subtype = '', $action_type = '', $limit = 20, $offset = 0, $posted_min = 0, $posted_max = 0) { +function get_river_items($subject_guid = 0, $object_guid = 0, $subject_relationship = '', +$type = '', $subtype = '', $action_type = '', $limit = 20, $offset = 0, $posted_min = 0, +$posted_max = 0) { // Get config global $CONFIG; @@ -179,14 +195,14 @@ function get_river_items($subject_guid = 0, $object_guid = 0, $subject_relations if (!is_array($subject_guid)) { $subject_guid = (int) $subject_guid; } else { - foreach($subject_guid as $key => $temp) { + foreach ($subject_guid as $key => $temp) { $subject_guid[$key] = (int) $temp; } } if (!is_array($object_guid)) { $object_guid = (int) $object_guid; } else { - foreach($object_guid as $key => $temp) { + foreach ($object_guid as $key => $temp) { $object_guid[$key] = (int) $temp; } } @@ -207,40 +223,41 @@ function get_river_items($subject_guid = 0, $object_guid = 0, $subject_relations // Construct 'where' clauses for the river $where = array(); // river table does not have columns expected by get_access_sql_suffix so we modify its output - $where[] = str_replace("and enabled='yes'",'',str_replace('owner_guid','subject_guid',get_access_sql_suffix())); + $where[] = str_replace("and enabled='yes'", '', + str_replace('owner_guid', 'subject_guid', get_access_sql_suffix())); if (empty($subject_relationship)) { if (!empty($subject_guid)) { if (!is_array($subject_guid)) { $where[] = " subject_guid = {$subject_guid} "; } else { - $where[] = " subject_guid in (" . implode(',',$subject_guid) . ") "; + $where[] = " subject_guid in (" . implode(',', $subject_guid) . ") "; } } } else { if (!is_array($subject_guid)) { - if ($entities = elgg_get_entities_from_relationship(array( + if ($entities = elgg_get_entities_from_relationship(array ( 'relationship' => $subject_relationship, 'relationship_guid' => $subject_guid, 'limit' => 9999)) ) { $guids = array(); - foreach($entities as $entity) { + foreach ($entities as $entity) { $guids[] = (int) $entity->guid; } - // $guids[] = $subject_guid; - $where[] = " subject_guid in (" . implode(',',$guids) . ") "; + $where[] = " subject_guid in (" . implode(',', $guids) . ") "; } else { return array(); } } } - if (!empty($object_guid)) + if (!empty($object_guid)) { if (!is_array($object_guid)) { $where[] = " object_guid = {$object_guid} "; } else { - $where[] = " object_guid in (" . implode(',',$object_guid) . ") "; + $where[] = " object_guid in (" . implode(',', $object_guid) . ") "; } + } if (!empty($type)) { $where[] = " type = '{$type}' "; } @@ -260,8 +277,10 @@ function get_river_items($subject_guid = 0, $object_guid = 0, $subject_relations $whereclause = implode(' and ', $where); // Construct main SQL - $sql = "select id,type,subtype,action_type,access_id,view,subject_guid,object_guid,annotation_id,posted" . - " from {$CONFIG->dbprefix}river where {$whereclause} order by posted desc limit {$offset},{$limit}"; + $sql = "select id, type, subtype, action_type, access_id, view, + subject_guid, object_guid, annotation_id, posted + from {$CONFIG->dbprefix}river + where {$whereclause} order by posted desc limit {$offset}, {$limit}"; // Get data return get_data($sql); @@ -270,22 +289,25 @@ function get_river_items($subject_guid = 0, $object_guid = 0, $subject_relations /** * Retrieves items from the river. All parameters are optional. * - * @param int|array $subject_guid Acting entity to restrict to. Default: all - * @param int|array $object_guid Entity being acted on to restrict to. Default: all - * @param string $subject_relationship If set to a relationship type, this will use - * $subject_guid as the starting point and set the subjects to be all users this - * entity has this relationship with (eg 'friend'). Default: blank - * @param string $type The type of entity to restrict to. Default: all - * @param string $subtype The subtype of entity to restrict to. Default: all - * @param string $action_type The type of river action to restrict to. Default: all - * @param int $limit The number of items to retrieve. Default: 20 - * @param int $offset The page offset. Default: 0 - * @param int $posted_min The minimum time period to look at. Default: none - * @param int $posted_max The maximum time period to look at. Default: none + * @param int|array $subject_guid Acting entity to restrict to. Default: all + * @param int|array $object_guid Entity being acted on to restrict to. Default: all + * @param string $subject_relationship If set to a relationship type, this will use + * $subject_guid as the starting point and set the + * subjects to be all users this entity has this + * relationship with (eg 'friend'). Default: blank + * @param string $type The type of entity to restrict to. Default: all + * @param string $subtype The subtype of entity to restrict to. Default: all + * @param string $action_type The type of river action to restrict to. Default: all + * @param int $limit The number of items to retrieve. Default: 20 + * @param int $offset The page offset. Default: 0 + * @param int $posted_min The minimum time period to look at. Default: none + * @param int $posted_max The maximum time period to look at. Default: none + * * @return array|false Depending on success */ -function elgg_get_river_items($subject_guid = 0, $object_guid = 0, $subject_relationship = '', $type = '', - $subtype = '', $action_type = '', $limit = 10, $offset = 0, $posted_min = 0, $posted_max = 0) { +function elgg_get_river_items($subject_guid = 0, $object_guid = 0, $subject_relationship = '', +$type = '', $subtype = '', $action_type = '', $limit = 10, $offset = 0, $posted_min = 0, +$posted_max = 0) { // Get config global $CONFIG; @@ -294,14 +316,14 @@ function elgg_get_river_items($subject_guid = 0, $object_guid = 0, $subject_rela if (!is_array($subject_guid)) { $subject_guid = (int) $subject_guid; } else { - foreach($subject_guid as $key => $temp) { + foreach ($subject_guid as $key => $temp) { $subject_guid[$key] = (int) $temp; } } if (!is_array($object_guid)) { $object_guid = (int) $object_guid; } else { - foreach($object_guid as $key => $temp) { + foreach ($object_guid as $key => $temp) { $object_guid[$key] = (int) $temp; } } @@ -322,14 +344,15 @@ function elgg_get_river_items($subject_guid = 0, $object_guid = 0, $subject_rela // Construct 'where' clauses for the river $where = array(); // river table does not have columns expected by get_access_sql_suffix so we modify its output - $where[] = str_replace("and enabled='yes'",'',str_replace('owner_guid','subject_guid',get_access_sql_suffix_new('er','e'))); + $where[] = str_replace("and enabled='yes'", '', + str_replace('owner_guid', 'subject_guid', get_access_sql_suffix_new('er', 'e'))); if (empty($subject_relationship)) { if (!empty($subject_guid)) { if (!is_array($subject_guid)) { $where[] = " subject_guid = {$subject_guid} "; } else { - $where[] = " subject_guid in (" . implode(',',$subject_guid) . ") "; + $where[] = " subject_guid in (" . implode(',', $subject_guid) . ") "; } } } else { @@ -341,22 +364,23 @@ function elgg_get_river_items($subject_guid = 0, $object_guid = 0, $subject_rela )); if (is_array($entities) && !empty($entities)) { $guids = array(); - foreach($entities as $entity) { + foreach ($entities as $entity) { $guids[] = (int) $entity->guid; } // $guids[] = $subject_guid; - $where[] = " subject_guid in (" . implode(',',$guids) . ") "; + $where[] = " subject_guid in (" . implode(',', $guids) . ") "; } else { return array(); } } } - if (!empty($object_guid)) + if (!empty($object_guid)) { if (!is_array($object_guid)) { $where[] = " object_guid = {$object_guid} "; } else { - $where[] = " object_guid in (" . implode(',',$object_guid) . ") "; + $where[] = " object_guid in (" . implode(',', $object_guid) . ") "; } + } if (!empty($type)) { $where[] = " er.type = '{$type}' "; } @@ -379,7 +403,7 @@ function elgg_get_river_items($subject_guid = 0, $object_guid = 0, $subject_rela $sql = "select er.*" . " from {$CONFIG->dbprefix}river er, {$CONFIG->dbprefix}entities e " . " where {$whereclause} AND er.object_guid = e.guid GROUP BY object_guid " . - " ORDER BY e.last_action desc LIMIT {$offset},{$limit}"; + " ORDER BY e.last_action desc LIMIT {$offset}, {$limit}"; // Get data return get_data($sql); @@ -391,6 +415,7 @@ function elgg_get_river_items($subject_guid = 0, $object_guid = 0, $subject_rela * @see get_river_items * * @param stdClass $item A river item object as returned from get_river_items + * * @return string|false Depending on success */ function elgg_view_river_item($item) { @@ -402,12 +427,12 @@ function elgg_view_river_item($item) { return false; } else { if (elgg_view_exists($item->view)) { - $body = elgg_view($item->view,array( + $body = elgg_view($item->view, array( 'item' => $item )); } } - return elgg_view('river/item/wrapper',array( + return elgg_view('river/item/wrapper', array( 'item' => $item, 'body' => $body )); @@ -418,36 +443,43 @@ function elgg_view_river_item($item) { /** * Returns a human-readable version of the river. * - * @param int|array $subject_guid Acting entity to restrict to. Default: all - * @param int|array $object_guid Entity being acted on to restrict to. Default: all - * @param string $subject_relationship If set to a relationship type, this will use - * $subject_guid as the starting point and set the subjects to be all users this - * entity has this relationship with (eg 'friend'). Default: blank - * @param string $type The type of entity to restrict to. Default: all - * @param string $subtype The subtype of entity to restrict to. Default: all - * @param string $action_type The type of river action to restrict to. Default: all - * @param int $limit The number of items to retrieve. Default: 20 - * @param int $posted_min The minimum time period to look at. Default: none - * @param int $posted_max The maximum time period to look at. Default: none + * @param int|array $subject_guid Acting entity to restrict to. Default: all + * @param int|array $object_guid Entity being acted on to restrict to. Default: all + * @param string $subject_relationship If set to a relationship type, this will use + * $subject_guid as the starting point and set + * the subjects to be all users this entity has this + * relationship with (eg 'friend'). Default: blank + * @param string $type The type of entity to restrict to. Default: all + * @param string $subtype The subtype of entity to restrict to. Default: all + * @param string $action_type The type of river action to restrict to. Default: all + * @param int $limit The number of items to retrieve. Default: 20 + * @param int $posted_min The minimum time period to look at. Default: none + * @param int $posted_max The maximum time period to look at. Default: none + * @param bool $pagination Show pagination? + * @param $bool $chronological Show in chronological order? + * * @return string Human-readable river. */ function elgg_view_river_items($subject_guid = 0, $object_guid = 0, $subject_relationship = '', - $type = '', $subtype = '', $action_type = '', $limit = 20, $posted_min = 0, $posted_max = 0, $pagination = true, $chronological = false) { +$type = '', $subtype = '', $action_type = '', $limit = 20, $posted_min = 0, +$posted_max = 0, $pagination = true, $chronological = false) { // Get input from outside world and sanitise it - $offset = (int) get_input('offset',0); + $offset = (int) get_input('offset', 0); // Get the correct function - if($chronological == true){ - $riveritems = get_river_items($subject_guid,$object_guid,$subject_relationship,$type,$subtype,$action_type,($limit + 1),$offset,$posted_min,$posted_max); - }else{ - $riveritems = elgg_get_river_items($subject_guid,$object_guid,$subject_relationship,$type,$subtype,$action_type,($limit + 1),$offset,$posted_min,$posted_max); + if ($chronological == true) { + $riveritems = get_river_items($subject_guid, $object_guid, $subject_relationship, $type, + $subtype, $action_type, ($limit + 1), $offset, $posted_min, $posted_max); + } else { + $riveritems = elgg_get_river_items($subject_guid, $object_guid, $subject_relationship, $type, + $subtype, $action_type, ($limit + 1), $offset, $posted_min, $posted_max); } // Get river items, if they exist if ($riveritems) { - return elgg_view('river/item/list',array( + return elgg_view('river/item/list', array( 'limit' => $limit, 'offset' => $offset, 'items' => $riveritems, @@ -463,10 +495,14 @@ function elgg_view_river_items($subject_guid = 0, $object_guid = 0, $subject_rel * This function has been added here until we decide if it is going to roll into core or not * Add access restriction sql code to a given query. * Note that if this code is executed in privileged mode it will return blank. + * * @TODO: DELETE once Query classes are fully integrated * - * @param string $table_prefix Optional table. prefix for the access code. - * @param int $owner + * @param string $table_prefix_one Optional table. prefix for the access code. + * @param string $table_prefix_two Another optiona table prefix? + * @param int $owner Owner GUID + * + * @return string */ function get_access_sql_suffix_new($table_prefix_one = '', $table_prefix_two = '', $owner = null) { global $ENTITY_SHOW_HIDDEN_OVERRIDE, $CONFIG; @@ -503,16 +539,19 @@ function get_access_sql_suffix_new($table_prefix_one = '', $table_prefix_two = ' WHERE relationship='friend' AND guid_two=$owner )"; - $friends_bit = '('.$friends_bit.') OR '; + $friends_bit = '(' . $friends_bit . ') OR '; if ((isset($CONFIG->user_block_and_filter_enabled)) && ($CONFIG->user_block_and_filter_enabled)) { // check to see if the user is in the entity owner's block list // or if the entity owner is in the user's filter list // if so, disallow access - $enemies_bit = get_annotation_sql('elgg_block_list', "{$table_prefix_one}owner_guid", $owner, false); + $enemies_bit = get_annotation_sql('elgg_block_list', "{$table_prefix_one}owner_guid", + $owner, false); + $enemies_bit = '(' . $enemies_bit - . ' AND ' . get_annotation_sql('elgg_filter_list', $owner, "{$table_prefix_one}owner_guid", false) + . ' AND ' . get_annotation_sql('elgg_filter_list', $owner, "{$table_prefix_one}owner_guid", + false) . ')'; } } @@ -531,9 +570,11 @@ function get_access_sql_suffix_new($table_prefix_one = '', $table_prefix_two = ' $sql = "$enemies_bit AND ($sql)"; } - if (!$ENTITY_SHOW_HIDDEN_OVERRIDE) + if (!$ENTITY_SHOW_HIDDEN_OVERRIDE) { $sql .= " and {$table_prefix_two}enabled='yes'"; - return '('.$sql.')'; + } + + return '(' . $sql . ')'; } /** @@ -541,15 +582,22 @@ function get_access_sql_suffix_new($table_prefix_one = '', $table_prefix_two = ' * * @deprecated 1.8 * - * @param int $limit Limit the query. - * @param int $offset Execute from the given object - * @param mixed $type A type, or array of types to look for. Note: This is how they appear in the SYSTEM LOG. - * @param mixed $subtype A subtype, or array of types to look for. Note: This is how they appear in the SYSTEM LOG. - * @param mixed $owner_guid The guid or a collection of GUIDs - * @param string $owner_relationship If defined, the relationship between $owner_guid and the entity owner_guid - so "is $owner_guid $owner_relationship with $entity->owner_guid" + * @param int $limit Limit the query. + * @param int $offset Execute from the given object + * @param mixed $type A type, or array of types to look for. + * Note: This is how they appear in the SYSTEM LOG. + * @param mixed $subtype A subtype, or array of types to look for. + * Note: This is how they appear in the SYSTEM LOG. + * @param mixed $owner_guid The guid or a collection of GUIDs + * @param string $owner_relationship If defined, the relationship between $owner_guid and + * the entity owner_guid - so "is $owner_guid $owner_relationship + * with $entity->owner_guid" + * * @return array An array of system log entries. */ -function get_activity_stream_data($limit = 10, $offset = 0, $type = "", $subtype = "", $owner_guid = "", $owner_relationship = "") { +function get_activity_stream_data($limit = 10, $offset = 0, $type = "", $subtype = "", +$owner_guid = "", $owner_relationship = "") { + global $CONFIG; $limit = (int)$limit; @@ -588,14 +636,15 @@ function get_activity_stream_data($limit = 10, $offset = 0, $type = "", $subtype $owner_relationship = sanitise_string($owner_relationship); // Get a list of possible views - $activity_events= array(); - $activity_views = array_merge(elgg_view_tree('activity', 'default'), elgg_view_tree('river', 'default')); // Join activity with river + $activity_events = array(); + $activity_views = array_merge(elgg_view_tree('activity', 'default'), + elgg_view_tree('river', 'default')); $done = array(); foreach ($activity_views as $view) { $fragments = explode('/', $view); - $tmp = explode('/',$view, 2); + $tmp = explode('/', $view, 2); $tmp = $tmp[1]; if ((isset($fragments[0])) && (($fragments[0] == 'river') || ($fragments[0] == 'activity')) @@ -653,7 +702,7 @@ function get_activity_stream_data($limit = 10, $offset = 0, $type = "", $subtype } $access = ""; - if ($details['type']!='relationship') { + if ($details['type'] != 'relationship') { $access = " and " . get_access_sql_suffix('sl'); } @@ -667,7 +716,7 @@ function get_activity_stream_data($limit = 10, $offset = 0, $type = "", $subtype // User if ((count($owner_guid)) && ($owner_guid[0] != 0)) { - $user = " and sl.performed_by_guid in (".implode(',', $owner_guid).")"; + $user = " and sl.performed_by_guid in (" . implode(',', $owner_guid) . ")"; if ($owner_relationship) { $friendsarray = ""; @@ -681,11 +730,11 @@ function get_activity_stream_data($limit = 10, $offset = 0, $type = "", $subtype ) { $friendsarray = array(); - foreach($friends as $friend) { + foreach ($friends as $friend) { $friendsarray[] = $friend->getGUID(); } - $user = " and sl.performed_by_guid in (" . implode(',', $friendsarray).")"; + $user = " and sl.performed_by_guid in (" . implode(',', $friendsarray) . ")"; } } } diff --git a/engine/lib/sessions.php b/engine/lib/sessions.php index e4a3bfc76..887904371 100644 --- a/engine/lib/sessions.php +++ b/engine/lib/sessions.php @@ -4,8 +4,8 @@ * Elgg session management * Functions to manage logins * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage Session */ /** Elgg magic session */ @@ -14,8 +14,10 @@ global $SESSION; /** * Return the current logged in user, or NULL if no user is logged in. * - * If no user can be found in the current session, a plugin hook - 'session:get' 'user' to give plugin - * authors another way to provide user details to the ACL system without touching the session. + * If no user can be found in the current session, a plugin + * hook - 'session:get' 'user' to give plugin authors another + * way to provide user details to the ACL system without touching the session. + * * @return ElggUser|NULL */ function get_loggedin_user() { @@ -46,7 +48,7 @@ function get_loggedin_userid() { /** * Returns whether or not the user is currently logged in * - * @return true|false + * @return bool */ function isloggedin() { if (!is_installed()) { @@ -66,7 +68,7 @@ function isloggedin() { * Returns whether or not the user is currently logged in and that they are an admin user. * * @uses isloggedin() - * @return true|false + * @return bool */ function isadminloggedin() { if (!is_installed()) { @@ -84,9 +86,11 @@ function isadminloggedin() { /** * Check if the given user has full access. + * * @todo: Will always return full access if the user is an admin. * - * @param $user_guid + * @param int $user_guid The user to check + * * @return bool * @since 1.7.1 */ @@ -134,8 +138,10 @@ function elgg_is_admin_user($user_guid) { * Returns an ElggUser object for use with login. * * @see login + * * @param string $username The username, optionally (for standard logins) * @param string $password The password, optionally (for standard logins) + * * @return ElggUser|false The authenticated user object, or false on failure. */ @@ -151,8 +157,11 @@ function authenticate($username, $password) { * Hook into the PAM system which accepts a username and password and attempts to authenticate * it against a known user. * - * @param array $credentials Associated array of credentials passed to pam_authenticate. This function expects - * 'username' and 'password' (cleartext). + * @param array $credentials Associated array of credentials passed to + * pam_authenticate. This function expects + * 'username' and 'password' (cleartext). + * + * @return bool */ function pam_auth_userpass($credentials = NULL) { @@ -179,7 +188,8 @@ function pam_auth_userpass($credentials = NULL) { /** * Log a failed login for $user_guid * - * @param $user_guid + * @param int $user_guid User GUID + * * @return bool on success */ function log_login_failure($user_guid) { @@ -201,7 +211,8 @@ function log_login_failure($user_guid) { /** * Resets the fail login count for $user_guid * - * @param $user_guid + * @param int $user_guid User GUID + * * @return bool on success (success = user has no logged failed attempts) */ function reset_login_failure_count($user_guid) { @@ -212,7 +223,7 @@ function reset_login_failure_count($user_guid) { $fails = (int)$user->getPrivateSetting("login_failures"); if ($fails) { - for ($n=1; $n <= $fails; $n++) { + for ($n = 1; $n <= $fails; $n++) { $user->removePrivateSetting("login_failure_$n"); } @@ -231,7 +242,8 @@ function reset_login_failure_count($user_guid) { /** * Checks if the rate limit of failed logins has been exceeded for $user_guid. * - * @param $user_guid + * @param int $user_guid User GUID + * * @return bool on exceeded limit. */ function check_rate_limit_exceeded($user_guid) { @@ -245,13 +257,13 @@ function check_rate_limit_exceeded($user_guid) { if ($fails >= $limit) { $cnt = 0; $time = time(); - for ($n=$fails; $n>0; $n--) { + for ($n = $fails; $n > 0; $n--) { $f = $user->getPrivateSetting("login_failure_$n"); - if ($f > $time - (60*5)) { + if ($f > $time - (60 * 5)) { $cnt++; } - if ($cnt==$limit) { + if ($cnt == $limit) { // Limit reached return true; } @@ -267,9 +279,11 @@ function check_rate_limit_exceeded($user_guid) { * with authenticate. * * @see authenticate - * @param ElggUser $user A valid Elgg user object - * @param boolean $persistent Should this be a persistent login? - * @return true|false Whether login was successful + * + * @param ElggUser $user A valid Elgg user object + * @param boolean $persistent Should this be a persistent login? + * + * @return bool Whether login was successful */ function login(ElggUser $user, $persistent = false) { global $CONFIG; @@ -295,7 +309,7 @@ function login(ElggUser $user, $persistent = false) { $code = (md5($user->name . $user->username . time() . rand())); $_SESSION['code'] = $code; $user->code = md5($code); - setcookie("elggperm", $code, (time()+(86400 * 30)), "/"); + setcookie("elggperm", $code, (time() + (86400 * 30)), "/"); } if (!$user->save() || !trigger_elgg_event('login', 'user', $user)) { @@ -305,7 +319,7 @@ function login(ElggUser $user, $persistent = false) { unset($_SESSION['guid']); unset($_SESSION['id']); unset($_SESSION['user']); - setcookie("elggperm", "", (time()-(86400 * 30)), "/"); + setcookie("elggperm", "", (time() - (86400 * 30)), "/"); return false; } @@ -322,13 +336,13 @@ function login(ElggUser $user, $persistent = false) { /** * Log the current user out * - * @return true|false + * @return bool */ function logout() { global $CONFIG; if (isset($_SESSION['user'])) { - if (!trigger_elgg_event('logout','user',$_SESSION['user'])) { + if (!trigger_elgg_event('logout', 'user', $_SESSION['user'])) { return false; } $_SESSION['user']->code = ""; @@ -342,7 +356,7 @@ function logout() { unset($_SESSION['id']); unset($_SESSION['user']); - setcookie("elggperm", "", (time()-(86400 * 30)),"/"); + setcookie("elggperm", "", (time() - (86400 * 30)), "/"); // pass along any messages $old_msg = $_SESSION['msg']; @@ -362,12 +376,16 @@ function logout() { * This function looks for: * * 1. $_SESSION['id'] - if not present, we're logged out, and this is set to 0 - * 2. The cookie 'elggperm' - if present, checks it for an authentication token, validates it, and potentially logs the user in + * 2. The cookie 'elggperm' - if present, checks it for an authentication + * token, validates it, and potentially logs the user in * * @uses $_SESSION - * @param unknown_type $event - * @param unknown_type $object_type - * @param unknown_type $object + * + * @param string $event Event name + * @param string $object_type Object type + * @param mixed $object Object + * + * @return bool */ function session_init($event, $object_type, $object) { global $DB_PREFIX, $CONFIG; @@ -380,12 +398,12 @@ function session_init($event, $object_type, $object) { // HACK to allow access to prefix after object destruction $DB_PREFIX = $CONFIG->dbprefix; if ((!isset($CONFIG->use_file_sessions))) { - session_set_save_handler("__elgg_session_open", - "__elgg_session_close", - "__elgg_session_read", - "__elgg_session_write", - "__elgg_session_destroy", - "__elgg_session_gc"); + session_set_save_handler("_elgg_session_open", + "_elgg_session_close", + "_elgg_session_read", + "_elgg_session_write", + "_elgg_session_destroy", + "_elgg_session_gc"); } session_name('Elgg'); @@ -393,7 +411,7 @@ function session_init($event, $object_type, $object) { // Generate a simple token (private from potentially public session id) if (!isset($_SESSION['__elgg_session'])) { - $_SESSION['__elgg_session'] = md5(microtime().rand()); + $_SESSION['__elgg_session'] = md5(microtime() . rand()); } // test whether we have a user session @@ -438,7 +456,7 @@ function session_init($event, $object_type, $object) { set_last_action($_SESSION['guid']); } - register_action("login",true); + register_action("login", true); register_action("logout"); // Register a default PAM handler @@ -463,6 +481,7 @@ function session_init($event, $object_type, $object) { /** * Used at the top of a page to mark it as logged in users only. * + * @return void */ function gatekeeper() { if (!isloggedin()) { @@ -475,6 +494,7 @@ function gatekeeper() { /** * Used at the top of a page to mark it as logged in admin or siteadmin only. * + * @return void */ function admin_gatekeeper() { gatekeeper(); @@ -487,9 +507,15 @@ function admin_gatekeeper() { } /** - * DB Based session handling code. + * Handles opening a session in the DB + * + * @param string $save_path The path to save the sessions + * @param string $session_name The name of the session + * + * @return true + * @todo Document */ -function __elgg_session_open($save_path, $session_name) { +function _elgg_session_open($save_path, $session_name) { global $sess_save_path; $sess_save_path = $save_path; @@ -497,16 +523,25 @@ function __elgg_session_open($save_path, $session_name) { } /** - * DB Based session handling code. + * Closes a session + * + * @todo implement + * @todo document + * + * @return true */ -function __elgg_session_close() { +function _elgg_session_close() { return true; } /** - * DB Based session handling code. + * Read the session data from DB failing back to file. + * + * @param string $id The session ID + * + * @return string */ -function __elgg_session_read($id) { +function _elgg_session_read($id) { global $DB_PREFIX; $id = sanitise_string($id); @@ -532,9 +567,14 @@ function __elgg_session_read($id) { } /** - * DB Based session handling code. + * Write session data to the DB falling back to file. + * + * @param string $id The session ID + * @param mixed $sess_data Session data + * + * @return bool */ -function __elgg_session_write($id, $sess_data) { +function _elgg_session_write($id, $sess_data) { global $DB_PREFIX; $id = sanitise_string($id); @@ -547,7 +587,7 @@ function __elgg_session_write($id, $sess_data) { (session, ts, data) VALUES ('$id', '$time', '$sess_data_sanitised')"; - if (insert_data($q)!==false) { + if (insert_data($q) !== false) { return true; } } catch (DatabaseException $e) { @@ -567,9 +607,13 @@ function __elgg_session_write($id, $sess_data) { } /** - * DB Based session handling code. + * Destroy a DB session, falling back to file. + * + * @param string $id Session ID + * + * @return bool */ -function __elgg_session_destroy($id) { +function _elgg_session_destroy($id) { global $DB_PREFIX; $id = sanitise_string($id); @@ -589,17 +633,22 @@ function __elgg_session_destroy($id) { } /** - * DB Based session handling code. + * Perform garbage collection on session table / files + * + * @param int $maxlifetime Max age of a session + * + * @return bool */ -function __elgg_session_gc($maxlifetime) { +function _elgg_session_gc($maxlifetime) { global $DB_PREFIX; - $life = time()-$maxlifetime; + $life = time() - $maxlifetime; try { return (bool)delete_data("DELETE from {$DB_PREFIX}users_sessions where ts<'$life'"); } catch (DatabaseException $e) { - // Fall back to file store in this case, since this likely means that the database hasn't been upgraded + // Fall back to file store in this case, since this likely means that the database + // hasn't been upgraded global $sess_save_path; foreach (glob("$sess_save_path/sess_*") as $filename) { @@ -612,4 +661,4 @@ function __elgg_session_gc($maxlifetime) { return true; } -register_elgg_event_handler("boot","system","session_init",20); +register_elgg_event_handler("boot", "system", "session_init", 20); diff --git a/engine/lib/sites.php b/engine/lib/sites.php index 378a2cfe1..d5984a75f 100644 --- a/engine/lib/sites.php +++ b/engine/lib/sites.php @@ -3,14 +3,16 @@ * Elgg sites * Functions to manage multiple or single sites in an Elgg install * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage DataModel.Site */ /** * Return the site specific details of a site by a row. * - * @param int $guid + * @param int $guid The site GUID + * + * @return mixed */ function get_site_entity_as_row($guid) { global $CONFIG; @@ -23,10 +25,12 @@ function get_site_entity_as_row($guid) { * Create or update the extras table for a given site. * Call create_entity first. * - * @param int $guid - * @param string $name - * @param string $description - * @param string $url + * @param int $guid Site GUID + * @param string $name Site name + * @param string $description Site Description + * @param string $url URL of the site + * + * @return bool */ function create_site_entity($guid, $name, $description, $url) { global $CONFIG; @@ -40,12 +44,16 @@ function create_site_entity($guid, $name, $description, $url) { if ($row) { // Exists and you have access to it - if ($exists = get_data_row("SELECT guid from {$CONFIG->dbprefix}sites_entity where guid = {$guid}")) { - $result = update_data("UPDATE {$CONFIG->dbprefix}sites_entity set name='$name', description='$description', url='$url' where guid=$guid"); - if ($result!=false) { + $query = "SELECT guid from {$CONFIG->dbprefix}sites_entity where guid = {$guid}"; + if ($exists = get_data_row($query)) { + $query = "UPDATE {$CONFIG->dbprefix}sites_entity + set name='$name', description='$description', url='$url' where guid=$guid"; + $result = update_data($query); + + if ($result != false) { // Update succeeded, continue $entity = get_entity($guid); - if (trigger_elgg_event('update',$entity->type,$entity)) { + if (trigger_elgg_event('update', $entity->type, $entity)) { return $guid; } else { $entity->delete(); @@ -54,10 +62,13 @@ function create_site_entity($guid, $name, $description, $url) { } } else { // Update failed, attempt an insert. - $result = insert_data("INSERT into {$CONFIG->dbprefix}sites_entity (guid, name, description, url) values ($guid, '$name','$description','$url')"); - if ($result!==false) { + $query = "INSERT into {$CONFIG->dbprefix}sites_entity + (guid, name, description, url) values ($guid, '$name', '$description', '$url')"; + $result = insert_data($query); + + if ($result !== false) { $entity = get_entity($guid); - if (trigger_elgg_event('create',$entity->type,$entity)) { + if (trigger_elgg_event('create', $entity->type, $entity)) { return $guid; } else { $entity->delete(); @@ -74,8 +85,13 @@ function create_site_entity($guid, $name, $description, $url) { * THIS FUNCTION IS DEPRECATED. * * Delete a site's extra data. + * * @todo remove - * @param int $guid + * + * @param int $guid Site guid + * + * @deprecated 1.5 Or so? + * @return 1 */ function delete_site_entity($guid) { system_message(sprintf(elgg_echo('deprecatedfunction'), 'delete_user_entity')); @@ -86,8 +102,10 @@ function delete_site_entity($guid) { /** * Add a user to a site. * - * @param int $site_guid - * @param int $user_guid + * @param int $site_guid Site guid + * @param int $user_guid User guid + * + * @return bool */ function add_site_user($site_guid, $user_guid) { global $CONFIG; @@ -101,8 +119,10 @@ function add_site_user($site_guid, $user_guid) { /** * Remove a user from a site. * - * @param int $site_guid - * @param int $user_guid + * @param int $site_guid Site GUID + * @param int $user_guid User GUID + * + * @return bool */ function remove_site_user($site_guid, $user_guid) { $site_guid = (int)$site_guid; @@ -114,9 +134,11 @@ function remove_site_user($site_guid, $user_guid) { /** * Get the members of a site. * - * @param int $site_guid - * @param int $limit - * @param int $offset + * @param int $site_guid Site GUID + * @param int $limit User GUID + * @param int $offset Offset + * + * @return mixed */ function get_site_members($site_guid, $limit = 10, $offset = 0) { $site_guid = (int)$site_guid; @@ -124,10 +146,10 @@ function get_site_members($site_guid, $limit = 10, $offset = 0) { $offset = (int)$offset; return elgg_get_entities_from_relationship(array( - 'relationship' => 'member_of_site', - 'relationship_guid' => $site_guid, - 'inverse_relationship' => TRUE, - 'types' => 'user', + 'relationship' => 'member_of_site', + 'relationship_guid' => $site_guid, + 'inverse_relationship' => TRUE, + 'types' => 'user', 'limit' => $limit, 'offset' => $offset )); } @@ -135,21 +157,22 @@ function get_site_members($site_guid, $limit = 10, $offset = 0) { /** * Display a list of site members * - * @param int $site_guid The GUID of the site - * @param int $limit The number of members to display on a page - * @param true|false $fullview Whether or not to display the full view (default: true) + * @param int $site_guid The GUID of the site + * @param int $limit The number of members to display on a page + * @param bool $fullview Whether or not to display the full view (default: true) + * * @return string A displayable list of members */ function list_site_members($site_guid, $limit = 10, $fullview = true) { $offset = (int) get_input('offset'); $limit = (int) $limit; $options = array( - 'relationship' => 'member_of_site', - 'relationship_guid' => $site_guid, - 'inverse_relationship' => TRUE, + 'relationship' => 'member_of_site', + 'relationship_guid' => $site_guid, + 'inverse_relationship' => TRUE, 'types' => 'user', - 'limit' => $limit, - 'offset' => $offset, + 'limit' => $limit, + 'offset' => $offset, 'count' => TRUE ); $count = (int) elgg_get_entities_from_relationship($options); @@ -162,8 +185,10 @@ function list_site_members($site_guid, $limit = 10, $fullview = true) { /** * Add an object to a site. * - * @param int $site_guid - * @param int $object_guid + * @param int $site_guid Site GUID + * @param int $object_guid Object GUID + * + * @return mixed */ function add_site_object($site_guid, $object_guid) { global $CONFIG; @@ -177,8 +202,10 @@ function add_site_object($site_guid, $object_guid) { /** * Remove an object from a site. * - * @param int $site_guid - * @param int $object_guid + * @param int $site_guid Site GUID + * @param int $object_guid Object GUID + * + * @return bool */ function remove_site_object($site_guid, $object_guid) { $site_guid = (int)$site_guid; @@ -190,10 +217,12 @@ function remove_site_object($site_guid, $object_guid) { /** * Get the objects belonging to a site. * - * @param int $site_guid - * @param string $subtype - * @param int $limit - * @param int $offset + * @param int $site_guid Site GUID + * @param string $subtype Subtype + * @param int $limit Limit + * @param int $offset Offset + * + * @return mixed */ function get_site_objects($site_guid, $subtype = "", $limit = 10, $offset = 0) { $site_guid = (int)$site_guid; @@ -203,11 +232,11 @@ function get_site_objects($site_guid, $subtype = "", $limit = 10, $offset = 0) { return elgg_get_entities_from_relationship(array( 'relationship' => 'member_of_site', - 'relationship_guid' => $site_guid, - 'inverse_relationship' => TRUE, - 'types' => 'object', - 'subtypes' => $subtype, - 'limit' => $limit, + 'relationship_guid' => $site_guid, + 'inverse_relationship' => TRUE, + 'types' => 'object', + 'subtypes' => $subtype, + 'limit' => $limit, 'offset' => $offset )); } @@ -215,8 +244,10 @@ function get_site_objects($site_guid, $subtype = "", $limit = 10, $offset = 0) { /** * Add a collection to a site. * - * @param int $site_guid - * @param int $collection_guid + * @param int $site_guid Site GUID + * @param int $collection_guid Collection GUID + * + * @return mixed */ function add_site_collection($site_guid, $collection_guid) { global $CONFIG; @@ -230,8 +261,11 @@ function add_site_collection($site_guid, $collection_guid) { /** * Remove a collection from a site. * - * @param int $site_guid - * @param int $collection_guid + * @param int $site_guid Site GUID + * @param int $collection_guid Collection GUID + * + * @todo probably remove. + * @return mixed */ function remove_site_collection($site_guid, $collection_guid) { $site_guid = (int)$site_guid; @@ -243,10 +277,12 @@ function remove_site_collection($site_guid, $collection_guid) { /** * Get the collections belonging to a site. * - * @param int $site_guid - * @param string $subtype - * @param int $limit - * @param int $offset + * @param int $site_guid Site GUID + * @param string $subtype Subtype + * @param int $limit Limit + * @param int $offset Offset + * + * @return mixed */ function get_site_collections($site_guid, $subtype = "", $limit = 10, $offset = 0) { $site_guid = (int)$site_guid; @@ -256,11 +292,11 @@ function get_site_collections($site_guid, $subtype = "", $limit = 10, $offset = // collection isn't a valid type. This won't work. return elgg_get_entities_from_relationship(array( - 'relationship' => 'member_of_site', - 'relationship_guid' => $site_guid, - 'inverse_relationship' => TRUE, - 'types' => 'collection', - 'subtypes' => $subtype, + 'relationship' => 'member_of_site', + 'relationship_guid' => $site_guid, + 'inverse_relationship' => TRUE, + 'types' => 'collection', + 'subtypes' => $subtype, 'limit' => $limit, 'offset' => $offset )); @@ -268,6 +304,10 @@ function get_site_collections($site_guid, $subtype = "", $limit = 10, $offset = /** * Return the site via a url. + * + * @param string $url The URL of a site + * + * @return mixed */ function get_site_by_url($url) { global $CONFIG; @@ -284,17 +324,20 @@ function get_site_by_url($url) { } /** - * Searches for a site based on a complete or partial name or description or url using full text searching. + * Searches for a site based on a complete or partial name + * or description or url using full text searching. * * IMPORTANT NOTE: With MySQL's default setup: * 1) $criteria must be 4 or more characters long * 2) If $criteria matches greater than 50% of results NO RESULTS ARE RETURNED! * - * @param string $criteria The partial or full name or username. - * @param int $limit Limit of the search. - * @param int $offset Offset. - * @param string $order_by The order. - * @param boolean $count Whether to return the count of results or just the results. + * @param string $criteria The partial or full name or username. + * @param int $limit Limit of the search. + * @param int $offset Offset. + * @param string $order_by The order. + * @param boolean $count Whether to return the count of results or just the results. + * + * @return mixed * @deprecated 1.7 */ function search_for_site($criteria, $limit = 10, $offset = 0, $order_by = "", $count = false) { @@ -317,7 +360,9 @@ function search_for_site($criteria, $limit = 10, $offset = 0, $order_by = "", $c } else { $query = "SELECT e.* "; } - $query .= "from {$CONFIG->dbprefix}entities e join {$CONFIG->dbprefix}sites_entity s on e.guid=s.guid where match(s.name,s.description,s.url) against ('$criteria') and $access"; + $query .= "from {$CONFIG->dbprefix}entities e + join {$CONFIG->dbprefix}sites_entity s on e.guid=s.guid + where match(s.name, s.description, s.url) against ('$criteria') and $access"; if (!$count) { $query .= " order by $order_by limit $offset, $limit"; // Add order and limit @@ -333,7 +378,9 @@ function search_for_site($criteria, $limit = 10, $offset = 0, $order_by = "", $c /** * Retrieve a site and return the domain portion of its url. * - * @param int $guid + * @param int $guid ElggSite GUID + * + * @return string */ function get_site_domain($guid) { $guid = (int)$guid; @@ -355,16 +402,18 @@ function get_site_domain($guid) { * to the sites init event and changing $CONFIG->site_id. * * @uses $CONFIG - * @param string $event Event API required parameter + * + * @param string $event Event API required parameter * @param string $object_type Event API required parameter - * @param null $object Event API required parameter + * @param null $object Event API required parameter + * * @return true */ function sites_init($event, $object_type, $object) { global $CONFIG; if (is_installed() && is_db_installed()) { - $site = trigger_plugin_hook("siteid","system"); + $site = trigger_plugin_hook("siteid", "system"); if ($site === null || $site === false) { $CONFIG->site_id = (int) datalist_get('default_site'); } else { @@ -380,10 +429,21 @@ function sites_init($event, $object_type, $object) { } // Register event handlers -register_elgg_event_handler('boot','system','sites_init',2); +register_elgg_event_handler('boot', 'system', 'sites_init', 2); // Register with unit test register_plugin_hook('unit_test', 'system', 'sites_test'); + +/** + * Unit tests for sites + * + * @param sting $hook unit_test + * @param string $type system + * @param mixed $value Array of tests + * @param mixed $params Params + * + * @return array + */ function sites_test($hook, $type, $value, $params) { global $CONFIG; $value[] = "{$CONFIG->path}engine/tests/objects/sites.php"; diff --git a/engine/lib/statistics.php b/engine/lib/statistics.php index 91fea1257..0067f3672 100644 --- a/engine/lib/statistics.php +++ b/engine/lib/statistics.php @@ -1,18 +1,20 @@ <?php /** * Elgg statistics library. + * * This file contains a number of functions for obtaining statistics about the running system. - * These statistics are mainly used by the administration pages, and is also where the basic views for statistics - * are added. + * These statistics are mainly used by the administration pages, and is also where the basic + * views for statistics are added. * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage Statistics */ /** * Return an array reporting the number of various entities in the system. * * @param int $owner_guid Optional owner of the statistics + * * @return array */ function get_entity_statistics($owner_guid = 0) { @@ -21,7 +23,10 @@ function get_entity_statistics($owner_guid = 0) { $entity_stats = array(); $owner_guid = (int)$owner_guid; - $query = "SELECT distinct e.type,s.subtype,e.subtype as subtype_id from {$CONFIG->dbprefix}entities e left join {$CONFIG->dbprefix}entity_subtypes s on e.subtype=s.id"; + $query = "SELECT distinct e.type,s.subtype,e.subtype as subtype_id + from {$CONFIG->dbprefix}entities e left + join {$CONFIG->dbprefix}entity_subtypes s on e.subtype=s.id"; + $owner_query = ""; if ($owner_guid) { $query .= " where owner_guid=$owner_guid"; @@ -37,9 +42,11 @@ function get_entity_statistics($owner_guid = 0) { $entity_stats[$type->type] = array(); } - $query = "SELECT count(*) as count from {$CONFIG->dbprefix}entities where type='{$type->type}' $owner_query"; + $query = "SELECT count(*) as count + from {$CONFIG->dbprefix}entities where type='{$type->type}' $owner_query"; + if ($type->subtype) { - $query.= " and subtype={$type->subtype_id}"; + $query .= " and subtype={$type->subtype_id}"; } $subtype_cnt = get_data_row($query); @@ -57,7 +64,8 @@ function get_entity_statistics($owner_guid = 0) { /** * Return the number of users registered in the system. * - * @param bool $show_deactivated + * @param bool $show_deactivated Count not enabled users? + * * @return int */ function get_number_users($show_deactivated = false) { @@ -69,7 +77,10 @@ function get_number_users($show_deactivated = false) { $access = "and " . get_access_sql_suffix(); } - $result = get_data_row("SELECT count(*) as count from {$CONFIG->dbprefix}entities where type='user' $access"); + $query = "SELECT count(*) as count + from {$CONFIG->dbprefix}entities where type='user' $access"; + + $result = get_data_row($query); if ($result) { return $result->count; @@ -80,6 +91,8 @@ function get_number_users($show_deactivated = false) { /** * Return a list of how many users are currently online, rendered as a view. + * + * @return string */ function get_online_users() { $offset = get_input('offset', 0); @@ -87,12 +100,14 @@ function get_online_users() { $objects = find_active_users(600, 10, $offset); if ($objects) { - return elgg_view_entity_list($objects, $count,$offset,10,false); + return elgg_view_entity_list($objects, $count, $offset, 10, false); } } /** * Initialise the statistics admin page. + * + * @return void */ function statistics_init() { extend_elgg_admin_page('admin/statistics_opt/basic', 'admin/statistics'); @@ -104,4 +119,4 @@ function statistics_init() { } /// Register init function -register_elgg_event_handler('init','system','statistics_init');
\ No newline at end of file +register_elgg_event_handler('init', 'system', 'statistics_init');
\ No newline at end of file diff --git a/engine/lib/system_log.php b/engine/lib/system_log.php index 8816e24c3..05e3985eb 100644 --- a/engine/lib/system_log.php +++ b/engine/lib/system_log.php @@ -3,28 +3,35 @@ * Elgg system log. * Listens to events and writes crud events into the system log database. * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage Logging */ /** * Retrieve the system log based on a number of parameters. * - * @param int or array $by_user The guid(s) of the user(s) who initiated the event. - * @param string $event The event you are searching on. - * @param string $class The class of object it effects. - * @param string $type The type - * @param string $subtype The subtype. - * @param int $limit Maximum number of responses to return. - * @param int $offset Offset of where to start. - * @param bool $count Return count or not + * @param int|array $by_user The guid(s) of the user(s) who initiated the event. + * @param string $event The event you are searching on. + * @param string $class The class of object it effects. + * @param string $type The type + * @param string $subtype The subtype. + * @param int $limit Maximum number of responses to return. + * @param int $offset Offset of where to start. + * @param bool $count Return count or not + * @param int $timebefore Lower time limit + * @param int $timeafter Upper time limit + * @param int $object_id GUID of an object + * + * @return mixed */ -function get_system_log($by_user = "", $event = "", $class = "", $type = "", $subtype = "", $limit = 10, $offset = 0, $count = false, $timebefore = 0, $timeafter = 0, $object_id = 0) { +function get_system_log($by_user = "", $event = "", $class = "", $type = "", $subtype = "", +$limit = 10, $offset = 0, $count = false, $timebefore = 0, $timeafter = 0, $object_id = 0) { + global $CONFIG; $by_user_orig = $by_user; if (is_array($by_user) && sizeof($by_user) > 0) { - foreach($by_user as $key => $val) { + foreach ($by_user as $key => $val) { $by_user[$key] = (int) $val; } } else { @@ -39,23 +46,23 @@ function get_system_log($by_user = "", $event = "", $class = "", $type = "", $su $where = array(); - if ($by_user_orig!=="") { + if ($by_user_orig !== "") { if (is_int($by_user)) { $where[] = "performed_by_guid=$by_user"; } else if (is_array($by_user)) { - $where [] = "performed_by_guid in (". implode(",",$by_user) .")"; + $where [] = "performed_by_guid in (" . implode(",", $by_user) . ")"; } } if ($event != "") { $where[] = "event='$event'"; } - if ($class!=="") { + if ($class !== "") { $where[] = "object_class='$class'"; } if ($type != "") { $where[] = "object_type='$type'"; } - if ($subtype!=="") { + if ($subtype !== "") { $where[] = "object_subtype='$subtype'"; } @@ -98,6 +105,8 @@ function get_system_log($by_user = "", $event = "", $class = "", $type = "", $su * Return a specific log entry. * * @param int $entry_id The log entry + * + * @return mixed */ function get_log_entry($entry_id) { global $CONFIG; @@ -111,6 +120,8 @@ function get_log_entry($entry_id) { * Return the object referred to by a given log entry * * @param int $entry_id The log entry + * + * @return mixed */ function get_object_from_log_entry($entry_id) { $entry = get_log_entry($entry_id); @@ -133,8 +144,10 @@ function get_object_from_log_entry($entry_id) { * * This is called by the event system and should not be called directly. * - * @param $object The object you're talking about. - * @param $event String The event being logged + * @param object $object The object you're talking about. + * @param string $event String The event being logged + * + * @return mixed */ function system_log($object, $event) { global $CONFIG; @@ -173,7 +186,14 @@ function system_log($object, $event) { // Create log if we haven't already created it if (!isset($logcache[$time][$object_id][$event])) { - insert_data("INSERT DELAYED into {$CONFIG->dbprefix}system_log (object_id, object_class, object_type, object_subtype, event, performed_by_guid, owner_guid, access_id, enabled, time_created) VALUES ('$object_id','$object_class','$object_type', '$object_subtype', '$event',$performed_by, $owner_guid, $access_id, '$enabled', '$time')"); + $query = "INSERT DELAYED into {$CONFIG->dbprefix}system_log + (object_id, object_class, object_type, object_subtype, event, + performed_by_guid, owner_guid, access_id, enabled, time_created) + VALUES + ('$object_id','$object_class','$object_type', '$object_subtype', '$event', + $performed_by, $owner_guid, $access_id, '$enabled', '$time')"; + + insert_data($query); $logcache[$time][$object_id][$event] = true; } @@ -186,6 +206,8 @@ function system_log($object, $event) { * This function creates an archive copy of the system log. * * @param int $offset An offset in seconds from now to archive (useful for log rotation) + * + * @return bool */ function archive_log($offset = 0) { global $CONFIG; @@ -196,7 +218,10 @@ function archive_log($offset = 0) { $ts = $now - $offset; // create table - if (!update_data("CREATE TABLE {$CONFIG->dbprefix}system_log_$now as SELECT * from {$CONFIG->dbprefix}system_log WHERE time_created<$ts")) { + $query = "CREATE TABLE {$CONFIG->dbprefix}system_log_$now as + SELECT * from {$CONFIG->dbprefix}system_log WHERE time_created<$ts"; + + if (!update_data($query)) { return false; } @@ -217,10 +242,11 @@ function archive_log($offset = 0) { /** * Default system log handler, allows plugins to override, extend or disable logging. * - * @param string $event - * @param string $object_type - * @param Loggable $object - * @return unknown + * @param string $event Event name + * @param string $object_type Object type + * @param Loggable $object Object to log + * + * @return true */ function system_log_default_logger($event, $object_type, $object) { system_log($object['object'], $object['event']); @@ -232,12 +258,14 @@ function system_log_default_logger($event, $object_type, $object) { * System log listener. * This function listens to all events in the system and logs anything appropriate. * - * @param String $event - * @param String $object_type - * @param Loggable $object + * @param String $event Event name + * @param String $object_type Type of object + * @param Loggable $object Object to log + * + * @return true */ function system_log_listener($event, $object_type, $object) { - if (($object_type!='systemlog') && ($event!='log')) { + if (($object_type != 'systemlog') && ($event != 'log')) { trigger_elgg_event('log', 'systemlog', array('object' => $object, 'event' => $event)); } @@ -245,7 +273,7 @@ function system_log_listener($event, $object_type, $object) { } /** Register event to listen to all events **/ -register_elgg_event_handler('all','all','system_log_listener', 400); +register_elgg_event_handler('all', 'all', 'system_log_listener', 400); /** Register a default system log handler */ -register_elgg_event_handler('log','systemlog','system_log_default_logger', 999);
\ No newline at end of file +register_elgg_event_handler('log', 'systemlog', 'system_log_default_logger', 999);
\ No newline at end of file diff --git a/engine/lib/tags.php b/engine/lib/tags.php index e4b59b573..02c8e433c 100644 --- a/engine/lib/tags.php +++ b/engine/lib/tags.php @@ -3,25 +3,32 @@ * Elgg tags * Functions for managing tags and tag clouds. * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage Tags */ /** * The algorithm working out the size of font based on the number of tags. * This is quick and dirty. + * + * @param int $min Min size + * @param int $max Max size + * @param int $number_of_tags The number of tags + * @param int $buckets The number of buckets + * + * @return int */ function calculate_tag_size($min, $max, $number_of_tags, $buckets = 6) { - $delta = (($max - $min) / $buckets); + $delta = (($max - $min) / $buckets); $thresholds = array(); - for ($n=1; $n <= $buckets; $n++) { - $thresholds[$n-1] = ($min + $n) * $delta; + for ($n = 1; $n <= $buckets; $n++) { + $thresholds[$n - 1] = ($min + $n) * $delta; } // Correction - if ($thresholds[$buckets-1]>$max) { - $thresholds[$buckets-1] = $max; + if ($thresholds[$buckets - 1] > $max) { + $thresholds[$buckets - 1] = $max; } $size = 0; @@ -37,7 +44,9 @@ function calculate_tag_size($min, $max, $number_of_tags, $buckets = 6) { /** * This function generates an array of tags with a weighting. * - * @param array $tags The array of tags. + * @param array $tags The array of tags. + * @param int $buckets The number of buckets + * * @return An associated array of tags with a weighting, this can then be mapped to a display class. */ function generate_tag_cloud(array $tags, $buckets = 6) { @@ -49,11 +58,11 @@ function generate_tag_cloud(array $tags, $buckets = 6) { foreach ($tags as $tag) { $cloud[$tag]++; - if ($cloud[$tag]>$max) { + if ($cloud[$tag] > $max) { $max = $cloud[$tag]; } - if ($cloud[$tag]<$min) { + if ($cloud[$tag] < $min) { $min = $cloud[$tag]; } } @@ -70,7 +79,6 @@ function generate_tag_cloud(array $tags, $buckets = 6) { * * Supports similar arguments as elgg_get_entities() * - * * @param array $options Array in format: * * threshold => INT minimum tag count @@ -83,7 +91,8 @@ function generate_tag_cloud(array $tags, $buckets = 6) { * * subtypes => NULL|STR entity subtype (SQL: subtype = '$subtype') * - * type_subtype_pairs => NULL|ARR (array('type' => 'subtype')) (SQL: type = '$type' AND subtype = '$subtype') pairs + * type_subtype_pairs => NULL|ARR (array('type' => 'subtype')) + * (SQL: type = '$type' AND subtype = '$subtype') pairs * * owner_guids => NULL|INT entity guid * @@ -168,7 +177,8 @@ function elgg_get_tags(array $options = array()) { $tags_in = implode(',', $sanitised_tags); $wheres[] = "(msn.string IN ($tags_in))"; - $wheres[] = elgg_get_entity_type_subtype_where_sql('e', $options['types'], $options['subtypes'], $options['type_subtype_pairs']); + $wheres[] = elgg_get_entity_type_subtype_where_sql('e', $options['types'], + $options['subtypes'], $options['type_subtype_pairs']); $wheres[] = elgg_get_entity_site_where_sql('e', $options['site_guids']); $wheres[] = elgg_get_entity_owner_where_sql('e', $options['owner_guids']); $wheres[] = elgg_get_entity_container_where_sql('e', $options['container_guids']); @@ -240,19 +250,23 @@ function elgg_get_tags(array $options = array()) { * * @deprecated 1.8 Use elgg_get_tags(). * - * @param int $threshold Get the threshold of minimum number of each tags to bother with (ie only show tags where there are more than $threshold occurances) - * @param int $limit Number of tags to return - * @param string $metadata_name Optionally, the name of the field you want to grab for - * @param string $entity_type Optionally, the entity type ('object' etc) + * @param int $threshold Get the threshold of minimum number of each tags to + * bother with (ie only show tags where there are more + * than $threshold occurances) + * @param int $limit Number of tags to return + * @param string $metadata_name Optionally, the name of the field you want to grab for + * @param string $entity_type Optionally, the entity type ('object' etc) * @param string $entity_subtype The entity subtype, optionally - * @param int $owner_guid The GUID of the tags owner, optionally - * @param int $site_guid Optionally, the site to restrict to (default is the current site) - * @param int $start_ts Optionally specify a start timestamp for tags used to generate cloud. - * @param int $ent_ts Optionally specify an end timestamp for tags used to generate cloud. + * @param int $owner_guid The GUID of the tags owner, optionally + * @param int $site_guid Optionally, the site to restrict to (default is the current site) + * @param int $start_ts Optionally specify a start timestamp for tags used to + * generate cloud. + * @param int $end_ts Optionally specify an end timestamp for tags used to generate cloud + * * @return array|false Array of objects with ->tag and ->total values, or false on failure */ - -function get_tags($threshold = 1, $limit = 10, $metadata_name = "", $entity_type = "object", $entity_subtype = "", $owner_guid = "", $site_guid = -1, $start_ts = "", $end_ts = "") { +function get_tags($threshold = 1, $limit = 10, $metadata_name = "", $entity_type = "object", +$entity_subtype = "", $owner_guid = "", $site_guid = -1, $start_ts = "", $end_ts = "") { elgg_deprecated_notice('get_tags() has been replaced by elgg_get_tags()', 1.8); @@ -303,7 +317,6 @@ function get_tags($threshold = 1, $limit = 10, $metadata_name = "", $entity_type /** * Returns viewable tagcloud * - * * @see elgg_get_tags * * @param array $options Any elgg_get_tags() options except: @@ -324,9 +337,9 @@ function elgg_view_tagcloud(array $options = array()) { if (isset($options['subtype'])) { $subtype = $options['subtype']; } - + $tag_data = elgg_get_tags($options); - return elgg_view("output/tagcloud",array('value' => $tag_data, + return elgg_view("output/tagcloud", array('value' => $tag_data, 'type' => $type, 'subtype' => $subtype)); @@ -337,23 +350,30 @@ function elgg_view_tagcloud(array $options = array()) { * * @deprecated 1.8 use elgg_view_tagcloud() * - * @param int $threshold Get the threshold of minimum number of each tags to bother with (ie only show tags where there are more than $threshold occurances) - * @param int $limit Number of tags to return - * @param string $metadata_name Optionally, the name of the field you want to grab for - * @param string $entity_type Optionally, the entity type ('object' etc) + * @param int $threshold Get the threshold of minimum number of each tags + * to bother with (ie only show tags where there are + * more than $threshold occurances) + * @param int $limit Number of tags to return + * @param string $metadata_name Optionally, the name of the field you want to grab for + * @param string $entity_type Optionally, the entity type ('object' etc) * @param string $entity_subtype The entity subtype, optionally - * @param int $owner_guid The GUID of the tags owner, optionally - * @param int $site_guid Optionally, the site to restrict to (default is the current site) - * @param int $start_ts Optionally specify a start timestamp for tags used to generate cloud. - * @param int $ent_ts Optionally specify an end timestamp for tags used to generate cloud. + * @param int $owner_guid The GUID of the tags owner, optionally + * @param int $site_guid Optionally, the site to restrict to (default is the current site) + * @param int $start_ts Optionally specify a start timestamp for tags used to + * generate cloud. + * @param int $end_ts Optionally specify an end timestamp for tags used to generate + * cloud. + * * @return string The HTML (or other, depending on view type) of the tagcloud. */ - -function display_tagcloud($threshold = 1, $limit = 10, $metadata_name = "", $entity_type = "object", $entity_subtype = "", $owner_guid = "", $site_guid = -1, $start_ts = "", $end_ts = "") { +function display_tagcloud($threshold = 1, $limit = 10, $metadata_name = "", $entity_type = "object", +$entity_subtype = "", $owner_guid = "", $site_guid = -1, $start_ts = "", $end_ts = "") { elgg_deprecated_notice('display_cloud() was deprecated by elgg_view_tagcloud()!', 1.8); - - $tags = get_tags($threshold, $limit, $metadata_name, $entity_type, $entity_subtype, $owner_guid, $site_guid, $start_ts, $end_ts); + + $tags = get_tags($threshold, $limit, $metadata_name, $entity_type, + $entity_subtype, $owner_guid, $site_guid, $start_ts, $end_ts); + return elgg_view('output/tagcloud', array( 'value' => $tags, 'type' => $entity_type, @@ -366,8 +386,8 @@ function display_tagcloud($threshold = 1, $limit = 10, $metadata_name = "", $ent * This is required if you are using a non-standard metadata name * for your tags. * + * @param string $name Tag name * - * @param string $name * @return bool * @since 1.7.0 */ @@ -394,7 +414,9 @@ function elgg_register_tag_metadata_name($name) { function elgg_get_registered_tag_metadata_names() { global $CONFIG; - $names = (isset($CONFIG->registered_tag_metadata_names)) ? $CONFIG->registered_tag_metadata_names : array(); + $names = (isset($CONFIG->registered_tag_metadata_names)) + ? $CONFIG->registered_tag_metadata_names : array(); + return $names; } @@ -402,15 +424,23 @@ function elgg_get_registered_tag_metadata_names() { elgg_register_tag_metadata_name('tags'); register_page_handler('tags', 'elgg_tagcloud_page_handler'); + +/** + * Page hander for tags + * + * @param array $page Page array + * + * @return void + */ function elgg_tagcloud_page_handler($page) { global $CONFIG; - + switch ($page[0]) { default: $title = elgg_view_title(elgg_echo('tags:site_cloud')); $tags = display_tagcloud(0, 100, 'tags'); $body = elgg_view_layout('one_column_with_sidebar', $title . $tags); - + page_draw(elgg_echo('tags:site_cloud'), $body); break; } diff --git a/engine/lib/upgrades/2008100701.php b/engine/lib/upgrades/2008100701.php index cf976e84c..394a90046 100644 --- a/engine/lib/upgrades/2008100701.php +++ b/engine/lib/upgrades/2008100701.php @@ -1,8 +1,7 @@ <?php /// Activate mail plugin /** - * Because Elgg now has a plugable account activation process we need to activate + * Because Elgg now has a plugable account activation process we need to activate * the email account activation plugin for existing installs. - */ - enable_plugin('uservalidationbyemail', $CONFIG->site->guid); -?>
\ No newline at end of file + */ + enable_plugin('uservalidationbyemail', $CONFIG->site->guid);
\ No newline at end of file diff --git a/engine/lib/upgrades/2008101303.php b/engine/lib/upgrades/2008101303.php index c98eace74..69e44e3a0 100644 --- a/engine/lib/upgrades/2008101303.php +++ b/engine/lib/upgrades/2008101303.php @@ -1,11 +1,9 @@ <?php - // Upgrade to solve login issue - - if ($users = get_entities_from_metadata('validated_email', '', 'user', '', 0,9999)) { - foreach($users as $user) { - set_user_validation_status($user->guid, true, 'email'); - } - } - -?>
\ No newline at end of file +// Upgrade to solve login issue + +if ($users = get_entities_from_metadata('validated_email', '', 'user', '', 0, 9999)) { + foreach ($users as $user) { + set_user_validation_status($user->guid, true, 'email'); + } +} diff --git a/engine/lib/upgrades/2009022701.php b/engine/lib/upgrades/2009022701.php index 92d540cd3..2e83b56b3 100644 --- a/engine/lib/upgrades/2009022701.php +++ b/engine/lib/upgrades/2009022701.php @@ -1,8 +1,7 @@ <?php global $CONFIG; - + /** * Disable update client since this has now been removed. */ - disable_plugin('updateclient', $CONFIG->site->guid); -?>
\ No newline at end of file + disable_plugin('updateclient', $CONFIG->site->guid);
\ No newline at end of file diff --git a/engine/lib/upgrades/2009041701.php b/engine/lib/upgrades/2009041701.php index 609c7e569..acc8fc0bd 100644 --- a/engine/lib/upgrades/2009041701.php +++ b/engine/lib/upgrades/2009041701.php @@ -1,10 +1,9 @@ <?php global $CONFIG; - + /// Activate kses /** * Elgg now has kses tag filtering built as a plugin. This needs to be enabled. - */ - enable_plugin('kses', $CONFIG->site->guid); -?>
\ No newline at end of file + */ + enable_plugin('kses', $CONFIG->site->guid);
\ No newline at end of file diff --git a/engine/lib/upgrades/2009070101.php b/engine/lib/upgrades/2009070101.php index edd8ce4b4..3bf89e9b7 100644 --- a/engine/lib/upgrades/2009070101.php +++ b/engine/lib/upgrades/2009070101.php @@ -1,11 +1,10 @@ <?php global $CONFIG; - + /// Deprecate kses and activate htmlawed /** * Kses appears to be a dead project so we are deprecating it in favour of htmlawed. - */ + */ disable_plugin('kses', $CONFIG->site->guid); - enable_plugin('htmlawed', $CONFIG->site->guid); -?>
\ No newline at end of file + enable_plugin('htmlawed', $CONFIG->site->guid);
\ No newline at end of file diff --git a/engine/lib/upgrades/2009102801.php b/engine/lib/upgrades/2009102801.php index b72e0a781..8885dbb09 100644 --- a/engine/lib/upgrades/2009102801.php +++ b/engine/lib/upgrades/2009102801.php @@ -4,151 +4,176 @@ set_time_limit(0); /** - Elgg 1.0 + * Generates a file matrix like Elgg 1.0 did + * + * @param string $username Username of user + * + * @return string File matrix path */ -function file_matrix_1_0($username) -{ +function file_matrix_1_0($username) { $matrix = ""; - + $len = strlen($username); - if ($len > 5) + if ($len > 5) { $len = 5; - + } + for ($n = 0; $n < $len; $n++) { - if (ctype_alnum($username[$n])) + if (ctype_alnum($username[$n])) { $matrix .= $username[$n] . "/"; - } + } + } - return $matrix.$username."/"; + return $matrix . $username . "/"; } /** - Elgg 1.1, 1.2 and 1.5 + * Generate a file matrix like Elgg 1.1, 1.2 and 1.5 + * + * @param string $filename The filename + * + * @return string */ -function file_matrix_1_1($filename) -{ +function file_matrix_1_1($filename) { $matrix = ""; - + $name = $filename; $filename = mb_str_split($filename); - if (!$filename) return false; - + if (!$filename) { + return false; + } + $len = count($filename); - if ($len > 5) + if ($len > 5) { $len = 5; - + } + for ($n = 0; $n < $len; $n++) { $matrix .= $filename[$n] . "/"; - } + } - return $matrix.$name."/"; + return $matrix . $name . "/"; } -function mb_str_split($string, $charset = 'UTF8') -{ - if (is_callable('mb_substr')) - { +/** + * Handle splitting multibyte strings + * + * @param string $string String to split. + * @param string $charset Charset to use. + * + * @return array|false + */ +function mb_str_split($string, $charset = 'UTF8') { + if (is_callable('mb_substr')) { $length = mb_strlen($string); $array = array(); - - while ($length) - { + + while ($length) { $array[] = mb_substr($string, 0, 1, $charset); $string = mb_substr($string, 1, $length, $charset); - + $length = mb_strlen($string); } - + return $array; - } - else + } else { return str_split($string); - + } + return false; } /** - Elgg 1.6 + * 1.6 style file matrix + * + * @param string $filename The filename + * + * @return string */ -function file_matrix_1_6($filename) -{ +function file_matrix_1_6($filename) { $invalid_fs_chars = '*\'\\/"!$%^&*.%(){}[]#~?<>;|¬`@-+='; - + $matrix = ""; - + $name = $filename; $filename = mb_str_split($filename); - if (!$filename) return false; - + if (!$filename) { + return false; + } + $len = count($filename); - if ($len > 5) + if ($len > 5) { $len = 5; - + } + for ($n = 0; $n < $len; $n++) { - + // Prevent a matrix being formed with unsafe characters $char = $filename[$n]; - if (strpos($invalid_fs_chars, $char)!==false) + if (strpos($invalid_fs_chars, $char) !== false) { $char = '_'; - + } + $matrix .= $char . "/"; - } + } - return $matrix.$name."/"; + return $matrix . $name . "/"; } /** - * Scans a directory and moves any files from $from to $to + * Scans a directory and moves any files from $from to $to * preserving structure and handling existing paths. * Will no overwrite files in $to. * * TRAILING SLASHES REQUIRED. * - * @param $from From dir. - * @param $to To dir. - * @param $move Bool. True to move, false to copy. - * @param $preference str to|from If file collisions, which dir has preference. + * @param string $from From dir. + * @param string $to To dir. + * @param bool $move True to move, false to copy. + * @param string $preference to|from If file collisions, which dir has preference. + * + * @return bool */ -function merge_directories($from, $to, $move=false, $preference='to') { +function merge_directories($from, $to, $move = false, $preference = 'to') { if (!$entries = scandir($from)) { return false; } - + // character filtering needs to be elsewhere. if (!is_dir($to)) { mkdir($to, 0700, true); } - + if ($move === true) { $f = 'rename'; } else { $f = 'copy'; } - + foreach ($entries as $entry) { if ($entry == '.' || $entry == '..') { continue; } - + $from_path = $from . $entry; $to_path = $to . $entry; - + // check to see if the path exists and is a dir, if so, recurse. if (is_dir($from_path) && is_dir($to_path)) { $from_path .= '/'; $to_path .= '/'; merge_directories($from_path, $to_path, $move, $preference); - + // since it's a dir that already exists we don't need to move it continue; } - + // only move if target doesn't exist or if preference is for the from dir if (!file_exists($to_path) || $preference == 'from') { - + if ($f($from_path, $to_path)) { //elgg_dump("Moved/Copied $from_path to $to_path"); } @@ -158,20 +183,21 @@ function merge_directories($from, $to, $move=false, $preference='to') { } } +/** + * Create a 1.7 style user file matrix based upon date. + * + * @param int $guid Guid of owner + * + * @return string File matrix path + */ function user_file_matrix($guid) { // lookup the entity $user = get_entity($guid); - if ($user->type != 'user') - { + 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/"; } @@ -180,7 +206,8 @@ global $DB_QUERY_CACHE, $DB_PROFILE, $ENTITY_CACHE; /** Upgrade file locations */ -$users = mysql_query("SELECT guid, username FROM {$CONFIG->dbprefix}users_entity WHERE username != ''"); +$users = mysql_query("SELECT guid, username + FROM {$CONFIG->dbprefix}users_entity WHERE username != ''"); while ($user = mysql_fetch_object($users)) { $DB_QUERY_CACHE = $DB_PROFILE = $ENTITY_CACHE = array(); @@ -188,6 +215,6 @@ while ($user = mysql_fetch_object($users)) { foreach (array('1_0', '1_1', '1_6') as $version) { $function = "file_matrix_$version"; $from = $CONFIG->dataroot . $function($user->username); - merge_directories($from, $to, $move=TRUE, $preference='from'); + merge_directories($from, $to, $move = TRUE, $preference = 'from'); } } diff --git a/engine/lib/upgrades/2010033101.php b/engine/lib/upgrades/2010033101.php index b137e0285..5c8ee036b 100644 --- a/engine/lib/upgrades/2010033101.php +++ b/engine/lib/upgrades/2010033101.php @@ -38,20 +38,24 @@ if ($dbversion < 2009100701) { $qs[] = "ALTER TABLE {$CONFIG->dbprefix}groups_entity DISABLE KEYS"; $qs[] = "REPLACE INTO {$CONFIG->dbprefix}groups_entity (guid, name, description) - SELECT guid, unhex(hex(convert(name using latin1))), unhex(hex(convert(description using latin1))) + SELECT guid, unhex(hex(convert(name using latin1))), + unhex(hex(convert(description using latin1))) FROM {$CONFIG->dbprefix}groups_entity"; $qs[] = "ALTER TABLE {$CONFIG->dbprefix}groups_entity ENABLE KEYS"; $qs[] = "ALTER TABLE {$CONFIG->dbprefix}objects_entity DISABLE KEYS"; $qs[] = "REPLACE INTO {$CONFIG->dbprefix}objects_entity (guid, title, description) - SELECT guid, unhex(hex(convert(title using latin1))), unhex(hex(convert(description using latin1))) + SELECT guid, unhex(hex(convert(title using latin1))), + unhex(hex(convert(description using latin1))) FROM {$CONFIG->dbprefix}objects_entity"; $qs[] = "ALTER TABLE {$CONFIG->dbprefix}objects_entity ENABLE KEYS"; $qs[] = "ALTER TABLE {$CONFIG->dbprefix}users_entity DISABLE KEYS"; - $qs[] = "REPLACE INTO {$CONFIG->dbprefix}users_entity (guid, name, username, password, salt, email, language, code, + $qs[] = "REPLACE INTO {$CONFIG->dbprefix}users_entity + (guid, name, username, password, salt, email, language, code, banned, last_action, prev_last_action, last_login, prev_last_login) - SELECT guid, unhex(hex(convert(name using latin1))), username, password, salt, email, language, code, + SELECT guid, unhex(hex(convert(name using latin1))), + username, password, salt, email, language, code, banned, last_action, prev_last_action, last_login, prev_last_login FROM {$CONFIG->dbprefix}users_entity"; $qs[] = "ALTER TABLE {$CONFIG->dbprefix}users_entity ENABLE KEYS"; diff --git a/engine/lib/upgrades/2010060401.php b/engine/lib/upgrades/2010060401.php index 2106bdbc0..6d628b8eb 100644 --- a/engine/lib/upgrades/2010060401.php +++ b/engine/lib/upgrades/2010060401.php @@ -11,7 +11,8 @@ $count = 0; $user_guids = mysql_query("SELECT guid FROM {$CONFIG->dbprefix}users_entity"); while ($user = mysql_fetch_object($user_guids)) { - $query = "SELECT * FROM {$CONFIG->dbprefix}entity_relationships WHERE guid_one=$user->guid AND relationship LIKE 'notify%'"; + $query = "SELECT * FROM {$CONFIG->dbprefix}entity_relationships + WHERE guid_one=$user->guid AND relationship LIKE 'notify%'"; $relationships = mysql_query($query); if (mysql_num_rows($relationships) == 0) { // no notify relationships for this user @@ -42,11 +43,12 @@ while ($user = mysql_fetch_object($user_guids)) { WHERE guid_one=$user->guid AND relationship='$relationship_type' AND guid_two=$obj->guid_two"; $results = mysql_query($query); - if (mysql_num_rows($results) == 0) { - $query = "DELETE FROM {$CONFIG->dbprefix}entity_relationships WHERE id=$obj->id"; - mysql_query($query); - $count++; - } + + if (mysql_num_rows($results) == 0) { + $query = "DELETE FROM {$CONFIG->dbprefix}entity_relationships WHERE id=$obj->id"; + mysql_query($query); + $count++; + } } } diff --git a/engine/lib/upgrades/2010061501.php b/engine/lib/upgrades/2010061501.php index 2b65cc5c7..d230236fc 100644 --- a/engine/lib/upgrades/2010061501.php +++ b/engine/lib/upgrades/2010061501.php @@ -1,7 +1,7 @@ <?php /** * utf8 conversion and file merging for usernames with multibyte chars - * + * */ @@ -14,56 +14,60 @@ if ($dbversion < 2009100701) { // start a new link to the DB to see what its defaults are. $link = mysql_connect($CONFIG->dbhost, $CONFIG->dbuser, $CONFIG->dbpass, TRUE); mysql_select_db($CONFIG->dbname, $link); - + $q = "SHOW VARIABLES LIKE 'character_set_client'"; $r = mysql_query($q); $client = mysql_fetch_assoc($r); - + $q = "SHOW VARIABLES LIKE 'character_set_connection'"; $r = mysql_query($q); $connection = mysql_fetch_assoc($r); - + // only run upgrade if not already talking utf8 if ($client['Value'] != 'utf8' && $connection['Value'] != 'utf8') { $qs = array(); $qs[] = "SET NAMES utf8"; - + $qs[] = "ALTER TABLE {$CONFIG->dbprefix}users_entity DISABLE KEYS"; - $qs[] = "REPLACE INTO {$CONFIG->dbprefix}users_entity (guid, name, username, password, salt, email, language, code, - banned, admin, last_action, prev_last_action, last_login, prev_last_login) - SELECT guid, name, unhex(hex(convert(username using latin1))), password, salt, email, language, code, + $qs[] = "REPLACE INTO {$CONFIG->dbprefix}users_entity + (guid, name, username, password, salt, email, language, code, + banned, admin, last_action, prev_last_action, last_login, prev_last_login) + + SELECT guid, name, unhex(hex(convert(username using latin1))), + password, salt, email, language, code, banned, admin, last_action, prev_last_action, last_login, prev_last_login FROM {$CONFIG->dbprefix}users_entity"; - + $qs[] = "ALTER TABLE {$CONFIG->dbprefix}users_entity ENABLE KEYS"; - + foreach ($qs as $q) { if (!update_data($q)) { throw new Exception('Couldn\'t execute upgrade query: ' . $q); } } - + global $DB_QUERY_CACHE, $DB_PROFILE, $ENTITY_CACHE; - + /** Upgrade file locations */ // new connection to force into utf8 mode to get the old name $link = mysql_connect($CONFIG->dbhost, $CONFIG->dbuser, $CONFIG->dbpass, TRUE); mysql_select_db($CONFIG->dbname, $link); - + // must be the first command mysql_query("SET NAMES utf8"); - - $users = mysql_query("SELECT guid, username FROM {$CONFIG->dbprefix}users_entity WHERE username != ''", $link); + + $users = mysql_query("SELECT guid, username FROM {$CONFIG->dbprefix}users_entity + WHERE username != ''", $link); while ($user = mysql_fetch_object($users)) { $DB_QUERY_CACHE = $DB_PROFILE = $ENTITY_CACHE = array(); - + $to = $CONFIG->dataroot . user_file_matrix($user->guid); foreach (array('1_0', '1_1', '1_6') as $version) { $function = "file_matrix_$version"; $from = $CONFIG->dataroot . $function($user->username); - merge_directories($from, $to, $move=TRUE, $preference='from'); + merge_directories($from, $to, $move = TRUE, $preference = 'from'); } } } diff --git a/engine/lib/upgrades/2010062301.php b/engine/lib/upgrades/2010062301.php index 049a93440..f679fa46d 100644 --- a/engine/lib/upgrades/2010062301.php +++ b/engine/lib/upgrades/2010062301.php @@ -14,7 +14,8 @@ if ($groups) { $acl = $group->group_acl; try { - $query = "UPDATE {$CONFIG->dbprefix}access_collections SET owner_guid = $group->guid WHERE id = $acl"; + $query = "UPDATE {$CONFIG->dbprefix}access_collections + SET owner_guid = $group->guid WHERE id = $acl"; update_data($query); } catch (Exception $e) { // no acl so create one diff --git a/engine/lib/upgrades/2010071001.php b/engine/lib/upgrades/2010071001.php index 4df044cff..1b5d379d8 100644 --- a/engine/lib/upgrades/2010071001.php +++ b/engine/lib/upgrades/2010071001.php @@ -3,6 +3,14 @@ * Change profile image names to use guid rather than username */ +/** + * Need the same function to generate a user matrix, but can't call it + * the same thing as the previous update. + * + * @param int $guid User guid. + * + * @return string File matrix + */ function user_file_matrix_2010071001($guid) { // lookup the entity $user = get_entity($guid); @@ -23,7 +31,8 @@ function user_file_matrix_2010071001($guid) { $sizes = array('large', 'medium', 'small', 'tiny', 'master', 'topbar'); global $DB_QUERY_CACHE, $DB_PROFILE, $ENTITY_CACHE, $CONFIG; -$users = mysql_query("SELECT guid, username FROM {$CONFIG->dbprefix}users_entity WHERE username != ''"); +$users = mysql_query("SELECT guid, username FROM {$CONFIG->dbprefix}users_entity + WHERE username != ''"); while ($user = mysql_fetch_object($users)) { $DB_QUERY_CACHE = $DB_PROFILE = $ENTITY_CACHE = array(); diff --git a/engine/lib/upgrades/2010071002.php b/engine/lib/upgrades/2010071002.php index cdf08c830..30bd6538c 100644 --- a/engine/lib/upgrades/2010071002.php +++ b/engine/lib/upgrades/2010071002.php @@ -6,7 +6,8 @@ // loop through all users checking collections and notifications global $DB_QUERY_CACHE, $DB_PROFILE, $ENTITY_CACHE, $CONFIG; global $NOTIFICATION_HANDLERS; -$users = mysql_query("SELECT guid, username FROM {$CONFIG->dbprefix}users_entity WHERE username != ''"); +$users = mysql_query("SELECT guid, username FROM {$CONFIG->dbprefix}users_entity + WHERE username != ''"); while ($user = mysql_fetch_object($users)) { $DB_QUERY_CACHE = $DB_PROFILE = $ENTITY_CACHE = array(); @@ -25,7 +26,7 @@ while ($user = mysql_fetch_object($users)) { // check the all friends notifications if ($collection_id == -1) { $options = array( - 'relationship' => 'friend', + 'relationship' => 'friend', 'relationship_guid' => $user->guid, 'limit' => 0 ); diff --git a/engine/lib/users.php b/engine/lib/users.php index 3a15e9397..e980ee6f8 100644 --- a/engine/lib/users.php +++ b/engine/lib/users.php @@ -3,8 +3,8 @@ * Elgg users * Functions to manage multiple or single users in an Elgg install * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage DataModel.User */ /// Map a username to a cached GUID @@ -16,7 +16,9 @@ $CODE_TO_GUID_MAP_CACHE = array(); /** * Return the user specific details of a user by a row. * - * @param int $guid + * @param int $guid The ElggUser guid + * + * @return mixed */ function get_user_entity_as_row($guid) { global $CONFIG; @@ -29,10 +31,16 @@ function get_user_entity_as_row($guid) { * Create or update the extras table for a given user. * Call create_entity first. * - * @param int $guid - * @param string $name - * @param string $description - * @param string $url + * @param int $guid The user's GUID + * @param string $name The user's display name + * @param string $username The username + * @param string $password The password + * @param string $salt A salt for the password + * @param string $email The user's email address + * @param string $language The user's default language + * @param string $code A code + * + * @return bool */ function create_user_entity($guid, $name, $username, $password, $salt, $email, $language, $code) { global $CONFIG; @@ -50,12 +58,18 @@ function create_user_entity($guid, $name, $username, $password, $salt, $email, $ if ($row) { // Exists and you have access to it - if ($exists = get_data_row("SELECT guid from {$CONFIG->dbprefix}users_entity where guid = {$guid}")) { - $result = update_data("UPDATE {$CONFIG->dbprefix}users_entity set name='$name', username='$username', password='$password', salt='$salt', email='$email', language='$language', code='$code', last_action = ". time() ." where guid = {$guid}"); + $query = "SELECT guid from {$CONFIG->dbprefix}users_entity where guid = {$guid}"; + if ($exists = get_data_row($query)) { + $query = "UPDATE {$CONFIG->dbprefix}users_entity + set name='$name', username='$username', password='$password', salt='$salt', + email='$email', language='$language', code='$code', last_action = " + . time() . " where guid = {$guid}"; + + $result = update_data($query); if ($result != false) { // Update succeeded, continue $entity = get_entity($guid); - if (trigger_elgg_event('update',$entity->type,$entity)) { + if (trigger_elgg_event('update', $entity->type, $entity)) { return $guid; } else { $entity->delete(); @@ -63,10 +77,14 @@ function create_user_entity($guid, $name, $username, $password, $salt, $email, $ } } else { // Update failed, attempt an insert. - $result = insert_data("INSERT into {$CONFIG->dbprefix}users_entity (guid, name, username, password, salt, email, language, code) values ($guid, '$name', '$username', '$password', '$salt', '$email', '$language', '$code')"); - if ($result!==false) { + $query = "INSERT into {$CONFIG->dbprefix}users_entity + (guid, name, username, password, salt, email, language, code) + values ($guid, '$name', '$username', '$password', '$salt', '$email', '$language', '$code')"; + + $result = insert_data($query); + if ($result !== false) { $entity = get_entity($guid); - if (trigger_elgg_event('create',$entity->type,$entity)) { + if (trigger_elgg_event('create', $entity->type, $entity)) { return $guid; } else { $entity->delete(); //delete_entity($guid); @@ -82,15 +100,20 @@ function create_user_entity($guid, $name, $username, $password, $salt, $email, $ * Disables all of a user's entities * * @param int $owner_guid The owner GUID - * @return true|false Depending on success + * + * @return bool Depending on success */ function disable_user_entities($owner_guid) { global $CONFIG; $owner_guid = (int) $owner_guid; if ($entity = get_entity($owner_guid)) { - if (trigger_elgg_event('disable',$entity->type,$entity)) { + if (trigger_elgg_event('disable', $entity->type, $entity)) { if ($entity->canEdit()) { - $res = update_data("UPDATE {$CONFIG->dbprefix}entities set enabled='no' where owner_guid={$owner_guid} or container_guid = {$owner_guid}"); + $query = "UPDATE {$CONFIG->dbprefix}entities + set enabled='no' where owner_guid={$owner_guid} + or container_guid = {$owner_guid}"; + + $res = update_data($query); return $res; } } @@ -102,8 +125,10 @@ function disable_user_entities($owner_guid) { /** * Ban a user * - * @param int $user_guid The user guid - * @param string $reason A reason + * @param int $user_guid The user guid + * @param string $reason A reason + * + * @return bool */ function ban_user($user_guid, $reason = "") { global $CONFIG; @@ -117,7 +142,7 @@ function ban_user($user_guid, $reason = "") { if (trigger_elgg_event('ban', 'user', $user)) { // Add reason if ($reason) { - create_metadata($user_guid, 'ban_reason', $reason,'', 0, ACCESS_PUBLIC); + create_metadata($user_guid, 'ban_reason', $reason, '', 0, ACCESS_PUBLIC); } // clear "remember me" cookie code so user cannot login in using it @@ -135,7 +160,8 @@ function ban_user($user_guid, $reason = "") { } // Set ban flag - return update_data("UPDATE {$CONFIG->dbprefix}users_entity set banned='yes' where guid=$user_guid"); + $query = "UPDATE {$CONFIG->dbprefix}users_entity set banned='yes' where guid=$user_guid"; + return update_data($query); } return FALSE; @@ -148,6 +174,8 @@ function ban_user($user_guid, $reason = "") { * Unban a user. * * @param int $user_guid Unban a user. + * + * @return bool */ function unban_user($user_guid) { global $CONFIG; @@ -158,7 +186,7 @@ function unban_user($user_guid) { if (($user) && ($user->canEdit()) && ($user instanceof ElggUser)) { if (trigger_elgg_event('unban', 'user', $user)) { - create_metadata($user_guid, 'ban_reason', '','', 0, ACCESS_PUBLIC); + create_metadata($user_guid, 'ban_reason', '', '', 0, ACCESS_PUBLIC); // invalidate memcache for this user static $newentity_cache; @@ -170,7 +198,9 @@ function unban_user($user_guid) { $newentity_cache->delete($user_guid); } - return update_data("UPDATE {$CONFIG->dbprefix}users_entity set banned='no' where guid=$user_guid"); + + $query = "UPDATE {$CONFIG->dbprefix}users_entity set banned='no' where guid=$user_guid"; + return update_data($query); } return FALSE; @@ -182,7 +212,8 @@ function unban_user($user_guid) { /** * Makes user $guid an admin. * - * @param int $guid + * @param int $user_guid User guid + * * @return bool */ function make_user_admin($user_guid) { @@ -217,7 +248,8 @@ function make_user_admin($user_guid) { /** * Removes user $guid's admin flag. * - * @param int $guid + * @param int $user_guid User GUID + * * @return bool */ function remove_user_admin($user_guid) { @@ -253,8 +285,12 @@ function remove_user_admin($user_guid) { * THIS FUNCTION IS DEPRECATED. * * Delete a user's extra data. + * * @todo remove - * @param int $guid + * + * @param int $guid User GUID + * + * @return 1 */ function delete_user_entity($guid) { system_message(sprintf(elgg_echo('deprecatedfunction'), 'delete_user_entity')); @@ -266,8 +302,9 @@ function delete_user_entity($guid) { * Get the sites this user is part of * * @param int $user_guid The user's GUID - * @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 false|array On success, an array of ElggSites */ function get_user_sites($user_guid, $limit = 10, $offset = 0) { @@ -288,9 +325,10 @@ function get_user_sites($user_guid, $limit = 10, $offset = 0) { /** * Adds a user to another user's friends list. * - * @param int $user_guid The GUID of the friending user + * @param int $user_guid The GUID of the friending user * @param int $friend_guid The GUID of the user to friend - * @return true|false Depending on success + * + * @return bool Depending on success */ function user_add_friend($user_guid, $friend_guid) { $user_guid = (int) $user_guid; @@ -313,9 +351,10 @@ function user_add_friend($user_guid, $friend_guid) { /** * Removes a user from another user's friends list. * - * @param int $user_guid The GUID of the friending user + * @param int $user_guid The GUID of the friending user * @param int $friend_guid The GUID of the user on the friends list - * @return true|false Depending on success + * + * @return bool Depending on success */ function user_remove_friend($user_guid, $friend_guid) { global $CONFIG; @@ -337,9 +376,10 @@ function user_remove_friend($user_guid, $friend_guid) { /** * Determines whether or not a user is another user's friend. * - * @param int $user_guid The GUID of the user + * @param int $user_guid The GUID of the user * @param int $friend_guid The GUID of the friend - * @return true|false + * + * @return bool */ function user_is_friend($user_guid, $friend_guid) { return check_entity_relationship($user_guid, "friend", $friend_guid); @@ -348,13 +388,16 @@ function user_is_friend($user_guid, $friend_guid) { /** * Obtains a given user's friends * - * @param int $user_guid The user's GUID - * @param string $subtype The subtype of users, if any - * @param int $limit Number of results to return (default 10) - * @param int $offset Indexing offset, if any + * @param int $user_guid The user's GUID + * @param string $subtype The subtype of users, if any + * @param int $limit Number of results to return (default 10) + * @param int $offset Indexing offset, if any + * * @return false|array Either an array of ElggUsers or false, depending on success */ -function get_user_friends($user_guid, $subtype = ELGG_ENTITIES_ANY_VALUE, $limit = 10, $offset = 0) { +function get_user_friends($user_guid, $subtype = ELGG_ENTITIES_ANY_VALUE, $limit = 10, +$offset = 0) { + return elgg_get_entities_from_relationship(array( 'relationship' => 'friend', 'relationship_guid' => $user_guid, @@ -368,13 +411,16 @@ function get_user_friends($user_guid, $subtype = ELGG_ENTITIES_ANY_VALUE, $limit /** * Obtains the people who have made a given user a friend * - * @param int $user_guid The user's GUID - * @param string $subtype The subtype of users, if any - * @param int $limit Number of results to return (default 10) - * @param int $offset Indexing offset, if any + * @param int $user_guid The user's GUID + * @param string $subtype The subtype of users, if any + * @param int $limit Number of results to return (default 10) + * @param int $offset Indexing offset, if any + * * @return false|array Either an array of ElggUsers or false, depending on success */ -function get_user_friends_of($user_guid, $subtype = ELGG_ENTITIES_ANY_VALUE, $limit = 10, $offset = 0) { +function get_user_friends_of($user_guid, $subtype = ELGG_ENTITIES_ANY_VALUE, $limit = 10, +$offset = 0) { + return elgg_get_entities_from_relationship(array( 'relationship' => 'friend', 'relationship_guid' => $user_guid, @@ -389,15 +435,18 @@ function get_user_friends_of($user_guid, $subtype = ELGG_ENTITIES_ANY_VALUE, $li /** * Obtains a list of objects owned by a user * - * @param int $user_guid The GUID of the owning user - * @param string $subtype Optionally, the subtype of objects - * @param int $limit The number of results to return (default 10) - * @param int $offset Indexing offset, if any - * @param int $timelower The earliest time the entity can have been created. Default: all - * @param int $timeupper The latest time the entity can have been created. Default: all + * @param int $user_guid The GUID of the owning user + * @param string $subtype Optionally, the subtype of objects + * @param int $limit The number of results to return (default 10) + * @param int $offset Indexing offset, if any + * @param int $timelower The earliest time the entity can have been created. Default: all + * @param int $timeupper The latest time the entity can have been created. Default: all + * * @return false|array An array of ElggObjects or false, depending on success */ -function get_user_objects($user_guid, $subtype = ELGG_ENTITIES_ANY_VALUE, $limit = 10, $offset = 0, $timelower = 0, $timeupper = 0) { +function get_user_objects($user_guid, $subtype = ELGG_ENTITIES_ANY_VALUE, $limit = 10, +$offset = 0, $timelower = 0, $timeupper = 0) { + $ntt = elgg_get_entities(array( 'type' => 'object', 'subtype' => $subtype, @@ -414,13 +463,16 @@ function get_user_objects($user_guid, $subtype = ELGG_ENTITIES_ANY_VALUE, $limit /** * Counts the objects (optionally of a particular subtype) owned by a user * - * @param int $user_guid The GUID of the owning user - * @param string $subtype Optionally, the subtype of objects - * @param int $timelower The earliest time the entity can have been created. Default: all - * @param int $timeupper The latest time the entity can have been created. Default: all + * @param int $user_guid The GUID of the owning user + * @param string $subtype Optionally, the subtype of objects + * @param int $timelower The earliest time the entity can have been created. Default: all + * @param int $timeupper The latest time the entity can have been created. Default: all + * * @return int The number of objects the user owns (of this subtype) */ -function count_user_objects($user_guid, $subtype = ELGG_ENTITIES_ANY_VALUE, $timelower = 0, $timeupper = 0) { +function count_user_objects($user_guid, $subtype = ELGG_ENTITIES_ANY_VALUE, $timelower = 0, +$timeupper = 0) { + $total = elgg_get_entities(array( 'type' => 'object', 'subtype' => $subtype, @@ -438,40 +490,47 @@ function count_user_objects($user_guid, $subtype = ELGG_ENTITIES_ANY_VALUE, $tim * * @see elgg_view_entity_list * - * @param int $user_guid The GUID of the user - * @param string $subtype The object subtype - * @param int $limit The number of entities to display on a page - * @param true|false $fullview Whether or not to display the full view (default: true) - * @param true|false $viewtypetoggle Whether or not to allow gallery view (default: true) - * @param true|false $pagination Whether to display pagination (default: true) - * @param int $timelower The earliest time the entity can have been created. Default: all - * @param int $timeupper The latest time the entity can have been created. Default: all + * @param int $user_guid The GUID of the user + * @param string $subtype The object subtype + * @param int $limit The number of entities to display on a page + * @param bool $fullview Whether or not to display the full view (default: true) + * @param bool $viewtypetoggle Whether or not to allow gallery view (default: true) + * @param bool $pagination Whether to display pagination (default: true) + * @param int $timelower The earliest time the entity can have been created. Default: all + * @param int $timeupper The latest time the entity can have been created. Default: all + * * @return string The list in a form suitable to display */ -function list_user_objects($user_guid, $subtype = ELGG_ENTITIES_ANY_VALUE, $limit = 10, $fullview = true, $viewtypetoggle = true, $pagination = true, $timelower = 0, $timeupper = 0) { +function list_user_objects($user_guid, $subtype = ELGG_ENTITIES_ANY_VALUE, $limit = 10, +$fullview = true, $viewtypetoggle = true, $pagination = true, $timelower = 0, $timeupper = 0) { + $offset = (int) get_input('offset'); $limit = (int) $limit; - $count = (int) count_user_objects($user_guid, $subtype,$timelower,$timeupper); + $count = (int) count_user_objects($user_guid, $subtype, $timelower, $timeupper); $entities = get_user_objects($user_guid, $subtype, $limit, $offset, $timelower, $timeupper); - return elgg_view_entity_list($entities, $count, $offset, $limit, $fullview, $viewtypetoggle, $pagination); + return elgg_view_entity_list($entities, $count, $offset, $limit, $fullview, $viewtypetoggle, + $pagination); } /** * Obtains a list of objects owned by a user's friends * - * @param int $user_guid The GUID of the user to get the friends of - * @param string $subtype Optionally, the subtype of objects - * @param int $limit The number of results to return (default 10) - * @param int $offset Indexing offset, if any - * @param int $timelower The earliest time the entity can have been created. Default: all - * @param int $timeupper The latest time the entity can have been created. Default: all + * @param int $user_guid The GUID of the user to get the friends of + * @param string $subtype Optionally, the subtype of objects + * @param int $limit The number of results to return (default 10) + * @param int $offset Indexing offset, if any + * @param int $timelower The earliest time the entity can have been created. Default: all + * @param int $timeupper The latest time the entity can have been created. Default: all + * * @return false|array An array of ElggObjects or false, depending on success */ -function get_user_friends_objects($user_guid, $subtype = ELGG_ENTITIES_ANY_VALUE, $limit = 10, $offset = 0, $timelower = 0, $timeupper = 0) { +function get_user_friends_objects($user_guid, $subtype = ELGG_ENTITIES_ANY_VALUE, $limit = 10, +$offset = 0, $timelower = 0, $timeupper = 0) { + if ($friends = get_user_friends($user_guid, "", 999999, 0)) { $friendguids = array(); - foreach($friends as $friend) { + foreach ($friends as $friend) { $friendguids[] = $friend->getGUID(); } return elgg_get_entities(array( @@ -491,16 +550,19 @@ function get_user_friends_objects($user_guid, $subtype = ELGG_ENTITIES_ANY_VALUE /** * Counts the number of objects owned by a user's friends * - * @param int $user_guid The GUID of the user to get the friends of - * @param string $subtype Optionally, the subtype of objects - * @param int $timelower The earliest time the entity can have been created. Default: all - * @param int $timeupper The latest time the entity can have been created. Default: all + * @param int $user_guid The GUID of the user to get the friends of + * @param string $subtype Optionally, the subtype of objects + * @param int $timelower The earliest time the entity can have been created. Default: all + * @param int $timeupper The latest time the entity can have been created. Default: all + * * @return int The number of objects */ -function count_user_friends_objects($user_guid, $subtype = ELGG_ENTITIES_ANY_VALUE, $timelower = 0, $timeupper = 0) { +function count_user_friends_objects($user_guid, $subtype = ELGG_ENTITIES_ANY_VALUE, +$timelower = 0, $timeupper = 0) { + if ($friends = get_user_friends($user_guid, "", 999999, 0)) { $friendguids = array(); - foreach($friends as $friend) { + foreach ($friends as $friend) { $friendguids[] = $friend->getGUID(); } return elgg_get_entities(array( @@ -521,44 +583,55 @@ function count_user_friends_objects($user_guid, $subtype = ELGG_ENTITIES_ANY_VAL * * @see elgg_view_entity_list * - * @param int $user_guid The GUID of the user - * @param string $subtype The object subtype - * @param int $limit The number of entities to display on a page - * @param true|false $fullview Whether or not to display the full view (default: true) - * @param true|false $viewtypetoggle Whether or not to allow you to flip to gallery mode (default: true) - * @param true|false $pagination Whether to display pagination (default: true) - * @param int $timelower The earliest time the entity can have been created. Default: all - * @param int $timeupper The latest time the entity can have been created. Default: all + * @param int $user_guid The GUID of the user + * @param string $subtype The object subtype + * @param int $limit The number of entities to display on a page + * @param bool $fullview Whether or not to display the full view (default: true) + * @param bool $viewtypetoggle Whether or not to allow you to flip to gallery mode (default: true) + * @param bool $pagination Whether to display pagination (default: true) + * @param int $timelower The earliest time the entity can have been created. Default: all + * @param int $timeupper The latest time the entity can have been created. Default: all + * * @return string The list in a form suitable to display */ -function list_user_friends_objects($user_guid, $subtype = "", $limit = 10, $fullview = true, $viewtypetoggle = true, $pagination = true, $timelower = 0, $timeupper = 0) { +function list_user_friends_objects($user_guid, $subtype = "", $limit = 10, $fullview = true, +$viewtypetoggle = true, $pagination = true, $timelower = 0, $timeupper = 0) { + $offset = (int) get_input('offset'); $limit = (int) $limit; $count = (int) count_user_friends_objects($user_guid, $subtype, $timelower, $timeupper); - $entities = get_user_friends_objects($user_guid, $subtype, $limit, $offset, $timelower, $timeupper); - return elgg_view_entity_list($entities, $count, $offset, $limit, $fullview, $viewtypetoggle, $pagination); + $entities = get_user_friends_objects($user_guid, $subtype, $limit, $offset, + $timelower, $timeupper); + + return elgg_view_entity_list($entities, $count, $offset, $limit, $fullview, + $viewtypetoggle, $pagination); } /** * Get user objects by an array of metadata * - * @param int $user_guid The GUID of the owning user - * @param string $subtype Optionally, the subtype of objects - * @paran array $metadata An array of metadata - * @param int $limit The number of results to return (default 10) - * @param int $offset Indexing offset, if any + * @param int $user_guid The GUID of the owning user + * @param string $subtype Optionally, the subtype of objects + * @param array $metadata An array of metadata + * @param int $limit The number of results to return (default 10) + * @param int $offset Indexing offset, if any + * * @return false|array An array of ElggObjects or false, depending on success */ -function get_user_objects_by_metadata($user_guid, $subtype = "", $metadata = array(), $limit = 0, $offset = 0) { - return get_entities_from_metadata_multi($metadata,"object",$subtype,$user_guid,$limit,$offset); +function get_user_objects_by_metadata($user_guid, $subtype = "", $metadata = array(), +$limit = 0, $offset = 0) { + return get_entities_from_metadata_multi($metadata, "object", $subtype, $user_guid, + $limit, $offset); } /** * Get a user object from a GUID. * * This function returns an ElggUser from a given GUID. + * * @param int $guid The GUID + * * @return ElggUser|false */ function get_user($guid) { @@ -568,7 +641,6 @@ function get_user($guid) { } if ((!empty($result)) && (!($result instanceof ElggUser))) { - //throw new InvalidClassException(sprintf(elgg_echo('InvalidClassException:NotValidElggStar'), $guid, 'ElggUser')); return false; } @@ -583,6 +655,7 @@ function get_user($guid) { * Get user by username * * @param string $username The user's username + * * @return ElggUser|false Depending on success */ function get_user_by_username($username) { @@ -592,11 +665,16 @@ function get_user_by_username($username) { $access = get_access_sql_suffix('e'); // Caching - if ( (isset($USERNAME_TO_GUID_MAP_CACHE[$username])) && (retrieve_cached_entity($USERNAME_TO_GUID_MAP_CACHE[$username])) ) { + if ((isset($USERNAME_TO_GUID_MAP_CACHE[$username])) + && (retrieve_cached_entity($USERNAME_TO_GUID_MAP_CACHE[$username]))) { return retrieve_cached_entity($USERNAME_TO_GUID_MAP_CACHE[$username]); } - $row = get_data_row("SELECT e.* from {$CONFIG->dbprefix}users_entity u join {$CONFIG->dbprefix}entities e on e.guid=u.guid where u.username='$username' and $access "); + $query = "SELECT e.* from {$CONFIG->dbprefix}users_entity u + join {$CONFIG->dbprefix}entities e on e.guid=u.guid + where u.username='$username' and $access "; + + $row = get_data_row($query); if ($row) { $USERNAME_TO_GUID_MAP_CACHE[$username] = $row->guid; return new ElggUser($row); @@ -609,6 +687,7 @@ function get_user_by_username($username) { * Get user by session code * * @param string $code The session code + * * @return ElggUser|false Depending on success */ function get_user_by_code($code) { @@ -619,11 +698,17 @@ function get_user_by_code($code) { $access = get_access_sql_suffix('e'); // Caching - if ( (isset($CODE_TO_GUID_MAP_CACHE[$code])) && (retrieve_cached_entity($CODE_TO_GUID_MAP_CACHE[$code])) ) { + if ((isset($CODE_TO_GUID_MAP_CACHE[$code])) + && (retrieve_cached_entity($CODE_TO_GUID_MAP_CACHE[$code]))) { + return retrieve_cached_entity($CODE_TO_GUID_MAP_CACHE[$code]); } - $row = get_data_row("SELECT e.* from {$CONFIG->dbprefix}users_entity u join {$CONFIG->dbprefix}entities e on e.guid=u.guid where u.code='$code' and $access"); + $query = "SELECT e.* from {$CONFIG->dbprefix}users_entity u + join {$CONFIG->dbprefix}entities e on e.guid=u.guid + where u.code='$code' and $access"; + + $row = get_data_row($query); if ($row) { $CODE_TO_GUID_MAP_CACHE[$code] = $row->guid; return new ElggUser($row); @@ -636,6 +721,7 @@ function get_user_by_code($code) { * Get an array of users from their * * @param string $email Email address. + * * @return Array of users */ function get_user_by_email($email) { @@ -645,7 +731,9 @@ function get_user_by_email($email) { $access = get_access_sql_suffix('e'); - $query = "SELECT e.* from {$CONFIG->dbprefix}entities e join {$CONFIG->dbprefix}users_entity u on e.guid=u.guid where email='$email' and $access"; + $query = "SELECT e.* from {$CONFIG->dbprefix}entities e + join {$CONFIG->dbprefix}users_entity u on e.guid=u.guid + where email='$email' and $access"; return get_data($query, 'entity_row_to_elggstar'); } @@ -653,11 +741,13 @@ function get_user_by_email($email) { /** * Searches for a user based on a complete or partial name or username. * - * @param string $criteria The partial or full name or username. - * @param int $limit Limit of the search. - * @param int $offset Offset. - * @param string $order_by The order. - * @param boolean $count Whether to return the count of results or just the results. + * @param string $criteria The partial or full name or username. + * @param int $limit Limit of the search. + * @param int $offset Offset. + * @param string $order_by The order. + * @param boolean $count Whether to return the count of results or just the results. + * + * @return mixed * @deprecated 1.7 */ function search_for_user($criteria, $limit = 10, $offset = 0, $order_by = "", $count = false) { @@ -680,13 +770,14 @@ function search_for_user($criteria, $limit = 10, $offset = 0, $order_by = "", $c } else { $query = "SELECT e.* "; } - $query .= "from {$CONFIG->dbprefix}entities e join {$CONFIG->dbprefix}users_entity u on e.guid=u.guid where "; - // $query .= " match(u.name,u.username) against ('$criteria') "; + $query .= "from {$CONFIG->dbprefix}entities e + join {$CONFIG->dbprefix}users_entity u on e.guid=u.guid where "; + $query .= "(u.name like \"%{$criteria}%\" or u.username like \"%{$criteria}%\")"; $query .= " and $access"; if (!$count) { - $query .= " order by $order_by limit $offset, $limit"; // Add order and limit + $query .= " order by $order_by limit $offset, $limit"; return get_data($query, "entity_row_to_elggstar"); } else { if ($count = get_data_row($query)) { @@ -701,9 +792,11 @@ function search_for_user($criteria, $limit = 10, $offset = 0, $order_by = "", $c * * @see elgg_view_entity_list * - * @param string $tag Search criteria - * @param int $limit The number of entities to display on a page + * @param string $tag Search criteria + * @param int $limit The number of entities to display on a page + * * @return string The list in a form suitable to display + * * @deprecated 1.7 */ function list_user_search($tag, $limit = 10) { @@ -721,8 +814,10 @@ function list_user_search($tag, $limit = 10) { * $seconds seconds. * * @param int $seconds Number of seconds (default 600 = 10min) - * @param int $limit Limit, default 10. - * @param int $offset Offset, defualt 0. + * @param int $limit Limit, default 10. + * @param int $offset Offset, defualt 0. + * + * @return mixed */ function find_active_users($seconds = 600, $limit = 10, $offset = 0) { global $CONFIG; @@ -735,7 +830,10 @@ function find_active_users($seconds = 600, $limit = 10, $offset = 0) { $access = get_access_sql_suffix("e"); - $query = "SELECT distinct e.* from {$CONFIG->dbprefix}entities e join {$CONFIG->dbprefix}users_entity u on e.guid = u.guid where u.last_action >= {$time} and $access order by u.last_action desc limit {$offset},{$limit}"; + $query = "SELECT distinct e.* from {$CONFIG->dbprefix}entities e + join {$CONFIG->dbprefix}users_entity u on e.guid = u.guid + where u.last_action >= {$time} and $access + order by u.last_action desc limit {$offset}, {$limit}"; return get_data($query, "entity_row_to_elggstar"); } @@ -743,7 +841,9 @@ function find_active_users($seconds = 600, $limit = 10, $offset = 0) { /** * Generate and send a password request email to a given user's registered email address. * - * @param int $user_guid + * @param int $user_guid User GUID + * + * @return bool */ function send_new_password_request($user_guid) { global $CONFIG; @@ -754,7 +854,7 @@ function send_new_password_request($user_guid) { if ($user) { // generate code $code = generate_random_cleartext_password(); - //create_metadata($user_guid, 'conf_code', $code,'', 0, ACCESS_PRIVATE); + //create_metadata($user_guid, 'conf_code', $code, '', 0, ACCESS_PRIVATE); set_private_setting($user_guid, 'passwd_conf_code', $code); // generate link @@ -763,7 +863,8 @@ function send_new_password_request($user_guid) { // generate email $email = sprintf(elgg_echo('email:resetreq:body'), $user->name, $_SERVER['REMOTE_ADDR'], $link); - return notify_user($user->guid, $CONFIG->site->guid, elgg_echo('email:resetreq:subject'), $email, NULL, 'email'); + return notify_user($user->guid, $CONFIG->site->guid, + elgg_echo('email:resetreq:subject'), $email, NULL, 'email'); } return false; @@ -774,8 +875,10 @@ function send_new_password_request($user_guid) { * * This can only be called from execute_new_password_request(). * - * @param int $user_guid The user. - * @param string $password password text (which will then be converted into a hash and stored) + * @param int $user_guid The user. + * @param string $password Text (which will then be converted into a hash and stored) + * + * @return bool */ function force_user_password_reset($user_guid, $password) { global $CONFIG; @@ -789,7 +892,9 @@ function force_user_password_reset($user_guid, $password) { $hash = generate_user_password($user, $password); - return update_data("UPDATE {$CONFIG->dbprefix}users_entity set password='$hash', salt='$salt' where guid=$user_guid"); + $query = "UPDATE {$CONFIG->dbprefix}users_entity + set password='$hash', salt='$salt' where guid=$user_guid"; + return update_data($query); } } @@ -799,8 +904,10 @@ function force_user_password_reset($user_guid, $password) { /** * Validate and execute a password reset for a user. * - * @param int $user_guid The user id + * @param int $user_guid The user id * @param string $conf_code Confirmation code as sent in the request email. + * + * @return mixed */ function execute_new_password_request($user_guid, $conf_code) { global $CONFIG; @@ -818,7 +925,8 @@ function execute_new_password_request($user_guid, $conf_code) { $email = sprintf(elgg_echo('email:resetpassword:body'), $user->name, $password); - return notify_user($user->guid, $CONFIG->site->guid, elgg_echo('email:resetpassword:subject'), $email, NULL, 'email'); + return notify_user($user->guid, $CONFIG->site->guid, + elgg_echo('email:resetpassword:subject'), $email, NULL, 'email'); } } @@ -828,8 +936,9 @@ function execute_new_password_request($user_guid, $conf_code) { /** * Handles pages for password reset requests. * - * @param unknown_type $page - * @return unknown_type + * @param array $page Pages array + * + * @return void */ function elgg_user_resetpassword_page_handler($page) { global $CONFIG; @@ -873,9 +982,11 @@ function elgg_user_resetpassword_page_handler($page) { } /** - * Simple function that will generate a random clear text password suitable for feeding into generate_user_password(). + * Simple function that will generate a random clear text password + * suitable for feeding into generate_user_password(). * * @see generate_user_password + * * @return string */ function generate_random_cleartext_password() { @@ -885,10 +996,10 @@ function generate_random_cleartext_password() { /** * Generate a password for a user, currently uses MD5. * - * Later may introduce salting etc. + * @param ElggUser $user The user this is being generated for. + * @param string $password Password in clear text * - * @param ElggUser $user The user this is being generated for. - * @param string $password Password in clear text + * @return string */ function generate_user_password(ElggUser $user, $password) { return md5($password . $user->salt); @@ -899,7 +1010,9 @@ function generate_user_password(ElggUser $user, $password) { * * This should only permit chars that are valid on the file system as well. * - * @param string $username + * @param string $username Username + * + * @return bool * @throws RegistrationException on invalid */ function validate_username($username) { @@ -915,14 +1028,13 @@ function validate_username($username) { } // Blacklist for bad characters (partially nicked from mediawiki) - $blacklist = '/[' . - '\x{0080}-\x{009f}' . # iso-8859-1 control chars - '\x{00a0}' . # non-breaking space - '\x{2000}-\x{200f}' . # various whitespace - '\x{2028}-\x{202f}' . # breaks and control chars - '\x{3000}' . # ideographic space - '\x{e000}-\x{f8ff}' . # private use + '\x{0080}-\x{009f}' . // iso-8859-1 control chars + '\x{00a0}' . // non-breaking space + '\x{2000}-\x{200f}' . // various whitespace + '\x{2028}-\x{202f}' . // breaks and control chars + '\x{3000}' . // ideographic space + '\x{e000}-\x{f8ff}' . // private use ']/u'; if ( @@ -934,20 +1046,25 @@ function validate_username($username) { // Belts and braces // @todo Tidy into main unicode $blacklist2 = '\'/\\"*& ?#%^(){}[]~?<>;|¬`@-+='; - for ($n=0; $n < strlen($blacklist2); $n++) { - if (strpos($username, $blacklist2[$n])!==false) { - throw new RegistrationException(sprintf(elgg_echo('registration:invalidchars'), $blacklist2[$n], $blacklist2)); + + for ($n = 0; $n < strlen($blacklist2); $n++) { + if (strpos($username, $blacklist2[$n]) !== false) { + $msg = sprintf(elgg_echo('registration:invalidchars'), $blacklist2[$n], $blacklist2); + throw new RegistrationException($msg); } } $result = true; - return trigger_plugin_hook('registeruser:validate:username', 'all', array('username' => $username), $result); + return trigger_plugin_hook('registeruser:validate:username', 'all', + array('username' => $username), $result); } /** * Simple validation of a password. * - * @param string $password + * @param string $password Clear text password + * + * @return bool * @throws RegistrationException on invalid */ function validate_password($password) { @@ -958,13 +1075,15 @@ function validate_password($password) { } $result = true; - return trigger_plugin_hook('registeruser:validate:password', 'all', array('password' => $password), $result); + return trigger_plugin_hook('registeruser:validate:password', 'all', + array('password' => $password), $result); } /** * Simple validation of a email. * - * @param string $address + * @param string $address Email address + * * @throws RegistrationException on invalid * @return bool */ @@ -975,21 +1094,27 @@ function validate_email_address($address) { // Got here, so lets try a hook (defaulting to ok) $result = true; - return trigger_plugin_hook('registeruser:validate:email', 'all', array('email' => $address), $result); + return trigger_plugin_hook('registeruser:validate:email', 'all', + array('email' => $address), $result); } /** * Registers a user, returning false if the username already exists * - * @param string $username The username of the new user - * @param string $password The password - * @param string $name The user's display name - * @param string $email Their email address - * @param bool $allow_multiple_emails Allow the same email address to be registered multiple times? - * @param int $friend_guid Optionally, GUID of a user this user will friend once fully registered + * @param string $username The username of the new user + * @param string $password The password + * @param string $name The user's display name + * @param string $email Their email address + * @param bool $allow_multiple_emails Allow the same email address to be + * registered multiple times? + * @param int $friend_guid GUID of a user to friend once fully registered + * @param string $invitecode An invite code from a friend + * * @return int|false The new user's GUID; false on failure */ -function register_user($username, $password, $name, $email, $allow_multiple_emails = false, $friend_guid = 0, $invitecode = '') { +function register_user($username, $password, $name, $email, +$allow_multiple_emails = false, $friend_guid = 0, $invitecode = '') { + // Load the configuration global $CONFIG; @@ -1084,6 +1209,7 @@ function register_user($username, $password, $name, $email, $allow_multiple_emai * Generates a unique invite code for a user * * @param string $username The username of the user sending the invitation + * * @return string Invite code */ function generate_invite_code($username) { @@ -1094,24 +1220,32 @@ function generate_invite_code($username) { /** * Adds collection submenu items * + * @return void */ function collections_submenu_items() { global $CONFIG; $user = get_loggedin_user(); - add_submenu_item(elgg_echo('friends:collections'), $CONFIG->wwwroot . "pg/collections/" . $user->username); + + add_submenu_item(elgg_echo('friends:collections'), + $CONFIG->wwwroot . "pg/collections/" . $user->username); + add_submenu_item(elgg_echo('friends:collections:add'), $CONFIG->wwwroot . "pg/collections/add"); } /** * Page handler for friends * + * @param array $page_elements Page elements + * + * @return void */ function friends_page_handler($page_elements) { if (isset($page_elements[0]) && $user = get_user_by_username($page_elements[0])) { set_page_owner($user->getGUID()); } if (get_loggedin_userid() == page_owner()) { - // collections_submenu_items(); disabled for now as we no longer use friends collections (replaced by shared access) + // disabled for now as we no longer use friends collections (replaced by shared access) + // collections_submenu_items(); } require_once(dirname(dirname(dirname(__FILE__))) . "/pages/friends/index.php"); } @@ -1119,13 +1253,17 @@ function friends_page_handler($page_elements) { /** * Page handler for friends of * + * @param array $page_elements Page elements + * + * @return void */ function friends_of_page_handler($page_elements) { if (isset($page_elements[0]) && $user = get_user_by_username($page_elements[0])) { set_page_owner($user->getGUID()); } if (get_loggedin_userid() == page_owner()) { - // collections_submenu_items(); disabled for now as we no longer use friends collections (replaced by shared access) + // disabled for now as we no longer use friends collections (replaced by shared access) + // collections_submenu_items(); } require_once(dirname(dirname(dirname(__FILE__))) . "/pages/friends/of.php"); } @@ -1133,6 +1271,9 @@ function friends_of_page_handler($page_elements) { /** * Page handler for friends collections * + * @param array $page_elements Page elements + * + * @return void */ function collections_page_handler($page_elements) { if (isset($page_elements[0])) { @@ -1154,6 +1295,10 @@ function collections_page_handler($page_elements) { /** * Page handler for dashboard + * + * @param array $page_elements Page elements + * + * @return void */ function dashboard_page_handler($page_elements) { require_once(dirname(dirname(dirname(__FILE__))) . "/pages/dashboard/index.php"); @@ -1162,6 +1307,10 @@ function dashboard_page_handler($page_elements) { /** * Page handler for registration + * + * @param array $page_elements Page elements + * + * @return void */ function registration_page_handler($page_elements) { require_once(dirname(dirname(dirname(__FILE__))) . "/pages/account/register.php"); @@ -1172,6 +1321,9 @@ function registration_page_handler($page_elements) { * * This is a fallback for non-JS users who click on the * dropdown login link. + * + * @return void + * @todo finish */ function elgg_user_login_page_handler() { $content = elgg_view_layout('one_column', elgg_view('account/forms/login')); @@ -1187,34 +1339,46 @@ function elgg_user_login_page_handler() { * Sets the last action time of the given user to right now. * * @param int $user_guid The user GUID + * + * @return void */ function set_last_action($user_guid) { $user_guid = (int) $user_guid; global $CONFIG; $time = time(); - execute_delayed_write_query("UPDATE {$CONFIG->dbprefix}users_entity set prev_last_action = last_action, last_action = {$time} where guid = {$user_guid}"); + $query = "UPDATE {$CONFIG->dbprefix}users_entity + set prev_last_action = last_action, + last_action = {$time} where guid = {$user_guid}"; + + execute_delayed_write_query($query); } /** * Sets the last logon time of the given user to right now. * * @param int $user_guid The user GUID + * + * @return boid */ function set_last_login($user_guid) { $user_guid = (int) $user_guid; global $CONFIG; $time = time(); - execute_delayed_write_query("UPDATE {$CONFIG->dbprefix}users_entity set prev_last_login = last_login, last_login = {$time} where guid = {$user_guid}"); + $query = "UPDATE {$CONFIG->dbprefix}users_entity + set prev_last_login = last_login, last_login = {$time} where guid = {$user_guid}"; + + execute_delayed_write_query($query); } /** * Creates a relationship between this site and the user. * - * @param $event - * @param $object_type - * @param $object + * @param string $event create + * @param string $object_type user + * @param ElggUser $object User object + * * @return bool */ function user_create_hook_add_site_relationship($event, $object_type, $object) { @@ -1226,23 +1390,32 @@ function user_create_hook_add_site_relationship($event, $object_type, $object) { /** * Sets up user-related menu items * + * @return void */ function users_pagesetup() { // Load config global $CONFIG; //add submenu options - if (get_context() == "friends" || get_context() == "friendsof") { // || get_context() == "collections") { - disabled as we no longer use collections - add_submenu_item(elgg_echo('friends'),$CONFIG->wwwroot."pg/friends/" . page_owner_entity()->username); - add_submenu_item(elgg_echo('friends:of'),$CONFIG->wwwroot."pg/friendsof/" . page_owner_entity()->username); - if(is_plugin_enabled('members')) + if (get_context() == "friends" || get_context() == "friendsof") { + // || get_context() == "collections") { - disabled as we no longer use collections + + add_submenu_item(elgg_echo('friends'), $CONFIG->wwwroot . "pg/friends/" + . page_owner_entity()->username); + + add_submenu_item(elgg_echo('friends:of'), $CONFIG->wwwroot . "pg/friendsof/" + . page_owner_entity()->username); + + if (is_plugin_enabled('members')) { add_submenu_item(elgg_echo('members:browse'), $CONFIG->wwwroot . "mod/members/index.php"); + } } } /** * Users initialisation function, which establishes the page handler * + * @return void */ function users_init() { // Load config @@ -1253,7 +1426,8 @@ function users_init() { /* if ( isloggedin() && is_plugin_enabled('profile') ) { $user = get_loggedin_user(); - add_menu(elgg_echo('friends'), $CONFIG->wwwroot . "pg/friends/" . $user->username, array(), 'core:friends'); + add_menu(elgg_echo('friends'), $CONFIG->wwwroot . + "pg/friends/" . $user->username, array(), 'core:friends'); } */ @@ -1299,16 +1473,24 @@ function users_init() { //register_action("user/language"); // Register the user type - register_entity_type('user',''); + register_entity_type('user', ''); - register_plugin_hook('usersettings:save','user','users_settings_save'); + register_plugin_hook('usersettings:save', 'user', 'users_settings_save'); register_elgg_event_handler('create', 'user', 'user_create_hook_add_site_relationship'); } /** * Returns a formatted list of users suitable for injecting into search. + * * @deprecated 1.7 + * + * @param string $hook Hook name + * @param string $user User? + * @param mixed $returnvalue Previous hook's return value + * @param mixed $tag Tag to search against + * + * @return void */ function search_list_users_by_name($hook, $user, $returnvalue, $tag) { elgg_deprecated_notice('search_list_users_by_name() was deprecated by new search', 1.7); @@ -1318,20 +1500,29 @@ function search_list_users_by_name($hook, $user, $returnvalue, $tag) { $object = get_input('object'); if (!get_input('offset') && (empty($object) || $object == 'user')) { - if ($users = search_for_user($tag,$threshold)) { - $countusers = search_for_user($tag,0,0,"",true); + if ($users = search_for_user($tag, $threshold)) { + $countusers = search_for_user($tag, 0, 0, "", true); - $return = elgg_view('user/search/startblurb',array('count' => $countusers, 'tag' => $tag)); - foreach($users as $user) { + $return = elgg_view('user/search/startblurb', array('count' => $countusers, 'tag' => $tag)); + foreach ($users as $user) { $return .= elgg_view_entity($user); } - $return .= elgg_view('user/search/finishblurb',array('count' => $countusers, 'threshold' => $threshold, 'tag' => $tag)); + + $vars = array('count' => $countusers, 'threshold' => $threshold, 'tag' => $tag); + $return .= elgg_view('user/search/finishblurb', $vars); return $return; } } } +/** + * Saves user settings by directly including actions. + * + * @todo this is dirty. + * + * @return void + */ function users_settings_save() { global $CONFIG; include($CONFIG->path . "actions/user/name.php"); @@ -1343,6 +1534,13 @@ function users_settings_save() { /** * Runs unit tests for ElggObject + * + * @param sting $hook unit_test + * @param string $type system + * @param mixed $value Array of tests + * @param mixed $params Params + * + * @return array */ function users_test($hook, $type, $value, $params) { global $CONFIG; @@ -1350,7 +1548,6 @@ function users_test($hook, $type, $value, $params) { return $value; } -//register actions ************************************************************* -register_elgg_event_handler('init','system','users_init',0); -register_elgg_event_handler('pagesetup','system','users_pagesetup',0); +register_elgg_event_handler('init', 'system', 'users_init', 0); +register_elgg_event_handler('pagesetup', 'system', 'users_pagesetup', 0); register_plugin_hook('unit_test', 'system', 'users_test');
\ No newline at end of file diff --git a/engine/lib/usersettings.php b/engine/lib/usersettings.php index a815556dd..bec202b8a 100644 --- a/engine/lib/usersettings.php +++ b/engine/lib/usersettings.php @@ -3,31 +3,41 @@ * Elgg user settings functions. * Functions for adding and manipulating options on the user settings panel. * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage Settings.User */ /** * Register a user settings page with the admin panel. - * This function extends the view "usersettings/main" with the provided view. This view should provide a description - * and either a control or a link to. + * This function extends the view "usersettings/main" with the provided view. + * This view should provide a description and either a control or a link to. * * Usage: * - To add a control to the main admin panel then extend usersettings/main - * - To add a control to a new page create a page which renders a view usersettings/subpage (where subpage is your new page - - * nb. some pages already exist that you can extend), extend the main view to point to it, and add controls to your - * new view. + * - To add a control to a new page create a page which renders a view + * usersettings/subpage (where subpage is your new page - + * nb. some pages already exist that you can extend), extend the main view + * to point to it, and add controls to your new view. * * At the moment this is essentially a wrapper around elgg_extend_view(). * * @param string $new_settings_view The view associated with the control you're adding - * @param string $view The view to extend, by default this is 'usersettings/main'. - * @param int $priority Optional priority to govern the appearance in the list. + * @param string $view The view to extend, by default this is 'usersettings/main'. + * @param int $priority Optional priority to govern the appearance in the list. + * + * @return bool */ -function extend_elgg_settings_page( $new_settings_view, $view = 'usersettings/main', $priority = 500) { +function extend_elgg_settings_page($new_settings_view, $view = 'usersettings/main', +$priority = 500) { + return elgg_extend_view($view, $new_settings_view, $priority); } +/** + * Set up the page for user settings + * + * @return void + */ function usersettings_pagesetup() { // Get config global $CONFIG; @@ -35,12 +45,24 @@ function usersettings_pagesetup() { // Menu options if (get_context() == "settings") { $user = get_loggedin_user(); - add_submenu_item(elgg_echo('usersettings:user:opt:linktext'),$CONFIG->wwwroot . "pg/settings/user/{$user->username}/"); - add_submenu_item(elgg_echo('usersettings:plugins:opt:linktext'),$CONFIG->wwwroot . "pg/settings/plugins/{$user->username}/"); - add_submenu_item(elgg_echo('usersettings:statistics:opt:linktext'),$CONFIG->wwwroot . "pg/settings/statistics/{$user->username}/"); + add_submenu_item(elgg_echo('usersettings:user:opt:linktext'), + $CONFIG->wwwroot . "pg/settings/user/{$user->username}/"); + + add_submenu_item(elgg_echo('usersettings:plugins:opt:linktext'), + $CONFIG->wwwroot . "pg/settings/plugins/{$user->username}/"); + + add_submenu_item(elgg_echo('usersettings:statistics:opt:linktext'), + $CONFIG->wwwroot . "pg/settings/statistics/{$user->username}/"); } } +/** + * Page handler for user settings + * + * @param array $page Pages array + * + * @return void + */ function usersettings_page_handler($page) { global $CONFIG; @@ -69,12 +91,14 @@ function usersettings_page_handler($page) { /** * Initialise the admin page. + * + * @return void */ function usersettings_init() { // Page handler - register_page_handler('settings','usersettings_page_handler'); + register_page_handler('settings', 'usersettings_page_handler'); } /// Register init function -register_elgg_event_handler('init','system','usersettings_init'); -register_elgg_event_handler('pagesetup','system','usersettings_pagesetup');
\ No newline at end of file +register_elgg_event_handler('init', 'system', 'usersettings_init'); +register_elgg_event_handler('pagesetup', 'system', 'usersettings_pagesetup');
\ No newline at end of file diff --git a/engine/lib/version.php b/engine/lib/version.php index db3eb907e..c11707417 100644 --- a/engine/lib/version.php +++ b/engine/lib/version.php @@ -3,15 +3,17 @@ * Elgg version library. * Contains code for handling versioning and upgrades. * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage Version */ /** * Run any php upgrade scripts which are required * - * @param int $version Version upgrading from. - * @param bool $quiet Suppress errors. Don't use this. + * @param int $version Version upgrading from. + * @param bool $quiet Suppress errors. Don't use this. + * + * @return bool */ function upgrade_code($version, $quiet = FALSE) { global $CONFIG; @@ -42,7 +44,7 @@ function upgrade_code($version, $quiet = FALSE) { asort($upgrades); if (sizeof($upgrades) > 0) { - foreach($upgrades as $upgrade) { + foreach ($upgrades as $upgrade) { // hide all errors. if ($quiet) { // hide include errors as well as any exceptions that might happen @@ -68,7 +70,8 @@ function upgrade_code($version, $quiet = FALSE) { /** * Get the current version information * - * @param true|false $humanreadable Whether to return a human readable version (default: false) + * @param bool $humanreadable Whether to return a human readable version (default: false) + * * @return string|false Depending on success */ function get_version($humanreadable = false) { @@ -98,13 +101,15 @@ function version_upgrade_check() { } /** - * Upgrades Elgg + * Upgrades Elgg Database and code + * + * @return bool * */ function version_upgrade() { // It's possible large upgrades could exceed the max execution time. set_time_limit(0); - + $dbversion = (int) datalist_get('version'); // No version number? Oh snap...this is an upgrade from a clean installation < 1.7. diff --git a/engine/lib/views.php b/engine/lib/views.php index cceb71c55..755fa9da2 100644 --- a/engine/lib/views.php +++ b/engine/lib/views.php @@ -64,6 +64,7 @@ $CURRENT_SYSTEM_VIEWTYPE = ""; * @tip Call elgg_set_viewtype() with no parameter to reset. * * @param string $viewtype The view type, e.g. 'rss', or 'default'. + * * @return bool * @link http://docs.elgg.org/Views/Viewtype * @example views/viewtype.php @@ -102,10 +103,12 @@ function elgg_get_viewtype() { } // @todo what is this? Why would you want to save a viewtype to the session? - if ((empty($_SESSION['view'])) || ( (trim($CONFIG->view!="")) && ($_SESSION['view']!=$CONFIG->view) )) { + if ((empty($_SESSION['view'])) || ( (trim($CONFIG->view != "")) + && ($_SESSION['view'] != $CONFIG->view) )) { + $_SESSION['view'] = "default"; // If we have a config default view for this site then use that instead of 'default' - if ((!empty($CONFIG->view)) && (trim($CONFIG->view)!="")) { + if ((!empty($CONFIG->view)) && (trim($CONFIG->view) != "")) { $_SESSION['view'] = $CONFIG->view; } } @@ -128,6 +131,8 @@ function elgg_get_viewtype() { * @tip This is useful for alternate html viewtypes (such as for mobile devices). * * @param string $viewtype The viewtype to register + * + * @return void * @since 1.7.2 * @example views/viewtype_fallback.php Fallback from mobile to default. */ @@ -148,7 +153,8 @@ function elgg_register_viewtype_fallback($viewtype) { /** * Checks if a viewtype falls back to default. * - * @param string $viewtype + * @param string $viewtype Viewtype + * * @return boolean * @since 1.7.2 */ @@ -169,9 +175,10 @@ function elgg_does_viewtype_fallback($viewtype) { * @warning This doesn't check if the file exists, but only * constructs (or extracts) the path and returns it. * - * @param string $view The view. + * @param string $view The view. * @param string $viewtype The viewtype - * Views + * + * @return string */ function elgg_get_view_location($view, $viewtype = '') { global $CONFIG; @@ -213,11 +220,15 @@ function elgg_get_view_location($view, $viewtype = '') { * @warning Any variables in $_SESSION will override passed vars * upon name collision. See {@trac #2124}. * - * @param string $view The name and location of the view to use - * @param array $vars Variables to pass to the view. - * @param boolean $bypass If set to true, elgg_view will bypass any specified alternative template handler; by default, it will hand off to this if requested (see set_template_handler) - * @param boolean $debug If set to true, the viewer will complain if it can't find a view - * @param string $viewtype If set, forces the viewtype for the elgg_view call to be this value (default: standard detection) + * @param string $view The name and location of the view to use + * @param array $vars Variables to pass to the view. + * @param boolean $bypass If set to true, elgg_view will bypass any specified + * alternative template handler; by default, it will + * hand off to this if requested (see set_template_handler) + * @param boolean $debug If set to true, the viewer will complain if it can't find a view + * @param string $viewtype If set, forces the viewtype for the elgg_view call to be + * this value (default: standard detection) + * * @return string The parsed view * @see set_template_handler() * @example views/elgg_view.php @@ -240,7 +251,7 @@ function elgg_view($view, $vars = array(), $bypass = false, $debug = false, $vie // Trigger the pagesetup event if (!isset($CONFIG->pagesetupdone)) { - trigger_elgg_event('pagesetup','system'); + trigger_elgg_event('pagesetup', 'system'); $CONFIG->pagesetupdone = true; } @@ -321,7 +332,7 @@ function elgg_view($view, $vars = array(), $bypass = false, $debug = false, $vie // Start the output buffer, find the requested view file, and execute it ob_start(); - foreach($viewlist as $priority => $view) { + foreach ($viewlist as $priority => $view) { $view_location = elgg_get_view_location($view, $viewtype); $view_file = "$view_location$viewtype/$view.php"; @@ -357,7 +368,8 @@ function elgg_view($view, $vars = array(), $bypass = false, $debug = false, $vie array('view' => $view_orig, 'vars' => $vars), $content); // backward compatibility with less grandular hook will be gone in 2.0 - $content_tmp = trigger_plugin_hook('display', 'view', array('view' => $view_orig, 'vars' => $vars), $content); + $params = array('view' => $view_orig, 'vars' => $vars); + $content_tmp = trigger_plugin_hook('display', 'view', $params, $content); if ($content_tmp != $content) { $content = $content_tmp; @@ -372,9 +384,10 @@ function elgg_view($view, $vars = array(), $bypass = false, $debug = false, $vie * * @note If $recurse is strue, also checks if a view exists only as an extension. * - * @param string $view The view name + * @param string $view The view name * @param string $viewtype If set, forces the viewtype - * @param bool $recurse If false, do not check extensions + * @param bool $recurse If false, do not check extensions + * * @return bool */ function elgg_view_exists($view, $viewtype = '', $recurse = true) { @@ -402,7 +415,7 @@ function elgg_view_exists($view, $viewtype = '', $recurse = true) { // If we got here then check whether this exists as an extension // We optionally recursively check whether the extended view exists also for the viewtype if ($recurse && isset($CONFIG->views->extensions[$view])) { - foreach( $CONFIG->views->extensions[$view] as $view_extension ) { + foreach ($CONFIG->views->extensions[$view] as $view_extension) { // do not recursively check to stay away from infinite loops if (elgg_view_exists($view_extension, $viewtype, false)) { return true; @@ -428,6 +441,8 @@ function elgg_view_exists($view, $viewtype = '', $recurse = true) { * @note CSS and the basic JS views are automatically cached. * * @param string $viewname View name + * + * @return void * @link http://docs.elgg.org/Views/Simplecache * @see elgg_view_regenerate_simplecache() */ @@ -451,6 +466,8 @@ function elgg_view_register_simplecache($viewname) { * @warning This does not invalidate the cache, but actively resets it. * * @param string $viewtype Optional viewtype to regenerate + * + * @return void * @see elgg_view_register_simplecache() */ function elgg_view_regenerate_simplecache($viewtype = NULL) { @@ -510,6 +527,7 @@ function elgg_view_regenerate_simplecache($viewtype = NULL) { * * @access private * @see elgg_view_register_simplecache() + * @return void */ function elgg_view_enable_simplecache() { global $CONFIG; @@ -526,18 +544,19 @@ function elgg_view_enable_simplecache() { * * @access private * @see elgg_view_register_simplecache() + * @return void */ function elgg_view_disable_simplecache() { global $CONFIG; if ($CONFIG->simplecache_enabled) { - datalist_set('simplecache_enabled',0); + datalist_set('simplecache_enabled', 0); $CONFIG->simplecache_enabled = 0; // purge simple cache - if ($handle = opendir($CONFIG->dataroot.'views_simplecache')) { + if ($handle = opendir($CONFIG->dataroot . 'views_simplecache')) { while (false !== ($file = readdir($handle))) { if ($file != "." && $file != "..") { - unlink($CONFIG->dataroot.'views_simplecache/'.$file); + unlink($CONFIG->dataroot . 'views_simplecache/' . $file); } } closedir($handle); @@ -548,6 +567,7 @@ function elgg_view_disable_simplecache() { /** * Invalidates all cached views in the simplecache * + * @return bool * @since 1.7.4 */ function elgg_invalidate_simplecache() { @@ -558,7 +578,7 @@ function elgg_invalidate_simplecache() { if ($handle = opendir($CONFIG->dataroot . 'views_simplecache')) { while (false !== ($file = readdir($handle))) { if ($file != "." && $file != "..") { - $return = $return && unlink($CONFIG->dataroot.'views_simplecache/'.$file); + $return = $return && unlink($CONFIG->dataroot . 'views_simplecache/' . $file); } } closedir($handle); @@ -574,24 +594,26 @@ function elgg_invalidate_simplecache() { * * Use this to get all namespaced views under the first element. * - * @param string $dir The main directory that holds the views. (mod/profile/views/) + * @param string $dir The main directory that holds the views. (mod/profile/views/) * @param string $base The root name of the view to use, without the viewtype. (profile) + * * @return array * @since 1.7.0 - * @todo Why isn't this used anywhere else but in elgg_view_tree()? Seems like a useful function for autodiscovery. + * @todo Why isn't this used anywhere else but in elgg_view_tree()? + * Seems like a useful function for autodiscovery. */ function elgg_get_views($dir, $base) { $return = array(); if (file_exists($dir) && is_dir($dir)) { if ($handle = opendir($dir)) { while ($view = readdir($handle)) { - if (!in_array($view, array('.','..','.svn','CVS'))) { + if (!in_array($view, array('.', '..', '.svn', 'CVS'))) { if (is_dir($dir . '/' . $view)) { if ($val = elgg_get_views($dir . '/' . $view, $base . '/' . $view)) { $return = array_merge($return, $val); } } else { - $view = str_replace('.php','',$view); + $view = str_replace('.php', '', $view); $return[] = $base . '/' . $view; } } @@ -603,9 +625,14 @@ function elgg_get_views($dir, $base) { } /** + * Get views in a dir + * * @deprecated 1.7. Use elgg_get_views(). - * @param $dir - * @param $base + * + * @param string $dir Dir + * @param string $base Base view + * + * @return array */ function get_views($dir, $base) { elgg_deprecated_notice('get_views() was deprecated by elgg_get_views()!', 1.7); @@ -619,7 +646,9 @@ function get_views($dir, $base) { * the "profile" namespace. * * @param string $view_root The root view - * @param string $viewtype Optionally specify a view type other than the current one. + * @param string $viewtype Optionally specify a view type + * other than the current one. + * * @return array A list of view names underneath that root view * @todo This is used once in the deprecated get_activity_stream_data() function. */ @@ -643,8 +672,8 @@ function elgg_view_tree($view_root, $viewtype = "") { // Examine $CONFIG->views->locations if (isset($CONFIG->views->locations[$viewtype])) { - foreach($CONFIG->views->locations[$viewtype] as $view => $path) { - $pos = strpos($view,$view_root); + foreach ($CONFIG->views->locations[$viewtype] as $view => $path) { + $pos = strpos($view, $view_root); if ($pos === 0) { $treecache[$view_root][] = $view; } @@ -684,9 +713,11 @@ function elgg_view_tree($view_root, $viewtype = "") { * {@link elgg_view_entity_annotations()}. * * @param ElggEntity $entity The entity to display - * @param boolean $full Passed to entity view to decide how much information to show. - * @param boolean $bypass If false, will not pass to a custom template handler. {@see set_template_handler()} - * @param boolean $debug Complain if views are missing + * @param boolean $full Passed to entity view to decide how much information to show. + * @param boolean $bypass If false, will not pass to a custom template handler. + * {@see set_template_handler()} + * @param boolean $debug Complain if views are missing + * * @return string HTML to display or false * @link http://docs.elgg.org/Views/Entity * @link http://docs.elgg.org/Entities @@ -729,13 +760,13 @@ function elgg_view_entity(ElggEntity $entity, $full = false, $bypass = true, $de ), $bypass, $debug); } if (empty($contents)) { - $contents = elgg_view("{$entity_type}/default",array( + $contents = elgg_view("{$entity_type}/default", array( 'entity' => $entity, 'full' => $full ), $bypass, $debug); } // Marcus Povey 20090616 : Speculative and low impact approach for fixing #964 - if ($full) { + if ($full) { $annotations = elgg_view_entity_annotations($entity, $full); if ($annotations) { @@ -758,8 +789,10 @@ function elgg_view_entity(ElggEntity $entity, $full = false, $bypass = true, $de * - ElggEntity 'annotation' The annotation being viewed. * * @param ElggAnnotation $annotation The annotation to display - * @param boolean $bypass If false, will not pass to a custom template handler. {@see set_template_handler()} - * @param boolean $debug Complain if views are missing + * @param boolean $bypass If false, will not pass to a custom + * template handler. {@see set_template_handler()} + * @param boolean $debug Complain if views are missing + * * @return string HTML (etc) to display */ function elgg_view_annotation(ElggAnnotation $annotation, $bypass = true, $debug = false) { @@ -768,7 +801,7 @@ function elgg_view_annotation(ElggAnnotation $annotation, $bypass = true, $debug $view = $annotation->view; if (is_string($view)) { - return elgg_view($view,array('annotation' => $annotation), $bypass, $debug); + return elgg_view($view, array('annotation' => $annotation), $bypass, $debug); } $name = $annotation->name; @@ -781,9 +814,9 @@ function elgg_view_annotation(ElggAnnotation $annotation, $bypass = true, $debug } if (elgg_view_exists("annotation/{$name}")) { - return elgg_view("annotation/{$name}",array('annotation' => $annotation), $bypass, $debug); + return elgg_view("annotation/{$name}", array('annotation' => $annotation), $bypass, $debug); } else { - return elgg_view("annotation/default",array('annotation' => $annotation), $bypass, $debug); + return elgg_view("annotation/default", array('annotation' => $annotation), $bypass, $debug); } } @@ -800,17 +833,20 @@ function elgg_view_annotation(ElggAnnotation $annotation, $bypass = true, $debug * @see list_entities_from_relationships() * @see list_site_members() * - * @param array $entities List of entities - * @param int $count The total number of entities across all pages - * @param int $offset The current indexing offset - * @param int $limit The number of entities to display per page - * @param true|false $fullview Whether or not to display the full view (default: true) - * @param true|false $viewtypetoggle Whether or not to allow users to toggle to gallery view - * @param bool $pagination Whether pagination is offered. + * @param array $entities List of entities + * @param int $count The total number of entities across all pages + * @param int $offset The current indexing offset + * @param int $limit The number of entities to display per page + * @param bool $fullview Whether or not to display the full view (default: true) + * @param bool $viewtypetoggle Whether or not to allow users to toggle to gallery view + * @param bool $pagination Whether pagination is offered. + * * @return string The list of entities * @access private */ -function elgg_view_entity_list($entities, $count, $offset, $limit, $fullview = true, $viewtypetoggle = true, $pagination = true) { +function elgg_view_entity_list($entities, $count, $offset, $limit, $fullview = true, +$viewtypetoggle = true, $pagination = true) { + $count = (int) $count; $limit = (int) $limit; @@ -821,7 +857,7 @@ function elgg_view_entity_list($entities, $count, $offset, $limit, $fullview = t $context = get_context(); - $html = elgg_view('entities/entity_list',array( + $html = elgg_view('entities/entity_list', array( 'entities' => $entities, 'count' => $count, 'offset' => $offset, @@ -830,7 +866,7 @@ function elgg_view_entity_list($entities, $count, $offset, $limit, $fullview = t 'fullview' => $fullview, 'context' => $context, 'viewtypetoggle' => $viewtypetoggle, - 'viewtype' => get_input('search_viewtype','list'), + 'viewtype' => get_input('search_viewtype', 'list'), 'pagination' => $pagination )); @@ -842,9 +878,10 @@ function elgg_view_entity_list($entities, $count, $offset, $limit, $fullview = t * should be called by wrapper functions. * * @param array $annotations List of annotations - * @param int $count The total number of annotations across all pages - * @param int $offset The current indexing offset - * @param int $limit The number of annotations to display per page + * @param int $count The total number of annotations across all pages + * @param int $offset The current indexing offset + * @param int $limit The number of annotations to display per page + * * @return string The list of annotations * @access private */ @@ -855,7 +892,7 @@ function elgg_view_annotation_list($annotations, $count, $offset, $limit) { $html = ""; - $nav = elgg_view('navigation/pagination',array( + $nav = elgg_view('navigation/pagination', array( 'baseurl' => $_SERVER['REQUEST_URI'], 'offset' => $offset, 'count' => $count, @@ -867,7 +904,7 @@ function elgg_view_annotation_list($annotations, $count, $offset, $limit) { $html .= $nav; if (is_array($annotations) && sizeof($annotations) > 0) { - foreach($annotations as $annotation) { + foreach ($annotations as $annotation) { $html .= elgg_view_annotation($annotation, "", false); } } @@ -887,8 +924,9 @@ function elgg_view_annotation_list($annotations, $count, $offset, $limit) { * * This is called automatically by the framework from {@link elgg_view_entity()} * - * @param ElggEntity $entity - * @param bool $full + * @param ElggEntity $entity Entity + * @param bool $full Full view? + * * @return mixed string or false on failure * @todo Change the hook name. */ @@ -933,6 +971,7 @@ function elgg_view_entity_annotations(ElggEntity $entity, $full = true) { * argument names. * * @param string $layout The name of the views in canvas/layouts/. + * * @return string The layout * @todo Make this consistent with the rest of the view functions by passing * an array instead of "$areaN". @@ -946,9 +985,9 @@ function elgg_view_layout($layout) { } if (elgg_view_exists("canvas/layouts/{$layout}")) { - return elgg_view("canvas/layouts/{$layout}",$param_array); + return elgg_view("canvas/layouts/{$layout}", $param_array); } else { - return elgg_view("canvas/default",$param_array); + return elgg_view("canvas/default", $param_array); } } @@ -957,8 +996,9 @@ function elgg_view_layout($layout) { * * This is a shortcut for {@elgg_view page_elements/title}. * - * @param string $title The page title + * @param string $title The page title * @param string $submenu Should a submenu be displayed? (default false, use not recommended) + * * @return string The HTML (etc) */ function elgg_view_title($title, $submenu = false) { @@ -973,6 +1013,7 @@ function elgg_view_title($title, $submenu = false) { * @see elgg_get_friendly_time() * * @param int $time A UNIX epoch timestamp + * * @return string The friendly time HTML * @since 1.7.2 */ @@ -988,24 +1029,26 @@ function elgg_view_friendly_time($time) { * for the comments, $entity_type hook. The handler is responsible * for formatting the comments and add comment form. * - * @param ElggEntity $entity - * @param bool $add_comment Include a form to add comments + * @param ElggEntity $entity The entity to view comments of + * @param bool $add_comment Include a form to add comments + * * @return string|false The HTML (etc) for the comments, or false on failure * @link http://docs.elgg.org/Entities/Comments * @link http://docs.elgg.org/Annotations/Comments */ -function elgg_view_comments($entity, $add_comment = true){ +function elgg_view_comments($entity, $add_comment = true) { if (!($entity instanceof ElggEntity)) { return false; } - if ($comments = trigger_plugin_hook('comments', $entity->getType(), array('entity' => $entity), false)) { + $comments = trigger_plugin_hook('comments', $entity->getType(), array('entity' => $entity), false); + if ($comemnts) { return $comments; } else { $comments = list_annotations($entity->getGUID(), 'generic_comment'); //display the new comment form if required - if($add_comment){ + if ($add_comment) { $comments .= elgg_view('comments/forms/edit', array('entity' => $entity)); } @@ -1019,10 +1062,11 @@ function elgg_view_comments($entity, $add_comment = true){ * * @param string $icon The icon for the listing * @param string $info Any information that needs to be displayed. + * * @return string The HTML (etc) representing the listing */ function elgg_view_listing($icon, $info) { - return elgg_view('entities/entity_listing',array('icon' => $icon, 'info' => $info)); + return elgg_view('entities/entity_listing', array('icon' => $icon, 'info' => $info)); } /** @@ -1040,9 +1084,10 @@ function elgg_view_listing($icon, $info) { * * @warning This is experimental. * - * @see elgg_view() * @param string $function_name The name of the function to pass to. + * * @return bool + * @see elgg_view() * @link http://docs.elgg.org/Views/TemplateHandlers */ function set_template_handler($function_name) { @@ -1068,10 +1113,13 @@ function set_template_handler($function_name) { * @internal View extensions are stored in * $CONFIG->views->extensions[$view][$priority] = $view_extension * - * @param string $view The view to extend. + * @param string $view The view to extend. * @param string $view_extension This view is added to $view - * @param int $priority The priority, from 0 to 1000, to add at (lowest numbers displayed first) - * @param string $viewtype Not used + * @param int $priority The priority, from 0 to 1000, + * to add at (lowest numbers displayed first) + * @param string $viewtype Not used + * + * @return void * @since 1.7.0 * @link http://docs.elgg.org/Views/Ejxtend * @example views/extend.php @@ -1091,7 +1139,7 @@ function elgg_extend_view($view, $view_extension, $priority = 501, $viewtype = ' $CONFIG->views->extensions[$view][500] = "{$view}"; } - while(isset($CONFIG->views->extensions[$view][$priority])) { + while (isset($CONFIG->views->extensions[$view][$priority])) { $priority++; } @@ -1102,8 +1150,9 @@ function elgg_extend_view($view, $view_extension, $priority = 501, $viewtype = ' /** * Unextends a view. * - * @param string $view The view that was extended. + * @param string $view The view that was extended. * @param string $view_extension This view that was added to $view + * * @return bool * @since 1.7.2 */ @@ -1133,11 +1182,17 @@ function elgg_unextend_view($view, $view_extension) { } /** + * Extend a view + * * @deprecated 1.7. Use elgg_extend_view(). - * @param $view - * @param $view_name - * @param $priority - * @param $viewtype + * + * @param string $view The view to extend. + * @param string $view_name This view is added to $view + * @param int $priority The priority, from 0 to 1000, + * to add at (lowest numbers displayed first) + * @param string $viewtype Not used + * + * @return void */ function extend_view($view, $view_name, $priority = 501, $viewtype = '') { elgg_deprecated_notice('extend_view() was deprecated by elgg_extend_view()!', 1.7); @@ -1154,8 +1209,11 @@ function extend_view($view, $view_name, $priority = 501, $viewtype = '') { * * @tip This is useful to optionally register views in a plugin. * - * @param string $view The name of the view + * @param string $view The name of the view * @param string $location The base location path + * @param string $viewtype The view type + * + * @return void */ function set_view_location($view, $location, $viewtype = '') { global $CONFIG; @@ -1186,10 +1244,12 @@ function set_view_location($view, $location, $viewtype = '') { * Plugin authors would only need to call this if optionally including * an entire views structure. * - * @param string $view_base Optional The base of the view name without the view type. - * @param string $folder Required The folder to begin looking in + * @param string $view_base Optional The base of the view name without the view type. + * @param string $folder Required The folder to begin looking in * @param string $base_location_path The base views directory to use with set_view_location - * @param string $viewtype The type of view we're looking at (default, rss, etc) + * @param string $viewtype The type of view we're looking at (default, rss, etc) + * + * @return void * @since 1.7.0 * @see set_view_location() * @todo This seems overly complicated. @@ -1201,7 +1261,7 @@ function autoregister_views($view_base, $folder, $base_location_path, $viewtype) if ($handle = opendir($folder)) { while ($view = readdir($handle)) { - if (!in_array($view, array('.','..','.svn','CVS')) && !is_dir($folder . "/" . $view)) { + if (!in_array($view, array('.', '..', '.svn', 'CVS')) && !is_dir($folder . "/" . $view)) { // this includes png files because some icons are stored within view directories. // See commit [1705] if ((substr_count($view, ".php") > 0) || (substr_count($view, ".png") > 0)) { @@ -1211,7 +1271,8 @@ function autoregister_views($view_base, $folder, $base_location_path, $viewtype) $view_base_new = ""; } - set_view_location($view_base_new . str_replace('.php', '', $view), $base_location_path, $viewtype); + set_view_location($view_base_new . str_replace('.php', '', $view), + $base_location_path, $viewtype); } } else if (!in_array($view, array('.', '..', '.svn', 'CVS')) && is_dir($folder . "/" . $view)) { if (!empty($view_base)) { @@ -1219,7 +1280,8 @@ function autoregister_views($view_base, $folder, $base_location_path, $viewtype) } else { $view_base_new = ""; } - autoregister_views($view_base_new . $view, $folder . "/" . $view, $base_location_path, $viewtype); + autoregister_views($view_base_new . $view, $folder . "/" . $view, + $base_location_path, $viewtype); } } return TRUE; @@ -1235,10 +1297,12 @@ function autoregister_views($view_base, $folder, $base_location_path, $viewtype) * can be HTML for a browser, RSS for a feed reader, or * Javascript, PHP and a number of other formats. * - * @param string $title - * @param string $body + * @param string $title Title + * @param string $body Body * @param string $page_shell Optional page shell to use. - * @param array $vars Optional vars array to pass to the page shell. Automatically adds title, body, and sysmessages + * @param array $vars Optional vars array to pass to the page + * shell. Automatically adds title, body, and sysmessages + * * @return NULL */ function page_draw($title, $body, $page_shell = 'page_shells/default', $vars = array()) { @@ -1267,7 +1331,7 @@ function page_draw($title, $body, $page_shell = 'page_shells/default', $vars = a $split_output = str_split($output, 1024); - foreach($split_output as $chunk) { + foreach ($split_output as $chunk) { echo $chunk; } } @@ -1275,7 +1339,8 @@ function page_draw($title, $body, $page_shell = 'page_shells/default', $vars = a /** * Checks if $view_type is valid on this installation. * - * @param string $view_type + * @param string $view_type View type + * * @return bool * @since 1.7.2 */ @@ -1294,6 +1359,7 @@ function elgg_is_valid_view_type($view_type) { * Initialize viewtypes on system boot event * This ensures simplecache is cleared during upgrades. See #2252 * + * @return void * @access private * @elgg_event_handler boot system */ diff --git a/engine/lib/widgets.php b/engine/lib/widgets.php index b87344c29..c849596d4 100644 --- a/engine/lib/widgets.php +++ b/engine/lib/widgets.php @@ -3,14 +3,16 @@ * Elgg widgets library. * Contains code for handling widgets. * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage Widgets */ /** * Register a particular context for use with widgets. * * @param string $context The context we wish to enable context for + * + * @return void */ function use_widgets($context) { global $CONFIG; @@ -31,14 +33,16 @@ function use_widgets($context) { /** * Determines whether or not the current context is using widgets * - * @return true|false Depending on widget status + * @return bool Depending on widget status */ function using_widgets() { global $CONFIG; $context = get_context(); if (isset($CONFIG->widgets->contexts) && is_array($CONFIG->widgets->contexts)) { - if (in_array($context, $CONFIG->widgets->contexts)) return true; + if (in_array($context, $CONFIG->widgets->contexts)) { + return true; + } } return false; @@ -49,9 +53,10 @@ function using_widgets() { * and also provides a sensible ordering for all widgets in that column * * @param ElggObject $widget The widget entity - * @param int $order The order within the column - * @param int $column The column (1, 2 or 3) - * @return true|false Depending on success + * @param int $order The order within the column + * @param int $column The column (1, 2 or 3) + * + * @return bool Depending on success */ function save_widget_location(ElggObject $widget, $order, $column) { if ($widget instanceof ElggObject) { @@ -74,8 +79,8 @@ function save_widget_location(ElggObject $widget, $order, $column) { 'column' => $column, ); - if ($entities = get_entities_from_metadata_multi($params,'object','widget')) { - foreach($entities as $entity) { + if ($entities = get_entities_from_metadata_multi($params, 'object', 'widget')) { + foreach ($entities as $entity) { $entityorder = $entity->order; if ($entityorder < $order) { $ordertmp[$entityorder] = $entity; @@ -90,7 +95,7 @@ function save_widget_location(ElggObject $widget, $order, $column) { ksort($ordertmp); $orderticker = 10; - foreach($ordertmp as $orderval => $entity) { + foreach ($ordertmp as $orderval => $entity) { $entity->order = $orderticker; $orderticker += 10; } @@ -108,9 +113,10 @@ function save_widget_location(ElggObject $widget, $order, $column) { /** * Get widgets for a particular context and column, in order of display * - * @param int $user_guid The owner user GUID - * @param string $context The context (profile, dashboard etc) - * @param int $column The column (1 or 2) + * @param int $user_guid The owner user GUID + * @param string $context The context (profile, dashboard etc) + * @param int $column The column (1 or 2) + * * @return array|false An array of widget ElggObjects, or false */ function get_widgets($user_guid, $context, $column) { @@ -118,12 +124,14 @@ function get_widgets($user_guid, $context, $column) { 'column' => $column, 'context' => $context ); - $widgets = get_entities_from_private_setting_multi($params, "object", "widget", $user_guid, "", 10000); + $widgets = get_entities_from_private_setting_multi($params, "object", + "widget", $user_guid, "", 10000); + if ($widgets) { $widgetorder = array(); - foreach($widgets as $widget) { + foreach ($widgets as $widget) { $order = $widget->order; - while(isset($widgetorder[$order])) { + while (isset($widgetorder[$order])) { $order++; } $widgetorder[$order] = $widget; @@ -141,6 +149,7 @@ function get_widgets($user_guid, $context, $column) { * Displays a particular widget * * @param ElggObject $widget The widget to display + * * @return string The HTML for the widget, including JavaScript wrapper */ function display_widget(ElggObject $widget) { @@ -150,13 +159,14 @@ function display_widget(ElggObject $widget) { /** * Add a new widget instance * - * @param int $entity_guid GUID of entity that owns this widget - * @param string $handler The handler for this widget - * @param string $context The page context for this widget - * @param int $order The order to display this widget in - * @param int $column The column to display this widget in (1, 2 or 3) - * @param int $access_id If not specified, it is set to the default access level - * @return true|false Depending on success + * @param int $entity_guid GUID of entity that owns this widget + * @param string $handler The handler for this widget + * @param string $context The page context for this widget + * @param int $order The order to display this widget in + * @param int $column The column to display this widget in (1, 2 or 3) + * @param int $access_id If not specified, it is set to the default access level + * + * @return bool Depending on success */ function add_widget($entity_guid, $handler, $context, $order = 0, $column = 1, $access_id = null) { if (empty($entity_guid) || empty($context) || empty($handler) || !widget_type_exists($handler)) { @@ -192,15 +202,21 @@ function add_widget($entity_guid, $handler, $context, $order = 0, $column = 1, $ /** * Define a new widget type * - * @param string $handler The identifier for the widget handler - * @param string $name The name of the widget type + * @param string $handler The identifier for the widget handler + * @param string $name The name of the widget type * @param string $description A description for the widget type - * @param string $context A comma-separated list of contexts where this widget is allowed (default: 'all') - * @param true|false $multiple Whether or not multiple instances of this widget are allowed on a single dashboard (default: false) - * @param string $position A comma-separated list of positions on the page (side or main) where this widget is allowed (default: "side,main") - * @return true|false Depending on success + * @param string $context A comma-separated list of contexts where this + * widget is allowed (default: 'all') + * @param bool $multiple Whether or not multiple instances of this widget + * are allowed on a single dashboard (default: false) + * @param string $positions A comma-separated list of positions on the page + * (side or main) where this widget is allowed (default: "side,main") + * + * @return bool Depending on success */ -function add_widget_type($handler, $name, $description, $context = "all", $multiple = false, $positions = "side,main") { +function add_widget_type($handler, $name, $description, $context = "all", +$multiple = false, $positions = "side,main") { + if (!empty($handler) && !empty($name)) { global $CONFIG; @@ -215,9 +231,9 @@ function add_widget_type($handler, $name, $description, $context = "all", $multi $handlerobj = new stdClass; $handlerobj->name = $name; $handlerobj->description = $description; - $handlerobj->context = explode(",",$context); + $handlerobj->context = explode(",", $context); $handlerobj->multiple = $multiple; - $handlerobj->positions = explode(",",$positions); + $handlerobj->positions = explode(",", $positions); $CONFIG->widgets->handlers[$handler] = $handlerobj; @@ -231,6 +247,8 @@ function add_widget_type($handler, $name, $description, $context = "all", $multi * Remove a widget type * * @param string $handler The identifier for the widget handler + * + * @return void * @since 1.7.1 */ function remove_widget_type($handler) { @@ -253,7 +271,8 @@ function remove_widget_type($handler) { * Determines whether or not widgets with the specified handler have been defined * * @param string $handler The widget handler identifying string - * @return true|false Whether or not those widgets exist + * + * @return bool Whether or not those widgets exist */ function widget_type_exists($handler) { global $CONFIG; @@ -277,29 +296,32 @@ function get_widget_types() { global $CONFIG; if (!empty($CONFIG->widgets) - && !empty($CONFIG->widgets->handlers) - && is_array($CONFIG->widgets->handlers)) { + && !empty($CONFIG->widgets->handlers) + && is_array($CONFIG->widgets->handlers)) { - $context = get_context(); + $context = get_context(); - foreach($CONFIG->widgets->handlers as $key => $handler) { - if (!in_array('all',$handler->context) && - !in_array($context,$handler->context)) { - unset($CONFIG->widgets->handlers[$key]); - } + foreach ($CONFIG->widgets->handlers as $key => $handler) { + if (!in_array('all', $handler->context) && + !in_array($context, $handler->context)) { + unset($CONFIG->widgets->handlers[$key]); } - - return $CONFIG->widgets->handlers; } + return $CONFIG->widgets->handlers; + } + return array(); } /** - * Saves a widget's settings (by passing an array of (name => value) pairs to save_{$handler}_widget) + * Saves a widget's settings (by passing an array of + * (name => value) pairs to save_{$handler}_widget) * - * @param int $widget_guid The GUID of the widget we're saving to - * @param array $params An array of name => value parameters + * @param int $widget_guid The GUID of the widget we're saving to + * @param array $params An array of name => value parameters + * + * @return bool */ function save_widget_info($widget_guid, $params) { if ($widget = get_entity($widget_guid)) { @@ -320,10 +342,10 @@ function save_widget_info($widget_guid, $params) { // Save the params to the widget if (is_array($params) && sizeof($params) > 0) { - foreach($params as $name => $value) { + foreach ($params as $name => $value) { if (!empty($name) && !in_array($name, array( - 'guid','owner_guid','site_guid' + 'guid', 'owner_guid', 'site_guid' ))) { if (is_array($value)) { // @todo Handle arrays securely @@ -347,18 +369,29 @@ function save_widget_info($widget_guid, $params) { return false; } +/** + * Reorders the widgets from a widget panel + * + * @param string $panelstring1 String of guids of ElggWidget objects separated by :: + * @param string $panelstring2 String of guids of ElggWidget objects separated by :: + * @param string $panelstring3 String of guids of ElggWidget objects separated by :: + * @param string $context Profile or dashboard + * @param int $owner Owner guid + * + * @return void + */ function reorder_widgets_from_panel($panelstring1, $panelstring2, $panelstring3, $context, $owner) { $return = true; - $mainwidgets = explode('::',$panelstring1); - $sidewidgets = explode('::',$panelstring2); - $rightwidgets = explode('::',$panelstring3); + $mainwidgets = explode('::', $panelstring1); + $sidewidgets = explode('::', $panelstring2); + $rightwidgets = explode('::', $panelstring3); $handlers = array(); $guids = array(); if (is_array($mainwidgets) && sizeof($mainwidgets) > 0) { - foreach($mainwidgets as $widget) { + foreach ($mainwidgets as $widget) { $guid = (int) $widget; @@ -370,7 +403,7 @@ function reorder_widgets_from_panel($panelstring1, $panelstring2, $panelstring3, } } if (is_array($sidewidgets) && sizeof($sidewidgets) > 0) { - foreach($sidewidgets as $widget) { + foreach ($sidewidgets as $widget) { $guid = (int) $widget; @@ -383,7 +416,7 @@ function reorder_widgets_from_panel($panelstring1, $panelstring2, $panelstring3, } } if (is_array($rightwidgets) && sizeof($rightwidgets) > 0) { - foreach($rightwidgets as $widget) { + foreach ($rightwidgets as $widget) { $guid = (int) $widget; @@ -397,19 +430,21 @@ function reorder_widgets_from_panel($panelstring1, $panelstring2, $panelstring3, } // Reorder existing widgets or delete ones that have vanished - foreach (array(1,2,3) as $column) { - if ($dbwidgets = get_widgets($owner,$context,$column)) { + foreach (array(1, 2, 3) as $column) { + if ($dbwidgets = get_widgets($owner, $context, $column)) { + + foreach ($dbwidgets as $dbwidget) { + if (in_array($dbwidget->getGUID(), $guids[1]) + || in_array($dbwidget->getGUID(), $guids[2]) || in_array($dbwidget->getGUID(), $guids[3])) { - foreach($dbwidgets as $dbwidget) { - if (in_array($dbwidget->getGUID(),$guids[1]) || in_array($dbwidget->getGUID(),$guids[2]) || in_array($dbwidget->getGUID(),$guids[3])) { - if (in_array($dbwidget->getGUID(),$guids[1])) { - $pos = array_search($dbwidget->getGUID(),$guids[1]); + if (in_array($dbwidget->getGUID(), $guids[1])) { + $pos = array_search($dbwidget->getGUID(), $guids[1]); $col = 1; - } else if (in_array($dbwidget->getGUID(),$guids[2])) { - $pos = array_search($dbwidget->getGUID(),$guids[2]); + } else if (in_array($dbwidget->getGUID(), $guids[2])) { + $pos = array_search($dbwidget->getGUID(), $guids[2]); $col = 2; } else { - $pos = array_search($dbwidget->getGUID(),$guids[3]); + $pos = array_search($dbwidget->getGUID(), $guids[3]); $col = 3; } $pos = ($pos + 1) * 10; @@ -429,11 +464,11 @@ function reorder_widgets_from_panel($panelstring1, $panelstring2, $panelstring3, } // Add new ones if (sizeof($guids[$column]) > 0) { - foreach($guids[$column] as $key => $guid) { + foreach ($guids[$column] as $key => $guid) { if ($guid == 0) { $pos = ($key + 1) * 10; $handler = $handlers[$column][$key]; - if (!add_widget($owner,$handler,$context,$pos,$column)) { + if (!add_widget($owner, $handler, $context, $pos, $column)) { $return = false; } } @@ -445,8 +480,9 @@ function reorder_widgets_from_panel($panelstring1, $panelstring2, $panelstring3, } /** - * Run some things once. + * Regsiter entity of object, widget as ElggWidget objects * + * @return void */ function widget_run_once() { // Register a class @@ -456,6 +492,7 @@ function widget_run_once() { /** * Function to initialise widgets functionality on Elgg init * + * @return void */ function widgets_init() { register_action('widgets/reorder'); @@ -467,7 +504,7 @@ function widgets_init() { } // Register event -register_elgg_event_handler('init','system','widgets_init'); +register_elgg_event_handler('init', 'system', 'widgets_init'); // Use widgets on the dashboard use_widgets('dashboard');
\ No newline at end of file diff --git a/engine/lib/xml-rpc.php b/engine/lib/xml-rpc.php index cf08dd8e4..70eb627d8 100644 --- a/engine/lib/xml-rpc.php +++ b/engine/lib/xml-rpc.php @@ -1,174 +1,197 @@ <?php - /** - * Elgg XML-RPC library. - * Contains functions and classes to handle XML-RPC services, currently only server only. - * - * @package Elgg - * @subpackage Core - */ - - // Helper functions /////////////////////////////////////////////////////////////////////// - - /** - * parse XMLRPCCall parameters - * - * Convert an XMLRPCCall result array into native data types - * - * @param array $parameters - * @return array - */ - function xmlrpc_parse_params($parameters) - { - $result = array(); - - foreach ($parameters as $parameter) - { - $result[] = xmlrpc_scalar_value($parameter); - } - - return $result; +/** + * Elgg XML-RPC library. + * Contains functions and classes to handle XML-RPC services, currently only server only. + * + * @package Elgg.Core + * @subpackage XMLRPC + */ + +/** + * parse XMLRPCCall parameters + * + * Convert an XMLRPCCall result array into native data types + * + * @param array $parameters An array of params + * + * @return array + */ +function xmlrpc_parse_params($parameters) { + $result = array(); + + foreach ($parameters as $parameter) { + $result[] = xmlrpc_scalar_value($parameter); } - /** - * Extract the scalar value of an XMLObject type result array - * - * @param XMLObject $object - * @return mixed - */ - function xmlrpc_scalar_value($object) - { - if ($object->name == 'param') - { - $object = $object->children[0]->children[0]; - } - - switch ($object->name) - { - case 'string': - return $object->content; - case 'array': - foreach ($object->children[0]->children as $child) - { - $value[] = xmlrpc_scalar_value($child); - } - return $value; - case 'struct': - foreach ($object->children as $child) - { - if (isset($child->children[1]->children[0])) - $value[$child->children[0]->content] = xmlrpc_scalar_value($child->children[1]->children[0]); - else - $value[$child->children[0]->content] = $child->children[1]->content; - } - return $value; - case 'boolean': - return (boolean) $object->content; - case 'i4': - case 'int': - return (int) $object->content; - case 'double': - return (double) $object->content; - case 'dateTime.iso8601': - return (int) strtotime($object->content); - case 'base64': - return base64_decode($object->content); - case 'value': - return xmlrpc_scalar_value($object->children[0]); - default: - // @todo unsupported, throw an error - return false; - } + return $result; +} + +/** + * Extract the scalar value of an XMLObject type result array + * + * @param XMLObject $object And object + * + * @return mixed + */ +function xmlrpc_scalar_value($object) { + if ($object->name == 'param') { + $object = $object->children[0]->children[0]; } - - // Functions for adding handlers ////////////////////////////////////////////////////////// - - /** XML-RPC Handlers */ - $XML_RPC_HANDLERS = array(); - - /** - * Register a method handler for a given XML-RPC method. - * - * @param string $method Method parameter. - * @param string $handler The handler function. This function accepts once XMLRPCCall object and must return a XMLRPCResponse object. - * @return bool - */ - function register_xmlrpc_handler($method, $handler) - { - global $XML_RPC_HANDLERS; - - $XML_RPC_HANDLERS[$method] = $handler; + + switch ($object->name) { + case 'string': + return $object->content; + + case 'array': + foreach ($object->children[0]->children as $child) { + $value[] = xmlrpc_scalar_value($child); + } + return $value; + + case 'struct': + foreach ($object->children as $child) { + if (isset($child->children[1]->children[0])) { + $value[$child->children[0]->content] = xmlrpc_scalar_value($child->children[1]->children[0]); + } else { + $value[$child->children[0]->content] = $child->children[1]->content; + } + } + return $value; + + case 'boolean': + return (boolean) $object->content; + + case 'i4': + case 'int': + return (int) $object->content; + + case 'double': + return (double) $object->content; + + case 'dateTime.iso8601': + return (int) strtotime($object->content); + + case 'base64': + return base64_decode($object->content); + + case 'value': + return xmlrpc_scalar_value($object->children[0]); + + default: + // @todo unsupported, throw an error + return false; } - - /** - * Trigger a method call and pass the relevant parameters to the funciton. - * - * @param XMLRPCCall $parameters The call and parameters. - * @return XMLRPCCall - */ - function trigger_xmlrpc_handler(XMLRPCCall $parameters) - { - global $XML_RPC_HANDLERS; - - // Go through and see if we have a handler - if (isset($XML_RPC_HANDLERS[$parameters->getMethodName()])) - { - $handler = $XML_RPC_HANDLERS[$parameters->getMethodName()]; - $result = $handler($parameters); - - if (!($result instanceof XMLRPCResponse)) - throw new InvalidParameterException(sprintf(elgg_echo('InvalidParameterException:UnexpectedReturnFormat'), $parameters->getMethodName())); - - // Result in right format, return it. - return $result; +} + +// Functions for adding handlers ////////////////////////////////////////////////////////// + +/** XML-RPC Handlers */ +$XML_RPC_HANDLERS = array(); + +/** + * Register a method handler for a given XML-RPC method. + * + * @param string $method Method parameter. + * @param string $handler The handler function. This function accepts + * one XMLRPCCall object and must return a XMLRPCResponse object. + * + * @return bool + */ +function register_xmlrpc_handler($method, $handler) { + global $XML_RPC_HANDLERS; + + $XML_RPC_HANDLERS[$method] = $handler; +} + +/** + * Trigger a method call and pass the relevant parameters to the funciton. + * + * @param XMLRPCCall $parameters The call and parameters. + * + * @return XMLRPCCall + */ +function trigger_xmlrpc_handler(XMLRPCCall $parameters) { + global $XML_RPC_HANDLERS; + + // Go through and see if we have a handler + if (isset($XML_RPC_HANDLERS[$parameters->getMethodName()])) { + $handler = $XML_RPC_HANDLERS[$parameters->getMethodName()]; + $result = $handler($parameters); + + if (!($result instanceof XMLRPCResponse)) { + $msg = sprintf(elgg_echo('InvalidParameterException:UnexpectedReturnFormat'), + $parameters->getMethodName()); + throw new InvalidParameterException($msg); } - - // if no handler then throw exception - throw new NotImplementedException(sprintf(elgg_echo('NotImplementedException:XMLRPCMethodNotImplemented'), $parameters->getMethodName())); + + // Result in right format, return it. + return $result; } - - // Error handler functions //////////////////////////////////////////////////////////////// - - /** - * PHP Error handler function. - * This function acts as a wrapper to catch and report PHP error messages. - * - * @see http://uk3.php.net/set-error-handler - * @param unknown_type $errno - * @param unknown_type $errmsg - * @param unknown_type $filename - * @param unknown_type $linenum - * @param unknown_type $vars - */ - function __php_xmlrpc_error_handler($errno, $errmsg, $filename, $linenum, $vars) - { - $error = date("Y-m-d H:i:s (T)") . ": \"" . $errmsg . "\" in file " . $filename . " (line " . $linenum . ")"; - - switch ($errno) { - case E_USER_ERROR: - error_log("ERROR: " . $error); - - // Since this is a fatal error, we want to stop any further execution but do so gracefully. - throw new Exception("ERROR: " . $error); - break; - - case E_WARNING : - case E_USER_WARNING : - error_log("WARNING: " . $error); - break; - - default: - error_log("DEBUG: " . $error); - } + + // if no handler then throw exception + $msg = sprintf(elgg_echo('NotImplementedException:XMLRPCMethodNotImplemented'), + $parameters->getMethodName()); + throw new NotImplementedException($msg); +} + +/** + * PHP Error handler function. + * This function acts as a wrapper to catch and report PHP error messages. + * + * @see http://uk3.php.net/set-error-handler + * + * @param int $errno Error number + * @param string $errmsg Human readable message + * @param string $filename Filename + * @param int $linenum Line number + * @param array $vars Vars + * + * @return void + */ +function _php_xmlrpc_error_handler($errno, $errmsg, $filename, $linenum, $vars) { + $error = date("Y-m-d H:i:s (T)") . ": \"" . $errmsg . "\" in file " + . $filename . " (line " . $linenum . ")"; + + switch ($errno) { + case E_USER_ERROR: + error_log("ERROR: " . $error); + + // Since this is a fatal error, we want to stop any further execution but do so gracefully. + throw new Exception("ERROR: " . $error); + break; + + case E_WARNING : + case E_USER_WARNING : + error_log("WARNING: " . $error); + break; + + default: + error_log("DEBUG: " . $error); } - - /** - * PHP Exception handler for XMLRPC. - * @param Exception $exception - */ - function __php_xmlrpc_exception_handler($exception) { - - error_log("*** FATAL EXCEPTION (XML-RPC) *** : " . $exception); - - page_draw($exception->getMessage(), elgg_view("xml-rpc/output", array('result' => new XMLRPCErrorResponse($exception->getMessage(), $exception->getCode()==0 ? -32400 : $exception->getCode())))); +} + +/** + * PHP Exception handler for XMLRPC. + * + * @param Exception $exception The exception + * + * @return void + */ +function _php_xmlrpc_exception_handler($exception) { + + error_log("*** FATAL EXCEPTION (XML-RPC) *** : " . $exception); + + $code = $exception->getCode(); + + if ($code == 0) { + $code = -32400; } -?> + + $result = new XMLRPCErrorResponse($exception->getMessage(), $code); + + $vars = array('result' => $result); + + $content = elgg_view("xml-rpc/output", $vars); + + page_draw($exception->getMessage(), $content); +} diff --git a/engine/lib/xml.php b/engine/lib/xml.php index bc52815f2..0d0d83da0 100644 --- a/engine/lib/xml.php +++ b/engine/lib/xml.php @@ -1,142 +1,147 @@ <?php - /** - * Elgg XML library. - * Contains functions for generating and parsing XML. - * - * @package Elgg - * @subpackage Core - */ - - /** - * This function serialises an object recursively into an XML representation. - * The function attempts to call $data->export() which expects a stdClass in return, otherwise it will attempt to - * get the object variables using get_object_vars (which will only return public variables!) - * @param $data object The object to serialise. - * @param $n int Level, only used for recursion. - * @return string The serialised XML output. - */ - function serialise_object_to_xml($data, $name = "", $n = 0) - { - $classname = ($name=="" ? get_class($data) : $name); - - $vars = method_exists($data, "export") ? get_object_vars($data->export()) : get_object_vars($data); - - $output = ""; - - if (($n==0) || ( is_object($data) && !($data instanceof stdClass))) { - $output = "<$classname>"; - } - - foreach ($vars as $key => $value) { - $output .= "<$key type=\"".gettype($value)."\">"; - - if (is_object($value)) { - $output .= serialise_object_to_xml($value, $key, $n+1); - } else if (is_array($value)) { - $output .= serialise_array_to_xml($value, $n+1); - } else if (gettype($value) == "boolean") { - $output .= $value ? "true" : "false"; - } else { - $output .= htmlspecialchars($value, ENT_NOQUOTES, 'UTF-8'); - } - - $output .= "</$key>\n"; - } - - if (($n==0) || ( is_object($data) && !($data instanceof stdClass))) { - $output .= "</$classname>\n"; - } - - return $output; +/** + * Elgg XML library. + * Contains functions for generating and parsing XML. + * + * @package Elgg.Core + * @subpackage XML + */ + +/** + * This function serialises an object recursively into an XML representation. + * + * The function attempts to call $data->export() which expects a stdClass in return, + * otherwise it will attempt to get the object variables using get_object_vars (which + * will only return public variables!) + * + * @param mixed $data The object to serialise. + * @param string $name The name? + * @param int $n Level, only used for recursion. + * + * @return string The serialised XML output. + */ +function serialise_object_to_xml($data, $name = "", $n = 0) { + $classname = ($name == "" ? get_class($data) : $name); + + $vars = method_exists($data, "export") ? get_object_vars($data->export()) : get_object_vars($data); + + $output = ""; + + if (($n == 0) || ( is_object($data) && !($data instanceof stdClass))) { + $output = "<$classname>"; } - /** - * Serialise an array. - * - * @param array $data - * @param int $n Used for recursion - * @return string - */ - function serialise_array_to_xml(array $data, $n = 0) - { - $output = ""; - - if ($n==0) { - $output = "<array>\n"; + foreach ($vars as $key => $value) { + $output .= "<$key type=\"" . gettype($value) . "\">"; + + if (is_object($value)) { + $output .= serialise_object_to_xml($value, $key, $n + 1); + } else if (is_array($value)) { + $output .= serialise_array_to_xml($value, $n + 1); + } else if (gettype($value) == "boolean") { + $output .= $value ? "true" : "false"; + } else { + $output .= htmlspecialchars($value, ENT_NOQUOTES, 'UTF-8'); } - - foreach ($data as $key => $value) { - $item = "array_item"; - - if (is_numeric($key)) { - $output .= "<$item name=\"$key\" type=\"".gettype($value)."\">"; - } else { - $item = $key; - $output .= "<$item type=\"".gettype($value)."\">"; - } - - if (is_object($value)) { - $output .= serialise_object_to_xml($value, "", $n+1); - } else if (is_array($value)) { - $output .= serialise_array_to_xml($value, $n+1); - } else if (gettype($value) == "boolean") { - $output .= $value ? "true" : "false"; - } else { - $output .= htmlspecialchars($value, ENT_NOQUOTES, 'UTF-8'); - } - - $output .= "</$item>\n"; + + $output .= "</$key>\n"; + } + + if (($n == 0) || (is_object($data) && !($data instanceof stdClass))) { + $output .= "</$classname>\n"; + } + + return $output; +} + +/** + * Serialise an array. + * + * @param array $data The data to serialize + * @param int $n Used for recursion + * + * @return string + */ +function serialise_array_to_xml(array $data, $n = 0) { + $output = ""; + + if ($n == 0) { + $output = "<array>\n"; + } + + foreach ($data as $key => $value) { + $item = "array_item"; + + if (is_numeric($key)) { + $output .= "<$item name=\"$key\" type=\"" . gettype($value) . "\">"; + } else { + $item = $key; + $output .= "<$item type=\"" . gettype($value) . "\">"; } - - if ($n==0) { - $output .= "</array>\n"; + + if (is_object($value)) { + $output .= serialise_object_to_xml($value, "", $n + 1); + } else if (is_array($value)) { + $output .= serialise_array_to_xml($value, $n + 1); + } else if (gettype($value) == "boolean") { + $output .= $value ? "true" : "false"; + } else { + $output .= htmlspecialchars($value, ENT_NOQUOTES, 'UTF-8'); } - - return $output; + + $output .= "</$item>\n"; } - - /** - * Parse an XML file into an object. - * Based on code from http://de.php.net/manual/en/function.xml-parse-into-struct.php by - * efredricksen at gmail dot com - * - * @param string $xml The XML. - */ - function xml_to_object($xml) - { - $parser = xml_parser_create(); - - // Parse $xml into a structure - xml_parser_set_option($parser, XML_OPTION_SKIP_WHITE, 1); - xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, 0); - xml_parse_into_struct($parser, $xml, $tags); - - xml_parser_free($parser); - - $elements = array(); - $stack = array(); - - foreach ($tags as $tag) { - $index = count($elements); - - if ($tag['type'] == "complete" || $tag['type'] == "open") { - $elements[$index] = new XmlElement; - $elements[$index]->name = $tag['tag']; - $elements[$index]->attributes = $tag['attributes']; - $elements[$index]->content = $tag['value']; - - if ($tag['type'] == "open") { - $elements[$index]->children = array(); - $stack[count($stack)] = &$elements; - $elements = &$elements[$index]->children; - } - } - - if ($tag['type'] == "close") { - $elements = &$stack[count($stack) - 1]; - unset($stack[count($stack) - 1]); + + if ($n == 0) { + $output .= "</array>\n"; + } + + return $output; +} + +/** + * Parse an XML file into an object. + * Based on code from http://de.php.net/manual/en/function.xml-parse-into-struct.php by + * efredricksen at gmail dot com + * + * @param string $xml The XML + * + * @return object + */ +function xml_to_object($xml) { + $parser = xml_parser_create(); + + // Parse $xml into a structure + xml_parser_set_option($parser, XML_OPTION_SKIP_WHITE, 1); + xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, 0); + xml_parse_into_struct($parser, $xml, $tags); + + xml_parser_free($parser); + + $elements = array(); + $stack = array(); + + foreach ($tags as $tag) { + $index = count($elements); + + if ($tag['type'] == "complete" || $tag['type'] == "open") { + $elements[$index] = new XmlElement; + $elements[$index]->name = $tag['tag']; + $elements[$index]->attributes = $tag['attributes']; + $elements[$index]->content = $tag['value']; + + if ($tag['type'] == "open") { + $elements[$index]->children = array(); + $stack[count($stack)] = &$elements; + $elements = &$elements[$index]->children; } } - - return $elements[0]; + + if ($tag['type'] == "close") { + $elements = &$stack[count($stack) - 1]; + unset($stack[count($stack) - 1]); + } } + + return $elements[0]; +} diff --git a/engine/settings.example.php b/engine/settings.example.php index c503f0162..f2772b8e6 100644 --- a/engine/settings.example.php +++ b/engine/settings.example.php @@ -80,7 +80,8 @@ $CONFIG->dbprefix = '{{dbprefix}}'; * 1) One or more memcache servers (http://www.danga.com/memcached/) * 2) PHP memcache wrapper (http://uk.php.net/manual/en/memcache.setup.php) * - * Note: Multiple server support is only available on server 1.2.1 or higher with PECL library > 2.0.0 + * Note: Multiple server support is only available on server 1.2.1 + * or higher with PECL library > 2.0.0 */ //$CONFIG->memcache = true; // diff --git a/engine/start.php b/engine/start.php index 35c382a5f..5d08c77d5 100644 --- a/engine/start.php +++ b/engine/start.php @@ -74,8 +74,8 @@ foreach ($required_files as $file) { } // Register the error handler -set_error_handler('__elgg_php_error_handler'); -set_exception_handler('__elgg_php_exception_handler'); +set_error_handler('_elgg_php_error_handler'); +set_exception_handler('_elgg_php_exception_handler'); /** * Load the system settings @@ -103,7 +103,7 @@ $lib_files = array( 'users.php', 'version.php', 'widgets.php', 'xml.php', 'xml-rpc.php' ); -foreach($lib_files as $file) { +foreach ($lib_files as $file) { $file = $lib_dir . $file; elgg_log("Loading $file..."); if (!include_once($file)) { @@ -132,7 +132,7 @@ trigger_elgg_event('init', 'system'); // Regenerate the simple cache if expired. // Don't do it on upgrade because upgrade does it itself. // @todo - move into function and perhaps run off init system event -if (!defined('upgrading')) { +if (!defined('UPGRADING')) { $view = get_input('view', 'default'); $lastupdate = datalist_get("simplecache_lastupdate_$view"); $lastcached = datalist_get("simplecache_lastcached_$view"); |