From 7ddd9521b3f3a397da3b0a6b56238d31414eb4be Mon Sep 17 00:00:00 2001 From: brettp Date: Thu, 28 Oct 2010 19:17:36 +0000 Subject: [PATCH] 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 --- CHANGES.txt | 31 +- _css/css.php | 2 +- _css/js.php | 2 +- actions/admin/menu_items.php | 2 +- .../admin/plugins/simple_update_states.php | 3 +- actions/comments/add.php | 16 +- actions/email/save.php | 2 +- actions/friends/add.php | 12 +- actions/friends/addcollection.php | 13 +- actions/friends/deletecollection.php | 7 +- actions/friends/editcollection.php | 5 +- actions/friends/remove.php | 6 +- actions/likes/add.php | 8 +- actions/likes/delete.php | 3 +- actions/login.php | 28 +- actions/register.php | 2 +- actions/user/language.php | 2 +- actions/user/password.php | 4 +- actions/user/spotlight.php | 7 +- actions/useradd.php | 10 +- actions/usersettings/save.php | 6 +- actions/widgets/add.php | 6 +- actions/widgets/reorder.php | 4 +- actions/widgets/save.php | 8 +- engine/classes/APIException.php | 3 +- engine/classes/CallException.php | 2 +- engine/classes/ClassException.php | 2 +- engine/classes/ClassNotFoundException.php | 2 +- engine/classes/ConfigurationException.php | 2 +- engine/classes/CronException.php | 2 +- engine/classes/DataFormatException.php | 2 +- engine/classes/DatabaseException.php | 2 +- engine/classes/ElggAccess.php | 38 +- engine/classes/ElggAnnotation.php | 29 +- engine/classes/ElggCache.php | 118 ++- engine/classes/ElggDiskFilestore.php | 158 ++-- engine/classes/ElggEntity.php | 353 ++++++--- engine/classes/ElggExtender.php | 117 ++- engine/classes/ElggFile.php | 125 +++- engine/classes/ElggFileCache.php | 110 ++- engine/classes/ElggFilestore.php | 53 +- engine/classes/ElggGroup.php | 189 +++-- engine/classes/ElggHMACCache.php | 30 +- engine/classes/ElggMemcache.php | 73 +- engine/classes/ElggMetadata.php | 31 +- engine/classes/ElggObject.php | 82 ++- engine/classes/ElggPlugin.php | 35 +- engine/classes/ElggRelationship.php | 117 ++- engine/classes/ElggSession.php | 84 ++- engine/classes/ElggSharedMemoryCache.php | 10 +- engine/classes/ElggSite.php | 115 +-- engine/classes/ElggStaticVariableCache.php | 43 +- engine/classes/ElggUser.php | 143 ++-- engine/classes/ElggWidget.php | 37 +- engine/classes/ErrorResult.php | 21 +- engine/classes/ExportException.php | 4 +- engine/classes/Exportable.php | 7 +- engine/classes/Friendable.php | 39 +- engine/classes/GenericResult.php | 37 +- engine/classes/IOException.php | 4 +- engine/classes/ImportException.php | 4 +- engine/classes/Importable.php | 6 +- engine/classes/InstallationException.php | 4 +- engine/classes/InvalidClassException.php | 4 +- engine/classes/InvalidParameterException.php | 4 +- engine/classes/Locatable.php | 19 +- engine/classes/Loggable.php | 22 +- engine/classes/NotImplementedException.php | 8 +- engine/classes/Notable.php | 25 +- engine/classes/NotificationException.php | 3 + engine/classes/ODD.php | 46 +- engine/classes/ODDDocument.php | 76 +- engine/classes/ODDEntity.php | 63 +- engine/classes/PluginException.php | 7 +- engine/classes/RegistrationException.php | 2 +- engine/classes/SecurityException.php | 7 +- engine/classes/SuccessResult.php | 19 +- engine/classes/XMLRPCArrayParameter.php | 47 +- engine/classes/XMLRPCBase64Parameter.php | 23 +- engine/classes/XMLRPCBoolParameter.php | 31 +- engine/classes/XMLRPCCall.php | 53 +- engine/classes/XMLRPCDateParameter.php | 29 +- engine/classes/XMLRPCDoubleParameter.php | 31 +- engine/classes/XMLRPCErrorResponse.php | 21 +- engine/classes/XMLRPCIntParameter.php | 31 +- engine/classes/XMLRPCParameter.php | 13 +- engine/classes/XMLRPCResponse.php | 67 +- engine/classes/XMLRPCStringParameter.php | 31 +- engine/classes/XMLRPCStructParameter.php | 51 +- engine/classes/XMLRPCSuccessResponse.php | 18 +- engine/classes/XmlElement.php | 13 +- engine/handlers/xml-rpc_handler.php | 4 +- engine/lib/access.php | 231 +++--- engine/lib/actions.php | 43 +- engine/lib/admin.php | 52 +- engine/lib/annotations.php | 515 ++++++++----- engine/lib/api.php | 357 +++++---- engine/lib/calendar.php | 288 +++++--- engine/lib/configuration.php | 34 +- engine/lib/cron.php | 23 +- engine/lib/database.php | 108 ++- engine/lib/elgglib.php | 552 +++++++++----- engine/lib/entities.php | 682 +++++++++++------- engine/lib/export.php | 61 +- engine/lib/extender.php | 59 +- engine/lib/filestore.php | 259 +++++-- engine/lib/group.php | 280 ++++--- engine/lib/input.php | 73 +- engine/lib/install.php | 10 +- engine/lib/languages.php | 46 +- engine/lib/location.php | 127 ++-- engine/lib/memcache.php | 6 +- engine/lib/metadata.php | 467 ++++++++---- engine/lib/metastrings.php | 35 +- engine/lib/notification.php | 161 +++-- engine/lib/objects.php | 90 ++- engine/lib/opendd.php | 23 +- engine/lib/output.php | 51 +- engine/lib/pagehandler.php | 25 +- engine/lib/pageowner.php | 51 +- engine/lib/pam.php | 48 +- engine/lib/plugins.php | 181 +++-- engine/lib/relationships.php | 388 ++++++---- engine/lib/river.php | 267 ++++--- engine/lib/sessions.php | 153 ++-- engine/lib/sites.php | 204 ++++-- engine/lib/statistics.php | 37 +- engine/lib/system_log.php | 88 ++- engine/lib/tags.php | 114 +-- engine/lib/upgrades/2008100701.php | 7 +- engine/lib/upgrades/2008101303.php | 16 +- engine/lib/upgrades/2009022701.php | 5 +- engine/lib/upgrades/2009041701.php | 7 +- engine/lib/upgrades/2009070101.php | 7 +- engine/lib/upgrades/2009102801.php | 165 +++-- engine/lib/upgrades/2010033101.php | 12 +- engine/lib/upgrades/2010060401.php | 14 +- engine/lib/upgrades/2010061501.php | 38 +- engine/lib/upgrades/2010062301.php | 3 +- engine/lib/upgrades/2010071001.php | 11 +- engine/lib/upgrades/2010071002.php | 5 +- engine/lib/users.php | 551 +++++++++----- engine/lib/usersettings.php | 56 +- engine/lib/version.php | 21 +- engine/lib/views.php | 240 +++--- engine/lib/widgets.php | 171 +++-- engine/lib/xml-rpc.php | 353 ++++----- engine/lib/xml.php | 269 +++---- engine/settings.example.php | 3 +- engine/start.php | 8 +- index.php | 21 +- install.php | 2 +- install/ElggInstaller.php | 173 +++-- install/ElggRewriteTester.php | 16 +- .../default/profile/profile_ownerblock.php | 6 +- pages/account/forgotten_password.php | 3 +- pages/account/register.php | 8 +- pages/dashboard/index.php | 2 +- pages/dashboard/latest.php | 5 +- pages/entities/index.php | 2 +- pages/friends/add.php | 2 +- pages/friends/edit.php | 3 +- pages/friends/index.php | 4 +- pages/friends/of.php | 4 +- pages/friends/pickercallback.php | 26 +- pages/settings/plugins.php | 3 +- services/api/rest_api.php | 10 +- services/export/handler.php | 34 +- simplecache/view.php | 17 +- upgrade.php | 10 +- 170 files changed, 7747 insertions(+), 3945 deletions(-) diff --git a/CHANGES.txt b/CHANGES.txt index b24013d4572..5709872c770 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -8,8 +8,35 @@ Version 1.8.0 (Jackie) Generic API changes: * Added elgg_instanceof(). * Added remove_subtype() and update_subtype(). - * Added elgg_format_url() - + * Added elgg_format_url(). + * ElggDiskFilestore supports non-user owners. + + Deprecated APIs: + * ElggAccess::get_ignore_access() by ElggAccess::getIgnoreAccess(). + * ElggAccess::set_ignore_access() by ElggAccess::setIgnoreAccess(). + * ElggCache::set_variable() by ElggCache::setVariable(). + * ElggCache::get_variable() by ElggCache::getVariable(). + * ElggDiskFilestore::make_directory_root() by ElggDiskFilestore::makeDirectoryRoot(). + * ElggDiskFilestore::make_file_matrix() and ElggDiskFilestore::user_file_matrix() by + ElggDiskFilestore::makeFileMatrix(). + * ElggDiskFilestore::mb_string_split() removed. + * ElggEntity::initialise_attriutes() by ElggEntity::initializeAttributes(). Same for + all sub classes of ElggEntity. + * ElggFileCache::create_file() by ::createFile(). + * ElggFileCache::sanitise_filename() by ::sanitizeFilename(). + * ElggMemcache::make_memcache_key() by ::_makeMemcacheKey(). + * ElggGroup::initialise_attributes() by ::initializeAttributes(). + * ElggPlugin::initialise_attributes() by ::initializeAttributes(). + * XMLRPCCall::parse() by XMLRPCCALL::_parse(). + * __get_annotations_calculate_x() by get_annotations_calculate_x(). + * __get_entities_from_annotations_calculate_x() by get_entities_from_annotations_calculate_x(). + * __php_api_error_handler() by _php_api_error_handler(). + * __php_api_exception_handler() by _php_api_exception_handler(). + * __elgg_php_error_handler() by _elgg_php_error_handler(). + * __elgg_php_exception_handler() by _elgg_php_exception_handler(). + * __process_element() by _process_element(). + * All __elgg_session_*() by _elgg_session_*(). + UI/UX API changes: * Added elgg_push_breadcrumb(), elgg_pop_breadcrumb(), and elgg_get_breadcrumbs(). * Added navigation/breadcrumbs. diff --git a/_css/css.php b/_css/css.php index 7fd12ec1389..4a5152afb8a 100644 --- a/_css/css.php +++ b/_css/css.php @@ -30,7 +30,7 @@ $viewinput['viewtype'] = $_GET['viewtype']; header("Content-type: text/css", true); -header('Expires: ' . date('r',time() + 86400000), true); +header('Expires: ' . date('r', time() + 86400000), true); header("Pragma: public", true); header("Cache-Control: public", true); diff --git a/_css/js.php b/_css/js.php index 4110df952d6..41b7901f994 100644 --- a/_css/js.php +++ b/_css/js.php @@ -33,7 +33,7 @@ $viewinput['viewtype'] = $_GET['viewtype']; header('Content-type: text/javascript'); -header('Expires: ' . date('r',time() + 864000000)); +header('Expires: ' . date('r', time() + 864000000)); header("Pragma: public"); header("Cache-Control: public"); diff --git a/actions/admin/menu_items.php b/actions/admin/menu_items.php index 7b27af3deaf..8b01ae8fe92 100644 --- a/actions/admin/menu_items.php +++ b/actions/admin/menu_items.php @@ -29,7 +29,7 @@ // save the custom items $custom_count = count($custom_item_names); $custom_items = array(); -for ($i=0; $i<$custom_count; $i++) { +for ($i = 0; $i < $custom_count; $i++) { if (isset($custom_item_names[$i]) && isset($custom_item_names[$i])) { $name = $custom_item_names[$i]; $url = $custom_item_urls[$i]; diff --git a/actions/admin/plugins/simple_update_states.php b/actions/admin/plugins/simple_update_states.php index d9d8fd3e8f6..a81cb6a7acd 100644 --- a/actions/admin/plugins/simple_update_states.php +++ b/actions/admin/plugins/simple_update_states.php @@ -23,7 +23,8 @@ foreach ($installed_plugins as $plugin => $info) { // this is only for simple plugins. - if (!isset($info['manifest']['admin_interface']) || $info['manifest']['admin_interface'] != 'simple') { + $interface_type = elgg_get_array_value('admin_interface', $info['manifest'], NULL); + if (!$interface_type || $interface_type != 'simple') { continue; } diff --git a/actions/comments/add.php b/actions/comments/add.php index 84467168a18..2e28e783904 100644 --- a/actions/comments/add.php +++ b/actions/comments/add.php @@ -2,7 +2,8 @@ /** * Elgg add comment action * - * @package Elgg + * @package Elgg.Core + * @subpackage Comments */ // Make sure we're logged in; forward to the front page if not @@ -27,11 +28,11 @@ $user = get_loggedin_user(); -$annotation = create_annotation($entity->guid, +$annotation = create_annotation($entity->guid, 'generic_comment', - $comment_text, - "", - $user->guid, + $comment_text, + "", + $user->guid, $entity->access_id); // tell user annotation posted @@ -42,7 +43,7 @@ // notify if poster wasn't owner if ($entity->owner_guid != $user->guid) { - + notify_user($entity->owner_guid, $user->guid, elgg_echo('generic_comment:email:subject'), @@ -59,8 +60,9 @@ } system_message(elgg_echo("generic_comment:posted")); + //add to river -add_to_river('annotation/annotate','comment',$user->guid,$entity->guid, "", 0, $annotation); +add_to_river('annotation/annotate', 'comment', $user->guid, $entity->guid, "", 0, $annotation); // Forward to the page the action occurred on forward($_SERVER['HTTP_REFERER']); diff --git a/actions/email/save.php b/actions/email/save.php index 885bf2b04c8..c849699452e 100644 --- a/actions/email/save.php +++ b/actions/email/save.php @@ -23,7 +23,7 @@ } if ($user) { - if (strcmp($email, $user->email)!=0) { + if (strcmp($email, $user->email) != 0) { if (!get_user_by_email($email)) { if ($user->email != $email) { diff --git a/actions/friends/add.php b/actions/friends/add.php index cb527f82bed..d26539a54be 100644 --- a/actions/friends/add.php +++ b/actions/friends/add.php @@ -2,8 +2,8 @@ /** * Elgg add friend action * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage Friends.Management */ // Ensure we are logged in @@ -21,13 +21,13 @@ $errors = true; } } catch (Exception $e) { - register_error(sprintf(elgg_echo("friends:add:failure"),$friend->name)); + register_error(sprintf(elgg_echo("friends:add:failure"), $friend->name)); $errors = true; } -if (!$errors){ +if (!$errors) { // add to river - add_to_river('friends/river/create','friend',get_loggedin_userid(),$friend_guid); - system_message(sprintf(elgg_echo("friends:add:successful"),$friend->name)); + add_to_river('friends/river/create', 'friend', get_loggedin_userid(), $friend_guid); + system_message(sprintf(elgg_echo("friends:add:successful"), $friend->name)); } // Forward back to the page you friended the user on diff --git a/actions/friends/addcollection.php b/actions/friends/addcollection.php index e81fa34af9e..8fdb2be87d6 100644 --- a/actions/friends/addcollection.php +++ b/actions/friends/addcollection.php @@ -1,12 +1,9 @@ removeFriend($friend_guid); - } else{ + } else { register_error(sprintf(elgg_echo("friends:remove:failure"), $friend->name)); $errors = true; } diff --git a/actions/likes/add.php b/actions/likes/add.php index 0cec18dc534..b4b4a84629a 100644 --- a/actions/likes/add.php +++ b/actions/likes/add.php @@ -2,14 +2,15 @@ /** * Elgg add like action * - * @package Elgg + * @package Elgg.Core + * @subpackage Likes */ gatekeeper(); $entity_guid = (int) get_input('guid'); //check to see if the user has already liked the item -if (elgg_annotation_exists($entity_guid, 'likes')){ +if (elgg_annotation_exists($entity_guid, 'likes')) { system_message(elgg_echo("likes:alreadyliked")); forward($_SERVER['HTTP_REFERER']); } @@ -53,8 +54,9 @@ } system_message(elgg_echo("likes:likes")); + //add to river -add_to_river('annotation/annotatelike','likes',$user->guid,$entity->guid, "", 0, $annotation); +add_to_river('annotation/annotatelike', 'likes', $user->guid, $entity->guid, "", 0, $annotation); // Forward back to the page where the user 'liked' the object forward($_SERVER['HTTP_REFERER']); diff --git a/actions/likes/delete.php b/actions/likes/delete.php index 3e9ef32ad06..3ca82308d0a 100644 --- a/actions/likes/delete.php +++ b/actions/likes/delete.php @@ -2,7 +2,8 @@ /** * Elgg delete like action * - * @package Elgg + * @package Elgg.Core + * @subpackage Likes */ // Ensure we're logged in diff --git a/actions/login.php b/actions/login.php index 0063a1f08a0..b7823514ad9 100644 --- a/actions/login.php +++ b/actions/login.php @@ -45,20 +45,20 @@ } } else { register_error(elgg_echo('loginerror')); -// // let a plugin hook say why login failed or react to it. -// $params = array( -// 'username' => $username, -// 'password' => $password, -// 'persistent' => $persistent, -// 'user' => $user -// ); -// -// // Returning FALSE to this function will generate a standard -// // "Could not log you in" message. -// // Plugins should use this hook to provide details, and then return TRUE. -// if (!trigger_plugin_hook('failed_login', 'user', $params, FALSE)) { -// register_error(elgg_echo('loginerror')); -// } + // // let a plugin hook say why login failed or react to it. + // $params = array( + // 'username' => $username, + // 'password' => $password, + // 'persistent' => $persistent, + // 'user' => $user + // ); + // + // // Returning FALSE to this function will generate a standard + // // "Could not log you in" message. + // // Plugins should use this hook to provide details, and then return TRUE. + // if (!trigger_plugin_hook('failed_login', 'user', $params, FALSE)) { + // register_error(elgg_echo('loginerror')); + // } } forward(REFERRER); diff --git a/actions/register.php b/actions/register.php index b9db150c178..fcb25de35d2 100644 --- a/actions/register.php +++ b/actions/register.php @@ -14,7 +14,7 @@ $password2 = get_input('password2'); $email = get_input('email'); $name = get_input('name'); -$friend_guid = (int) get_input('friend_guid',0); +$friend_guid = (int) get_input('friend_guid', 0); $invitecode = get_input('invitecode'); if ($CONFIG->allow_registration) { diff --git a/actions/user/language.php b/actions/user/language.php index 79a583e68a1..252263cd27e 100644 --- a/actions/user/language.php +++ b/actions/user/language.php @@ -18,7 +18,7 @@ } if (($user) && ($language)) { - if (strcmp($language, $user->language)!=0) { + if (strcmp($language, $user->language) != 0) { $user->language = $language; if ($user->save()) { system_message(elgg_echo('user:language:success')); diff --git a/actions/user/password.php b/actions/user/password.php index 2af60dfb731..ceb9d458563 100644 --- a/actions/user/password.php +++ b/actions/user/password.php @@ -18,8 +18,8 @@ $user = get_entity($user_id); } -if (($user) && ($password!="")) { - if (strlen($password)>=4) { +if (($user) && ($password != "")) { + if (strlen($password) >= 4) { if ($password == $password2) { $user->salt = generate_random_cleartext_password(); // Reset the salt $user->password = generate_user_password($user, $password); diff --git a/actions/user/spotlight.php b/actions/user/spotlight.php index f20d6bdd069..00525254b83 100644 --- a/actions/user/spotlight.php +++ b/actions/user/spotlight.php @@ -2,13 +2,14 @@ /** * Close or open spotlight. * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage Spotlight + * @todo This is deprecated in 1.8 */ gatekeeper(); -$closed = get_input('closed','true'); +$closed = get_input('closed', 'true'); if ($closed != 'true') { $closed = false; } else { diff --git a/actions/useradd.php b/actions/useradd.php index c46b7fb96b0..8e287e1d8f8 100644 --- a/actions/useradd.php +++ b/actions/useradd.php @@ -25,7 +25,7 @@ try { $guid = register_user($username, $password, $name, $email, TRUE); - if (((trim($password) != "") && (strcmp($password, $password2)==0)) && ($guid)) { + if (((trim($password) != "") && (strcmp($password, $password2) == 0)) && ($guid)) { $new_user = get_entity($guid); if (($guid) && ($admin)) { $new_user->makeAdmin(); @@ -35,9 +35,13 @@ $new_user->created_by_guid = get_loggedin_userid(); set_user_validation_status($new_user->getGUID(), TRUE, 'admin_created'); - notify_user($new_user->guid, $CONFIG->site->guid, elgg_echo('useradd:subject'), sprintf(elgg_echo('useradd:body'), $name, $CONFIG->site->name, $CONFIG->site->url, $username, $password)); + $subject = elgg_echo('useradd:subject'); + $body = sprintf(elgg_echo('useradd:body'), $name, + $CONFIG->site->name, $CONFIG->site->url, $username, $password); - system_message(sprintf(elgg_echo("adduser:ok"),$CONFIG->sitename)); + notify_user($new_user->guid, $CONFIG->site->guid, $subject, $body); + + system_message(sprintf(elgg_echo("adduser:ok"), $CONFIG->sitename)); } else { register_error(elgg_echo("adduser:bad")); } diff --git a/actions/usersettings/save.php b/actions/usersettings/save.php index 83987486cbc..5e375941fcb 100644 --- a/actions/usersettings/save.php +++ b/actions/usersettings/save.php @@ -2,14 +2,14 @@ /** * Aggregate action for saving settings * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage UserSettings */ global $CONFIG; gatekeeper(); -trigger_plugin_hook('usersettings:save','user'); +trigger_plugin_hook('usersettings:save', 'user'); forward($_SERVER['HTTP_REFERER']); diff --git a/actions/widgets/add.php b/actions/widgets/add.php index 42d884a02d0..b38e53f0d8b 100644 --- a/actions/widgets/add.php +++ b/actions/widgets/add.php @@ -2,8 +2,8 @@ /** * Elgg widget add action * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage Widgets.Management */ $guid = get_input('user'); @@ -16,7 +16,7 @@ if (!empty($guid)) { if ($user = get_entity($guid)) { if ($user->canEdit()) { - $result = add_widget($user->getGUID(),$handler,$context,0,$column); + $result = add_widget($user->getGUID(), $handler, $context, 0, $column); } } } diff --git a/actions/widgets/reorder.php b/actions/widgets/reorder.php index fbc8c537919..c7c525a81b4 100644 --- a/actions/widgets/reorder.php +++ b/actions/widgets/reorder.php @@ -2,8 +2,8 @@ /** * Elgg widget reorder action * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage Widgets.Management */ $owner = get_input('owner'); diff --git a/actions/widgets/save.php b/actions/widgets/save.php index ca8a4dd9f4a..6737679396d 100644 --- a/actions/widgets/save.php +++ b/actions/widgets/save.php @@ -2,19 +2,19 @@ /** * Elgg widget save action * - * @package Elgg - * @subpackage Core + * @package Elgg.Core + * @subpackage Widgets.Management */ $guid = get_input('guid'); $params = $_REQUEST['params']; $pageurl = get_input('pageurl'); -$noforward = get_input('noforward',false); +$noforward = get_input('noforward', false); $result = false; if (!empty($guid)) { - $result = save_widget_info($guid,$params); + $result = save_widget_info($guid, $params); } if ($noforward) { diff --git a/engine/classes/APIException.php b/engine/classes/APIException.php index a16ea3e6259..377538c36c3 100644 --- a/engine/classes/APIException.php +++ b/engine/classes/APIException.php @@ -1,10 +1,11 @@ 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 ec2cedfe52e..cdcfe363f30 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 @@ function __construct($id = null) { if ($annotation) { $objarray = (array) $annotation; - foreach($objarray as $key => $value) { + foreach ($objarray as $key => $value) { $this->attributes[$key] = $value; } @@ -44,7 +44,8 @@ function __construct($id = null) { /** * 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 @@ function __get($name) { /** * 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 @@ function __set($name, $value) { */ 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 @@ function save() { /** * Delete the annotation. + * + * @return bool */ function delete() { return delete_annotation($this->id); @@ -97,12 +102,16 @@ public function getURL() { 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 a494471b99e..549772d6d8a 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 @@ function __construct() { /** * 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 @@ public function set_variable($variable, $value) { /** * 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 @@ public function get_variable($variable) { /** * 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 @@ function __get($key) { /** * 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 @@ function __set($key, $value) { * 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 @@ function __isset($key) { * 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 @@ function __unset($key) { /** * 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 public function save($key, $data); /** * 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 public function load($key, $offset = 0, $limit = null); /** * Invalidate a key * - * @param string $key + * @param string $key Name + * * @return bool */ abstract public function delete($key); @@ -121,16 +161,18 @@ abstract public function delete($key); /** * 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 @@ public function add($key, $data) { } // 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 b0924fbe77d..4f9aae1aff0 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 @@ public function __construct($directory_root = "") { * @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 @@ public function open(ElggFile $file, $mode) { $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 @@ public function open(ElggFile $file, $mode) { } - if (($mode!='write') && (!file_exists($fullname))) { + if (($mode != 'write') && (!file_exists($fullname))) { return false; } @@ -82,7 +83,8 @@ public function open(ElggFile $file, $mode) { $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 @@ public function open(ElggFile $file, $mode) { /** * 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 @@ public function write($f, $data) { /** * 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 @@ public function read($f, $length, $offset = 0) { * Close a file pointer * * @param resource $f A file pointer resource + * * @return bool */ public function close($f) { @@ -130,6 +135,7 @@ public function close($f) { * Delete an ElggFile file. * * @param ElggFile $file File to delete + * * @return bool */ public function delete(ElggFile $file) { @@ -144,8 +150,10 @@ public function delete(ElggFile $file) { /** * 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 @@ public function seek($f, $position) { * 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 @@ public function tell($f) { /** * 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 @@ public function eof($f) { /** * 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 @@ public function getFileSize(ElggFile $file) { /** * 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 @@ public function getFilenameOnFilestore(ElggFile $file) { } 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 @@ public function getFilenameOnFilestore(ElggFile $file) { /** * 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 @@ public function grabFile(ElggFile $file) { /** * 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 @@ public function exists(ElggFile $file) { /** * 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 @@ public function getSize($prefix = '', $container_guid) { * 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 @@ protected function make_directory_root($dirroot) { /** * 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 @@ private function mb_str_split($string, $charset = 'UTF8') { /** * 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 @@ protected function make_file_matrix($identifier) { * 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 @@ public function getParameters() { /** * 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 80617936e49..95b141d457f 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 @@ protected function initialise_attributes() { $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 @@ protected function initialise_attributes() { * * @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 @@ public function __clone() { * 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 @@ public function get($name) { * 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 @@ public function set($name, $value) { /** * 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 @@ public function getMetaData($name) { /** * Return an attribute or a piece of metadata. * - * @param string $name + * @param string $name Name + * * @return mixed */ function __get($name) { @@ -270,8 +299,9 @@ function __get($name) { /** * 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 @@ function __set($name, $value) { * @tip Use isset($entity->property) * * @param string $name The name of the attribute or metadata. + * * @return bool */ function __isset($name) { @@ -296,12 +327,13 @@ function __isset($name) { * @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 @@ function __unset($name) { * @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 @@ public function setMetaData($name, $value, $value_type = "", $multiple = false) } $this->temp_metadata[$name][] = $value; - } - else { + } else { $this->temp_metadata[$name] = $value; } } @@ -349,7 +382,8 @@ public function setMetaData($name, $value, $value_type = "", $multiple = false) } 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 @@ public function setMetaData($name, $value, $value_type = "", $multiple = false) } $this->temp_metadata[$name][] = $value; - } - else { + } else { $this->temp_metadata[$name] = $value; } @@ -374,8 +407,10 @@ public function setMetaData($name, $value, $value_type = "", $multiple = false) * 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 @@ public function clearMetaData($name = "") { * 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 @@ public function getVolatileData($name) { /** * 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 @@ public function clearRelationships() { * * @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 @@ public function addRelationship($guid, $relationship) { /** * 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 @@ public function removeRelationship($guid, $relationship) { * 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 @@ function setPrivateSetting($name, $value) { /** * Returns a private setting value * - * @param $name + * @param string $name Name of the private setting + * * @return mixed */ function getPrivateSetting($name) { @@ -490,7 +532,8 @@ function getPrivateSetting($name) { /** * Removes private setting * - * @param $name + * @param string $name Name of the private setting + * * @return bool */ function removePrivateSetting($name) { @@ -502,11 +545,14 @@ function removePrivateSetting($name) { * * @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 @@ function annotate($name, $value, $access_id = ACCESS_PRIVATE, $owner_id = 0, $va /** * 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 @@ function getAnnotations($name, $limit = 50, $offset = 0, $order="asc") { /** * 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 @@ function clearAnnotations($name = "") { * Count annotations. * * @param string $name The type of annotation. + * * @return int */ function countAnnotations($name = "") { @@ -560,7 +610,8 @@ function countAnnotations($name = "") { /** * 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 @@ function getAnnotationsAvg($name) { /** * 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 @@ function getAnnotationsSum($name) { /** * 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 @@ function getAnnotationsMin($name) { /** * 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 @@ function getAnnotationsMax($name) { * 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 @@ function getEntitiesFromRelationship($relationship, $inverse = false, $limit = 5 /** * 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 @@ function countEntitiesFromRelationship($relationship, $inverse_relationship = FA /** * 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 @@ function canEdit($user_guid = 0) { /** * 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 @@ function canEditMetadata($metadata = null, $user_guid = 0) { * 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 @@ public function getURL() { * @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 @@ public function setURL($url) { * 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 @@ public function getIcon($size = 'medium') { * * @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 @@ public function save() { $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 @@ public function save() { // 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 @@ public function save() { // 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 @@ public function save() { /** * 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 @@ protected function load($guid) { // 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 @@ protected function load($guid) { * * @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 @@ public function delete() { * 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 @@ public function setLocation($location) { /** * 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 @@ public function getLocation() { /** * 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 @@ public function getCalendarStartTime() { * Returns the end timestamp. * * @todo Unimplemented + * + * @return int */ public function getCalendarEndTime() { return (int)$this->calendar_end; @@ -1107,7 +1185,8 @@ public function getExportableValues() { /** * 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 @@ public function export() { // 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 @@ public function export() { $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 @@ public function export() { /** * 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 @@ public function getSystemLogID() { /** * Return the class name of the object. + * + * @return string */ public function getClassName() { return get_class($this); @@ -1243,7 +1325,13 @@ public function getClassName() { * 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 @@ public function getObjectOwnerGUID() { * @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 @@ public function getTags($tag_names = NULL) { */ 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 @@ function valid() { * 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 577207c06e4..cfc8fbf682c 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 @@ protected function get($name) { /** * 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 @@ public function getEntity() { /** * 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 public function delete(); * 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 @@ public function getExportableValues() { 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 @@ public function getSubtype() { */ 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 @@ function valid() { * 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 a1bc81118ef..bf6732ca4fd 100644 --- a/engine/classes/ElggFile.php +++ b/engine/classes/ElggFile.php @@ -1,20 +1,24 @@ 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 @@ public function __construct($guid = null) { * Set the filename of this file. * * @param string $name The filename. + * + * @return void */ public function setFilename($name) { $this->filename = $name; @@ -47,33 +74,43 @@ public function setFilename($name) { /** * 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 @@ public function getMimeType() { /** * 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 @@ public function setMimeType($mimetype) { * Set the optional file description. * * @param string $description The description. + * + * @return bool */ public function setDescription($description) { $this->description = $description; @@ -105,6 +146,8 @@ public function setDescription($description) { * 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 @@ public function open($mode) { // 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 @@ public function open($mode) { } /** - * Write some data. + * Write data. * * @param string $data The data + * + * @return bool */ public function write($data) { $fs = $this->getFilestore(); @@ -147,10 +193,12 @@ public function write($data) { } /** - * 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 @@ public function grabFile() { /** * Close the file and commit changes + * + * @return bool */ public function close() { $fs = $this->getFilestore(); @@ -185,6 +235,8 @@ public function close() { /** * Delete this file. + * + * @return bool */ public function delete() { $fs = $this->getFilestore(); @@ -196,7 +248,9 @@ public function delete() { /** * 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 @@ public function tell() { /** * Return the size of the file in bytes. + * + * @return int */ public function size() { return $this->filestore->getFileSize($this); @@ -224,6 +280,8 @@ public function size() { /** * 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 @@ public function eof() { return $fs->eof($this->handle); } + /** + * Returns if the file exists + * + * @return bool + */ public function exists() { $fs = $this->getFilestore(); @@ -241,6 +304,8 @@ public function exists() { * Set a filestore. * * @param ElggFilestore $filestore The file store. + * + * @return void */ public function setFilestore(ElggFilestore $filestore) { $this->filestore = $filestore; @@ -250,6 +315,8 @@ public function setFilestore(ElggFilestore $filestore) { * 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 @@ protected function getFilestore() { $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 @@ protected function getFilestore() { 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 f386b7466df..2072af620c9 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 @@ function __construct($cache_path, $max_age = 0, $max_size = 0) { /** * 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 @@ protected function create_file($filename, $rw = "rb") { } // 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 @@ protected function create_file($filename, $rw = "rb") { /** * 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 @@ -63,15 +85,29 @@ protected function sanitise_filename($filename) { return $filename; } + /** + * 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 @@ public function save($key, $data) { /** * 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 @@ public function load($key, $offset = 0, $limit = null) { /** * 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 @@ public function __destruct() { // 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 11775c9b837..61ce167d0a1 100644 --- a/engine/classes/ElggFilestore.php +++ b/engine/classes/ElggFilestore.php @@ -1,14 +1,18 @@ getParameters(). + * + * @param array $parameters A list of parameters + * + * @return bool */ abstract public function setParameters(array $parameters); @@ -101,6 +123,7 @@ abstract public function setParameters(array $parameters); * 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 public function grabFile(ElggFile $file); /** * 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 4dea2bcd6ec..8721f931bdc 100644 --- a/engine/classes/ElggGroup.php +++ b/engine/classes/ElggGroup.php @@ -1,13 +1,36 @@ 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 @@ protected function initialise_attributes() { * * @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 @@ function __construct($guid = null) { 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 @@ function __construct($guid = null) { * Add an ElggObject to this group. * * @param ElggObject $object The object. + * * @return bool */ public function addObjectToGroup(ElggObject $object) { @@ -72,12 +96,22 @@ public function addObjectToGroup(ElggObject $object) { * 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 @@ public function get($name) { 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 @@ public function addFriend($friend_guid) { /** * 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 @@ public function removeFriend($friend_guid) { /** * For compatibility with Friendable + * + * Friending a group adds you as a member + * + * @return bool */ public function isFriend() { return $this->isMember(); @@ -123,6 +173,10 @@ public function isFriend() { /** * 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 @@ public function isFriendsWith($user_guid) { /** * 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 @@ public function isFriendOf($user_guid) { /** * 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 @@ public function getFriends($subtype = "", $limit = 10, $offset = 0) { /** * 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 @@ public function getFriendsOf($subtype = "", $limit = 10, $offset = 0) { /** * 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 @@ public function getFriendsObjects($subtype = "", $limit = 10, $offset = 0) { /** * 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 @@ public function isPublicMembership() { * 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 @@ public function isMember($user = 0) { /** * 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 @@ public function join(ElggUser $user) { /** * 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 @@ public function leave(ElggUser $user) { * 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 @@ protected function load($guid) { } // 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 @@ protected function load($guid) { // 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 @@ protected function load($guid) { /** * Override the save function. + * + * @return bool */ public function save() { // Save generic stuff @@ -288,6 +381,8 @@ public function save() { /** * 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 551e798f591..8d994d013cf 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 @@ public function save($key, $data) { $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 @@ public function load($key, $offset = 0, $limit = null) { /** * Invalidate a given key. * - * @param string $key + * @param string $key Name + * * @return bool */ public function delete($key) { @@ -71,6 +75,8 @@ public function delete($key) { * 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 @@ public function __destruct() { 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 070100586ca..e0d8e7beecf 100644 --- a/engine/classes/ElggMemcache.php +++ b/engine/classes/ElggMemcache.php @@ -1,6 +1,9 @@ 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 @@ function __construct($namespace = 'default') { * 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 @@ public function setDefaultExpiry($expires = 0) { * 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 @@ public function save($key, $data) { 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 @@ public function load($key, $offset = 0, $limit = null) { 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 fe8bb49599b..851397a930c 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 @@ function __construct($id = null) { 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 @@ function __construct($id = null) { /** * Class member get overloading * - * @param string $name + * @param string $name Name + * * @return mixed */ function __get($name) { @@ -47,8 +50,9 @@ function __get($name) { /** * 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 @@ function canEdit() { */ 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 @@ function save() { /** * Delete a given metadata. + * + * @return bool */ function delete() { return delete_metadata($this->id); @@ -106,6 +115,10 @@ public function getURL() { * 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 d19e1c84474..d2e3f14e40c 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 @@ protected function initialise_attributes() { * - 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 @@ function __construct($guid = null) { 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 @@ function __construct($guid = null) { /** * 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 @@ protected function load($guid) { } // 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 @@ protected function load($guid) { // 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 @@ public function save() { } // 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 @@ public function save() { * * 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 @@ function getSites($subtype="", $limit = 10, $offset = 0) { * 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 @@ function addToSite($site_guid) { * 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 @@ function getContainerEntity() { 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 3bbbc02fe74..0ea7fdf61d7 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 @@ public function get($name) { /** * 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 f90c1bb502d..847dfa8e944 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 @@ function __construct($id = null) { if ($relationship) { $objarray = (array) $relationship; - foreach($objarray as $key => $value) { + foreach ($objarray as $key => $value) { $this->attributes[$key] = $value; } } @@ -45,7 +45,8 @@ function __construct($id = null) { /** * Class member get overloading * - * @param string $name + * @param string $name Name + * * @return mixed */ function __get($name) { @@ -59,8 +60,9 @@ function __get($name) { /** * 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 @@ public function save() { /** * Delete a given relationship. + * + * @return bool */ public function delete() { return delete_relationship($this->id); @@ -106,6 +110,8 @@ public function getURL() { /** * Return an array of fields which can be exported. + * + * @return array */ public function getExportableValues() { return array( @@ -139,9 +145,10 @@ public function export() { /** * 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 @@ public function getSystemLogID() { /** * Return the class name of the object. + * + * @return string */ public function getClassName() { return get_class($this); @@ -201,6 +210,10 @@ public function getClassName() { * 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 @@ public function getObjectFromID($id) { /** * Return the GUID of the owner of this object. + * + * @return int */ public function getObjectOwnerGUID() { return $this->owner_guid; @@ -215,13 +230,18 @@ public function getObjectOwnerGUID() { /** * 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 @@ public function getSubtype() { 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 @@ function valid() { * 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 e34f7a961aa..1d59aaacc44 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 @@ function offsetGet($key) { } /** - * 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 @@ function offsetExists($offset) { 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 82c9c571af8..6d6a3d625c2 100644 --- a/engine/classes/ElggSharedMemoryCache.php +++ b/engine/classes/ElggSharedMemoryCache.php @@ -1,7 +1,11 @@ namespace = $namespace; diff --git a/engine/classes/ElggSite.php b/engine/classes/ElggSite.php index e71f3ca25e3..6f4abf18c99 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 @@ protected function initialise_attributes() { * - 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 @@ function __construct($guid = null) { /** * 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 @@ protected function load($guid) { } // 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 @@ protected function load($guid) { // 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 @@ public function save() { } // 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 @@ public function delete() { * * @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 @@ public function disable($reason = "") { /** * 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 @@ public function getMembers($limit = 10, $offset = 0) { /** * 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 @@ public function addUser($user_guid) { /** * 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 @@ public function removeUser($user_guid) { /** * 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 @@ public function addObject($object_guid) { /** * 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 @@ public function removeObject($object_guid) { /** * 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 @@ public function getExportableValues() { * 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 @@ public function check_walled_garden() { * 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 85facf7a76b..a846ab60f61 100644 --- a/engine/classes/ElggStaticVariableCache.php +++ b/engine/classes/ElggStaticVariableCache.php @@ -1,11 +1,11 @@ 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 @@ public function save($key, $data) { 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 @@ public function load($key, $offset = 0, $limit = null) { return false; } + /** + * Invalidate a given key. + * + * @param string $key Name + * + * @return bool + */ public function delete($key) { $namespace = $this->getNamespace(); @@ -53,6 +79,11 @@ public function delete($key) { 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 3bd93bba2ee..380fc4e8b68 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 @@ protected function initialise_attributes() { * * @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 @@ function __construct($guid = null) { 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 @@ function __construct($guid = null) { * 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 @@ protected function load($guid) { } // 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 @@ protected function load($guid) { // 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 @@ protected function load($guid) { /** * Saves this user to the database. + * * @return true|false */ public function save() { @@ -131,7 +148,9 @@ public function save() { } // 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 @@ public function delete() { * Ban this user. * * @param string $reason Optional reason + * + * @return bool */ public function ban($reason = "") { return ban_user($this->guid, $reason); @@ -170,8 +191,10 @@ public function ban($reason = "") { /** * Unban this user. + * + * @return bool */ - public function unban() { + public function unban() { return unban_user($this->guid); } @@ -236,11 +259,12 @@ public function removeAdmin() { * 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 @@ function getSites($subtype="", $limit = 10, $offset = 0) { * 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 @@ function addToSite($site_guid) { * 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 @@ function removeFromSite($site_guid) { * 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 @@ function addFriend($friend_guid) { * 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 @@ function isFriend() { * 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 @@ function isFriendsWith($user_guid) { * 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 @@ function isFriendOf($user_guid) { * 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 @@ function getFriends($subtype = "", $limit = 10, $offset = 0) { * 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 @@ function getFriendsOf($subtype = "", $limit = 10, $offset = 0) { * 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 @@ public function getObjects($subtype="", $limit = 10, $offset = 0) { * 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 @@ public function getFriendsObjects($subtype = "", $limit = 10, $offset = 0) { * 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 @@ public function countObjects($subtype = "") { * 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 @@ function getOwner() { /** * Return an array of fields which can be exported. + * + * @return array */ public function getExportableValues() { return array_merge(parent::getExportableValues(), array( @@ -409,8 +447,14 @@ public function getExportableValues() { )); } - // 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 @@ public function __set($name, $value) { 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 30cbc7dc271..c9a65967c69 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 @@ public function get($name) { /** * 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 739101dbb59..8dbb7c13fc4 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 @@ public function ErrorResult($message, $code = "", Exception $exception = NULL) { /** * 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 53bf58ceca5..11781d91b68 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 c8bc3bcd744..1adcd781ec9 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 @@ public function export(); /** * 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 d400bd0923a..588f9ec5a88 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 @@ public function addFriend($friend_guid); * 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 @@ public function isFriend(); * 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 @@ public function isFriendsWith($user_guid); * 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 @@ public function isFriendOf($user_guid); * 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 @@ public function getFriends($subtype = "", $limit = 10, $offset = 0); * 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 @@ public function getFriendsOf($subtype = "", $limit = 10, $offset = 0); * 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 @@ public function getFriendsObjects($subtype = "", $limit = 10, $offset = 0); * 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 746f0522a9d..bb8a7e76eb5 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 @@ protected function setStatusCode($status, $message = "") { /** * 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 @@ protected function getResult() { * * 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 @@ public function export() { $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 77641c42127..57403f44c43 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 946652cb469..14287fdf213 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 7eb984815e5..23b2ce2c846 100644 --- a/engine/classes/Importable.php +++ b/engine/classes/Importable.php @@ -1,13 +1,17 @@ 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 6f95598496e..98d131f38e3 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 @@ public function getSystemLogID(); /** * 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 @@ public function getSubtype(); * 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 1937665e0ff..d1decf75c9d 100644 --- a/engine/classes/NotImplementedException.php +++ b/engine/classes/NotImplementedException.php @@ -1,10 +1,10 @@ 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 @@ public function getAttribute($key) { 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 @@ public function getBody() { * 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 @@ public function getPublishedAsTime() { /** * 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 = ">"; } diff --git a/engine/classes/ODDDocument.php b/engine/classes/ODDDocument.php index d5619ce4600..4d185aba559 100644 --- a/engine/classes/ODDDocument.php +++ b/engine/classes/ODDDocument.php @@ -1,7 +1,9 @@ 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 @@ public function addElement(ODD $element) { } } + /** + * 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 @@ public function setWrapperFactory(ODDWrapperFactory $factory) { /** * Magic function to generate valid ODD XML for this item. + * + * @return string */ public function __toString() { $xml = ""; @@ -106,22 +145,57 @@ public function __toString() { 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 727c96733eb..acdfe2f7177 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 @@ function __construct($uuid, $class, $subclass = "") { $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 @@ function __construct($uuid, $entity_uuid, $name, $value, $type = "", $owner_uuid $this->setBody($value); } + /** + * Returns 'metadata' + * + * @return 'metadata' + */ protected function getTagName() { return "metadata"; } @@ -41,10 +74,19 @@ protected function getTagName() { /** * 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 @@ function __construct($uuid1, $type, $uuid2) { $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 d81a921a95e..56cf29596af 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 df77df158fa..05af35a01b7 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 c38209de844..3b6382f9efd 100644 --- a/engine/classes/SecurityException.php +++ b/engine/classes/SecurityException.php @@ -1,9 +1,10 @@ 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 2d0a2b49a4f..c0d358d5a6e 100644 --- a/engine/classes/XMLRPCArrayParameter.php +++ b/engine/classes/XMLRPCArrayParameter.php @@ -1,47 +1,56 @@ 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 "$params"; } } \ No newline at end of file diff --git a/engine/classes/XMLRPCBase64Parameter.php b/engine/classes/XMLRPCBase64Parameter.php index 461c1095990..eb82b24a8ea 100644 --- a/engine/classes/XMLRPCBase64Parameter.php +++ b/engine/classes/XMLRPCBase64Parameter.php @@ -1,23 +1,28 @@ value = base64_encode($blob); } - - function __toString() - { + + /** + * Convert to string + * + * @return string + */ + function __toString() { return "{$value}"; } } \ No newline at end of file diff --git a/engine/classes/XMLRPCBoolParameter.php b/engine/classes/XMLRPCBoolParameter.php index f9b3ec316d6..c53d9ad146d 100644 --- a/engine/classes/XMLRPCBoolParameter.php +++ b/engine/classes/XMLRPCBoolParameter.php @@ -1,18 +1,29 @@ value = (bool)$value; + + $this->value = (bool)$value; } - - function __toString() - { + + /** + * Convert to string + * + * @return string + */ + function __toString() { $code = ($this->value) ? "1" : "0"; return "{$code}"; } diff --git a/engine/classes/XMLRPCCall.php b/engine/classes/XMLRPCCall.php index 047f36d7bed..3b33f3ceee7 100644 --- a/engine/classes/XMLRPCCall.php +++ b/engine/classes/XMLRPCCall.php @@ -1,59 +1,62 @@ 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 39a849fe279..35e02fb37e1 100644 --- a/engine/classes/XMLRPCDateParameter.php +++ b/engine/classes/XMLRPCDateParameter.php @@ -1,25 +1,32 @@ 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}"; } diff --git a/engine/classes/XMLRPCDoubleParameter.php b/engine/classes/XMLRPCDoubleParameter.php index c2e346b375e..b7834650eac 100644 --- a/engine/classes/XMLRPCDoubleParameter.php +++ b/engine/classes/XMLRPCDoubleParameter.php @@ -1,18 +1,29 @@ value = (float)$value; + + $this->value = (float)$value; } - - function __toString() - { + + /** + * Convert to string + * + * @return string + */ + function __toString() { return "{$this->value}"; } } diff --git a/engine/classes/XMLRPCErrorResponse.php b/engine/classes/XMLRPCErrorResponse.php index c52601d3a12..c3dbd0373a2 100644 --- a/engine/classes/XMLRPCErrorResponse.php +++ b/engine/classes/XMLRPCErrorResponse.php @@ -1,18 +1,20 @@ addParameter( new XMLRPCStructParameter( array ( @@ -22,12 +24,13 @@ function __construct($message, $code = -32400) ) ); } - + /** * Output to XML. + * + * @return string */ - public function __toString() - { + public function __toString() { return "{$this->parameters[0]}"; } } \ No newline at end of file diff --git a/engine/classes/XMLRPCIntParameter.php b/engine/classes/XMLRPCIntParameter.php index ef950bc147d..0fc146165ea 100644 --- a/engine/classes/XMLRPCIntParameter.php +++ b/engine/classes/XMLRPCIntParameter.php @@ -1,18 +1,29 @@ value = (int)$value; + + $this->value = (int)$value; } - - function __toString() - { + + /** + * Convert to string + * + * @return string + */ + function __toString() { return "{$this->value}"; } } diff --git a/engine/classes/XMLRPCParameter.php b/engine/classes/XMLRPCParameter.php index cbec2c1a2cf..5fac3320177 100644 --- a/engine/classes/XMLRPCParameter.php +++ b/engine/classes/XMLRPCParameter.php @@ -1,11 +1,16 @@ 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 8381afb114e..35b28214bc7 100644 --- a/engine/classes/XMLRPCStringParameter.php +++ b/engine/classes/XMLRPCStringParameter.php @@ -1,18 +1,29 @@ value = $value; + + $this->value = $value; } - - function __toString() - { + + /** + * Convert to XML string + * + * @return string + */ + function __toString() { $value = htmlentities($this->value); return "{$value}"; } diff --git a/engine/classes/XMLRPCStructParameter.php b/engine/classes/XMLRPCStructParameter.php index 4f406abcbde..754c9261645 100644 --- a/engine/classes/XMLRPCStructParameter.php +++ b/engine/classes/XMLRPCStructParameter.php @@ -1,48 +1,55 @@ $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 .= "$k$v"; } - + return "$params"; } } \ No newline at end of file diff --git a/engine/classes/XMLRPCSuccessResponse.php b/engine/classes/XMLRPCSuccessResponse.php index 8ac1eae4b82..2f452ef424e 100644 --- a/engine/classes/XMLRPCSuccessResponse.php +++ b/engine/classes/XMLRPCSuccessResponse.php @@ -1,18 +1,22 @@ parameters as $param) + foreach ($this->parameters as $param) { $params .= "$param\n"; - + } + return "$params"; } } \ No newline at end of file diff --git a/engine/classes/XmlElement.php b/engine/classes/XmlElement.php index b44023eb305..64d54e6b0b1 100644 --- a/engine/classes/XmlElement.php +++ b/engine/classes/XmlElement.php @@ -1,19 +1,20 @@ 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 @@ function get_default_access(ElggUser $user = null) { * 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 @@ function get_annotation_sql($annotation_name, $entity_guid, $owner_guid, $exists * 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 @@ function elgg_get_access_object() { * * @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 18475de275f..63ddfcbfb8b 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 = "") { * ) * * - * @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 defeaa6e338..0f5a4f4001e 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 Twitter Services Settings'); * - * @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 3a8054b8c85..48421b2d623 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 @@ function get_annotations($entity_guid = 0, $entity_type = "", $entity_subtype = 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 @@ function get_annotations($entity_guid = 0, $entity_type = "", $entity_subtype = 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 @@ function get_annotations($entity_guid = 0, $entity_type = "", $entity_subtype = 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 @@ function get_annotations($entity_guid = 0, $entity_type = "", $entity_subtype = $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 @@ function get_annotations($entity_guid = 0, $entity_type = "", $entity_subtype = 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 @@ function get_annotations($entity_guid = 0, $entity_type = "", $entity_subtype = $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 @@ function get_annotations($entity_guid = 0, $entity_type = "", $entity_subtype = $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 @@ function get_annotations($entity_guid = 0, $entity_type = "", $entity_subtype = * * @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 @@ function get_entities_from_annotations($entity_type = "", $entity_subtype = "", * * @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 6cb8debaab1..fa7c17d8012 100644 --- a/engine/lib/api.php +++ b/engine/lib/api.php @@ -1,13 +1,13 @@ '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 @@ function auth_gettoken($username, $password) { * 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 ea0f5c51d5b..f1a18ddb8a4 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 0394cc7703b..d8c11b48580 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 c89a52395f8..811a4cdda75 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 76ca6c1938d..4b0a38bb3ef 100644 --- a/engine/lib/database.php +++ b/engine/lib/database.php @@ -64,7 +64,10 @@ * * 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 81be9675271..4d51e6d7d66 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: * * array( * 'title' => 'Text to display', @@ -270,8 +305,10 @@ function add_submenu_item($label, $link, $group = 'default', $onclick = false, $ * ) * * - * @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