aboutsummaryrefslogtreecommitdiff
path: root/engine
diff options
context:
space:
mode:
authorbrettp <brettp@36083f99-b078-4883-b0ff-0f9b5a30f544>2010-09-23 19:20:59 +0000
committerbrettp <brettp@36083f99-b078-4883-b0ff-0f9b5a30f544>2010-09-23 19:20:59 +0000
commitb2fcb1602f275bbe404311dae0cf2c0a4334c893 (patch)
tree5b772397c2939e6dfde18714adcd2263acd456d0 /engine
parent965cbe52f22809f19ca150feb585b0218aa89f85 (diff)
downloadelgg-b2fcb1602f275bbe404311dae0cf2c0a4334c893.tar.gz
elgg-b2fcb1602f275bbe404311dae0cf2c0a4334c893.tar.bz2
Refs #2450: Documented ElggSite, clarified some docs on ElggObject.
git-svn-id: http://code.elgg.org/elgg/trunk@6958 36083f99-b078-4883-b0ff-0f9b5a30f544
Diffstat (limited to 'engine')
-rw-r--r--engine/classes/ElggObject.php8
-rw-r--r--engine/classes/ElggSite.php138
2 files changed, 105 insertions, 41 deletions
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 @@
<?php
/**
- * ElggSite
- * Representation of a "site" in the system.
- * @author Curverider Ltd <info@elgg.com>
- * @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;
}