From b2fcb1602f275bbe404311dae0cf2c0a4334c893 Mon Sep 17 00:00:00 2001 From: brettp Date: Thu, 23 Sep 2010 19:20:59 +0000 Subject: Refs #2450: Documented ElggSite, clarified some docs on ElggObject. git-svn-id: http://code.elgg.org/elgg/trunk@6958 36083f99-b078-4883-b0ff-0f9b5a30f544 --- engine/classes/ElggObject.php | 8 ++- engine/classes/ElggSite.php | 138 ++++++++++++++++++++++++++++++------------ 2 files changed, 105 insertions(+), 41 deletions(-) (limited to 'engine') diff --git a/engine/classes/ElggObject.php b/engine/classes/ElggObject.php index 50ebe2d2d..d19e1c844 100644 --- a/engine/classes/ElggObject.php +++ b/engine/classes/ElggObject.php @@ -33,9 +33,11 @@ class ElggObject extends ElggEntity { * Load or create a new ElggObject. * * If no arguments are passed, create a new entity. - * If an argument is passed as an int, attempt to load that object by guid. - * If an argument is passed as an object, assume that it is as database result object and attempt to load - * by $obj->guid. + * + * If an argument is passed attempt to load a full Object entity. Arguments + * can be: + * - 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. * @throws IOException If passed an incorrect guid diff --git a/engine/classes/ElggSite.php b/engine/classes/ElggSite.php index 06cdf70ea..08d47ade5 100644 --- a/engine/classes/ElggSite.php +++ b/engine/classes/ElggSite.php @@ -1,10 +1,26 @@ - * @package Elgg - * @subpackage Core + * A Site entity. + * + * ElggSite represents a single site entity. + * + * An ElggSite object is an ElggEntity child class with the subtype + * of "site." It is created upon installation and hold all the + * information about a site: + * - name + * - description + * - url + * + * Every ElggEntity (except ElggSite) belongs to a site. + * + * @internal ElggSite represents a single row from the sites_entity + * table, as well as the corresponding ElggEntity row from the entities table. + * + * @warning Multiple site support isn't fully developed. + * + * @package Elgg.Core + * @subpackage DataMode.Site + * @link http://docs.elgg.org/DataModel/Sites */ class ElggSite extends ElggEntity { /** @@ -24,11 +40,19 @@ class ElggSite extends ElggEntity { } /** - * Construct a new site object, optionally from a given id value. + * Load or create a new ElggSite. * - * @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 site. + * If no arguments are passed, create a new entity. + * + * If an argument is passed attempt to load a full Site entity. Arguments + * can be: + * - The GUID of a site entity. + * - 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. + * @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(); @@ -45,7 +69,7 @@ class ElggSite extends ElggEntity { // 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; } @@ -78,11 +102,11 @@ class ElggSite extends ElggEntity { } /** - * Override the load function. - * This function will ensure that all data is loaded (were possible), so - * if only part of the ElggSite is loaded, it'll load the rest. + * Loads the full ElggSite when given a guid. * * @param int $guid + * @return bool + * @throws InvalidClassException */ protected function load($guid) { // Test to see if we have the generic stuff @@ -112,7 +136,11 @@ class ElggSite extends ElggEntity { } /** - * Override the save function. + * Saves site-specific attributes. + * + * @internal Site attributes are saved in the sites_entity table. + * + * @return bool */ public function save() { // Save generic stuff @@ -125,7 +153,12 @@ class ElggSite extends ElggEntity { } /** - * Delete this site. + * Delete the site. + * + * @note You cannot delete the current site. + * + * @return bool + * @throws SecurityException */ public function delete() { global $CONFIG; @@ -137,9 +170,13 @@ class ElggSite extends ElggEntity { } /** - * Disable override to add safety rail. + * Disable the site + * + * @note You cannot disable the current site. * - * @param unknown_type $reason + * @param string $reason + * @return bool + * @throws SecurityException */ public function disable($reason = "") { global $CONFIG; @@ -152,7 +189,7 @@ class ElggSite extends ElggEntity { } /** - * Return a list of users using this site. + * Returns an array of ElggUser entities who are members of the site. * * @param int $limit * @param int $offset @@ -163,47 +200,52 @@ class ElggSite extends ElggEntity { } /** - * Add a user to the site. + * Adds a user to the site. * * @param int $user_guid + * @return bool */ public function addUser($user_guid) { return add_site_user($this->getGUID(), $user_guid); } /** - * Remove a site user. + * Removes a user from the site. * * @param int $user_guid + * @return bool */ public function removeUser($user_guid) { return remove_site_user($this->getGUID(), $user_guid); } /** - * Get an array of member ElggObjects. + * Returns an array of ElggObject entities that belong to the site. * * @param string $subtype * @param int $limit * @param int $offset + * @return array */ public function getObjects($subtype="", $limit = 10, $offset = 0) { get_site_objects($this->getGUID(), $subtype, $limit, $offset); } /** - * Add an object to the site. + * Adds an object to the site. * - * @param int $user_id + * @param int $object_guid + * @return bool */ public function addObject($object_guid) { return add_site_object($this->getGUID(), $object_guid); } /** - * Remove a site user. + * Remvoes an object from the site. * - * @param int $user_id + * @param int $object_guid + * @return bool */ public function removeObject($object_guid) { return remove_site_object($this->getGUID(), $object_guid); @@ -216,15 +258,20 @@ class ElggSite extends ElggEntity { * @param int $limit * @param int $offset * @return unknown + * @todo Unimplemented */ public function getCollections($subtype="", $limit = 10, $offset = 0) { get_site_collections($this->getGUID(), $subtype, $limit, $offset); } - // EXPORTABLE INTERFACE //////////////////////////////////////////////////////////// + /* + * EXPORTABLE INTERFACE + */ /** * Return an array of fields which can be exported. + * + * @return array */ public function getExportableValues() { return array_merge(parent::getExportableValues(), array( @@ -233,38 +280,53 @@ class ElggSite extends ElggEntity { 'url', )); } - + + /** + * Halts bootup and redirects to the site front page + * if site is in walled garden mode, no user is logged in, + * and the URL is not a public page. + * + * @link http://docs.elgg.org/Tutorials/WalledGarden + */ public function check_walled_garden() { global $CONFIG; - + if ($CONFIG->walled_garden && !isloggedin()) { // hook into the index system call at the highest priority register_plugin_hook('index', 'system', 'elgg_walled_garden_index', 1); - + if (!$this->is_public_page()) { register_error(elgg_echo('loggedinrequired')); forward(); } } } - + + /** + * Returns if a URL is public for this site when in Walled Garden mode. + * + * 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='') { global $CONFIG; - + if (empty($url)) { $url = current_page_url(); - + // do not check against URL queries if ($pos = strpos($url, '?')) { $url = substr($url, 0, $pos); } } - + // always allow index page if ($url == $CONFIG->url) { return TRUE; } - + // default public pages $defaults = array( 'action/login', @@ -279,12 +341,12 @@ class ElggSite extends ElggEntity { '_css/css\.css', '_css/js\.php', ); - + // include a hook for plugin authors to include public pages $plugins = trigger_plugin_hook('public_pages', 'walled_garden', NULL, array()); - + // lookup admin-specific public pages - + // allow public pages foreach (array_merge($defaults, $plugins) as $public) { $pattern = "`^{$CONFIG->url}$public/*$`i"; @@ -292,7 +354,7 @@ class ElggSite extends ElggEntity { return TRUE; } } - + // non-public page return FALSE; } -- cgit v1.2.3