diff --git a/api/RSSFeed.php b/api/RSSFeed.php index ecf05c942..3dbed921d 100755 --- a/api/RSSFeed.php +++ b/api/RSSFeed.php @@ -9,6 +9,7 @@ * RSSFeed class * * This class is used to create an RSS feed. + * @todo Improve documentation * @package sapphire * @subpackage integration */ diff --git a/api/SapphireSoapServer.php b/api/SapphireSoapServer.php index e851d7f41..4c4cae331 100755 --- a/api/SapphireSoapServer.php +++ b/api/SapphireSoapServer.php @@ -7,6 +7,7 @@ /** * Soap server class + * @todo Improve documentation * @package sapphire * @subpackage integration */ diff --git a/cli/DailyTask.php b/cli/DailyTask.php index 92e00dbee..743f1d1de 100755 --- a/cli/DailyTask.php +++ b/cli/DailyTask.php @@ -7,6 +7,7 @@ /** * Classes that must be run daily extend this class + * @todo Improve documentation * @package sapphire * @subpackage cron */ diff --git a/cli/ScheduledTask.php b/cli/ScheduledTask.php index 17b047f03..21e753199 100755 --- a/cli/ScheduledTask.php +++ b/cli/ScheduledTask.php @@ -7,6 +7,7 @@ /** * Abstract task representing scheudled tasks + * @todo Improve documentation * @package sapphire * @subpackage cron */ diff --git a/core/ArrayLib.php b/core/ArrayLib.php index 985fd3ecf..fba8e6b7b 100755 --- a/core/ArrayLib.php +++ b/core/ArrayLib.php @@ -35,6 +35,9 @@ class ArrayLib extends Object { return $newArr; } + /** + * @todo Improve documentation + */ static function array_values_recursive($arr) { $lst = array(); foreach(array_keys($arr) as $k){ diff --git a/core/ClassInfo.php b/core/ClassInfo.php index 4f95c5d66..e632b6305 100755 --- a/core/ClassInfo.php +++ b/core/ClassInfo.php @@ -21,14 +21,26 @@ class ClassInfo { global $_ALL_CLASSES; return $_ALL_CLASSES && $_ALL_CLASSES['hastable']; } + + /** + * @todo Improve documentation + */ static function allClasses() { global $_ALL_CLASSES; return $_ALL_CLASSES['exists']; } + + /** + * @todo Improve documentation + */ static function exists($class) { global $_ALL_CLASSES; return isset($_ALL_CLASSES['exists'][$class]) ? $_ALL_CLASSES['exists'][$class] : null; } + + /** + * @todo Improve documentation + */ static function hasTable($class) { global $_ALL_CLASSES; return isset($_ALL_CLASSES['hastable'][$class]) ? $_ALL_CLASSES['hastable'][$class] : null; @@ -90,6 +102,9 @@ class ClassInfo { return $baseDataClass ? $baseDataClass : $class; } + /** + * @todo Improve documentation + */ static function subclassesFor($class){ global $_ALL_CLASSES; $subclasses = isset($_ALL_CLASSES['children'][$class]) ? $_ALL_CLASSES['children'][$class] : null; @@ -98,6 +113,9 @@ class ClassInfo { return $subclasses; } + /** + * @todo Improve documentation + */ static function ancestry($class, $onlyWithTables = false) { global $_ALL_CLASSES; diff --git a/core/control/ContentController.php b/core/control/ContentController.php index 716f9c7c2..115e4b081 100644 --- a/core/control/ContentController.php +++ b/core/control/ContentController.php @@ -6,7 +6,7 @@ */ /** - * The most common kind if controller; effectively a controller linked to a {@link DataObject}. + * The most common kind of controller; effectively a controller linked to a {@link DataObject}. * * ContentControllers are most useful in the content-focused areas of a site. This is generally * the bulk of a site; however, they may be less appropriate in, for example, the user management @@ -18,6 +18,8 @@ * * Subclasses of ContentController are generally instantiated by ModelAsController; this will create * a controller based on the URLSegment action variable, by looking in the SiteTree table. + * + * @todo Can this be used for anything other than SiteTree controllers? * * @package sapphire * @subpackage control diff --git a/core/control/ContentNegotiator.php b/core/control/ContentNegotiator.php index 423982c41..7cde3ab3f 100755 --- a/core/control/ContentNegotiator.php +++ b/core/control/ContentNegotiator.php @@ -7,6 +7,8 @@ /** * The content negotiator performs text/html or application/xhtml+xml switching. * It does this through the static function ContentNegotiator::process() + * + * @todo Improve documentation * @package sapphire * @subpackage control */ diff --git a/core/control/Controller.php b/core/control/Controller.php index 489696991..42a220608 100644 --- a/core/control/Controller.php +++ b/core/control/Controller.php @@ -75,6 +75,8 @@ class Controller extends ViewableData { return $this->response; } + protected $baseInitCalled = false; + /** * Executes this controller, and return an {@link HTTPResponse} object with the result. * @@ -96,8 +98,6 @@ class Controller extends ViewableData { * controllers - {@link ModelAsController} and {@link RootURLController} are two examples here. If you want to make more * orthodox functionality, it's better to overload {@link init()} or {@link index()}. * - * - * * Execute the appropriate action handler. If none is given, use defaultAction to display * a template. The default action will be appropriate in most cases where displaying data * is the core goal; the Viewer can call methods on the controller to get the data it needs. @@ -105,7 +105,6 @@ class Controller extends ViewableData { * @param array $requestParams GET and POST variables. * @return HTTPResponse The response that this controller produces, including HTTP headers such as redirection info */ - protected $baseInitCalled = false; function run($requestParams) { if(isset($_GET['debug_profile'])) Profiler::mark("Controller", "run"); $this->pushCurrent(); @@ -292,10 +291,17 @@ class Controller extends ViewableData { return $this->response; } + /** + * This is the default action handler used if a method doesn't exist. + * It will process the controller object with the template returned by {@link getViewer()} + */ function defaultAction($action) { return $this->getViewer($action)->process($this); } + /** + * Returns the action that is being executed on this controller. + */ function getAction() { return $this->action; } @@ -330,8 +336,9 @@ class Controller extends ViewableData { } /** - * Call this to disable basic authentication on test sites + * Call this to disable basic authentication on test sites. * must be called in the init() method + * @deprecated Use BasicAuth::disable() instead? This is used in CliController - it should be updated. */ function disableBasicAuth() { $this->basicAuthEnabled = false; @@ -394,6 +401,7 @@ class Controller extends ViewableData { * @param member The member whose permissions need checking. Defaults to the currently logged * in user. * @return boolean + * @deprecated I don't believe that the system has widespread use/support of this. */ function can($perm, $member = null) { if(!$member) $member = Member::currentUser(); @@ -419,11 +427,15 @@ class Controller extends ViewableData { /** * Returns a link to any other page + * @deprecated It's unclear what value this has; construct a link manually or use your own custom link-gen functions. */ function LinkTo($a, $b) { return Director::baseURL() . $a . '/' . $b; } + /** + * Returns an absolute link to this controller + */ function AbsoluteLink() { return Director::absoluteURL($this->Link()); } @@ -480,7 +492,8 @@ class Controller extends ViewableData { } /** - * Handle redirection + * Redirct to the given URL. + * It is generally recommended to call Director::redirect() rather than calling this function directly. */ function redirect($url) { if($this->response->getHeader('Location')) { @@ -530,7 +543,8 @@ class Controller extends ViewableData { } /** - * Check thAT + * Check that the given action is allowed to be called on this controller. + * This method is called by run() and makes use of {@link self::$allowed_actions}. */ function checkAccessAction($action) { // Collate self::$allowed_actions from this class and all parent classes @@ -547,7 +561,7 @@ class Controller extends ViewableData { $className = get_parent_class($className); } - if($access === null || $accessParts[0] === $accessParts[1]) { + if($access === null || (sizeof($accessParts) > 1 && $accessParts[0] === $accessParts[1])) { // user_error("Deprecated: please define static \$allowed_actions on your Controllers for security purposes", E_USER_NOTICE); return true; } diff --git a/core/control/Director.php b/core/control/Director.php index 13ab6dabd..c2fecd069 100644 --- a/core/control/Director.php +++ b/core/control/Director.php @@ -149,6 +149,10 @@ class Director { } + /** + * Returns the controller that should be used to handle the given URL. + * @todo More information about director rules. + */ static function getControllerForURL($url) { if(isset($_GET['debug_profile'])) Profiler::mark("Director","getControllerForURL"); $url = preg_replace( array( '/\/+/','/^\//', '/\/$/'),array('/','',''),$url); @@ -214,15 +218,24 @@ class Director { } } - + /** + * Returns the urlParam with the given name + */ static function urlParam($name) { return Director::$urlParams[$name]; } + /** + * Returns an array of urlParams + */ static function urlParams() { return Director::$urlParams; } + /** + * Returns the dataobject of the current page. + * This will only return a value if you are looking at a SiteTree page + */ static function currentPage() { if(isset(Director::$urlParams['URLSegment'])) { $SQL_urlSegment = Convert::raw2sql(Director::$urlParams['URLSegment']); @@ -236,7 +249,10 @@ class Director { } } - + /** + * Turns the given URL into an absolute URL. + * @todo Document how relativeToSiteBase works + */ static function absoluteURL($url, $relativeToSiteBase = false) { if(strpos($url,'/') === false && !$relativeToSiteBase) $url = dirname($_SERVER['REQUEST_URI'] . 'x') . '/' . $url; @@ -248,6 +264,9 @@ class Director { return $url; } + /** + * Returns the part of the URL, 'http://www.mysite.com'. + */ static function protocolAndHost() { if(self::$alternateBaseURL) { if(preg_match('/^(http[^:]*:\/\/[^/]+)\//1', self::$alternateBaseURL, $matches)) { @@ -314,12 +333,16 @@ class Director { Director::redirect($url); } + /** + * @deprecated This seems like a bit of a hack; is it used anywhere? + */ static function currentURLSegment() { return Director::$urlSegment; } /** * Returns a URL to composed of the given segments - usually controller, action, parameter + * @deprecated This function has little value. Just craft links yourself. */ static function link() { $parts = func_get_args(); @@ -327,7 +350,8 @@ class Director { } /** - * Returns a URL for the given controller + * Returns the root URL for the site. + * It will be automatically calculated unless it is overridden with {@link setBaseURL()}. */ static function baseURL() { if(self::$alternateBaseURL) return self::$alternateBaseURL; @@ -338,18 +362,35 @@ class Director { } } + /** + * Sets the root URL for the website. + * If the site isn't accessible from the URL you provide, weird things will happen. + */ static function setBaseURL($baseURL) { self::$alternateBaseURL = $baseURL; } + /** + * Returns the root filesystem folder for the site. + * It will be automatically calculated unless it is overridden with {@link setBaseFolder()}. + */ static function baseFolder() { if(self::$alternateBaseFolder) return self::$alternateBaseFolder; else return dirname(dirname($_SERVER['SCRIPT_FILENAME'])); } + + /** + * Sets the root folder for the website. + * If the site isn't accessible from the folder you provide, weird things will happen. + */ static function setBaseFolder($baseFolder) { self::$alternateBaseFolder = $baseFolder; } + /** + * Turns an absolute URL or folder into one that's relative to the root of the site. + * This is useful when turning a URL into a filesystem reference, or vice versa. + */ static function makeRelative($url) { $base1 = self::absoluteBaseURL(); $base2 = self::baseFolder(); @@ -362,26 +403,39 @@ class Director { return $url; } + /** + * @deprecated This method's behaviour isn't very useful or consistent. + */ static function getAbsURL($url) { return Director::baseURL() . $url; } - + + /** + * Given a filesystem reference relative to the site root, return the full filesystem path + */ static function getAbsFile($file) { if($file[0] == '/') return $file; return Director::baseFolder() . '/' . $file; } + /** + * Returns true if the given file exists. + * @param $file Filename specified relative to the site root + */ static function fileExists($file) { return file_exists(Director::getAbsFile($file)); } /** - * Returns the Absolute URL for the given controller + * Returns the Absolute URL of the site root. */ static function absoluteBaseURL() { return Director::absoluteURL(Director::baseURL()); } + /** + * Returns the Absolute URL of the site root, embedding the current basic-auth credentials into the URL. + */ static function absoluteBaseURLWithAuth() { if($_SERVER['PHP_AUTH_USER']) $login = "$_SERVER[PHP_AUTH_USER]:$_SERVER[PHP_AUTH_PW]@"; @@ -391,7 +445,12 @@ class Director { } /** - * Force the site to run on SSL. To use, call from _config.php + * Force the site to run on SSL. To use, call from _config.php. + * + * For example: + * + * if(Director::isLive()) Director::forceSSL(); + * */ static function forceSSL() { if(!isset($_SERVER['HTTPS']) && !Director::isDev()){ @@ -403,7 +462,7 @@ class Director { } /** - * Force a redirect to www.domain + * Force a redirect to a domain starting with "www." */ static function forceWWW() { if(!Director::isDev() && !Director::isTest() && strpos( $_SERVER['SERVER_NAME'], 'www') !== 0 ){ @@ -449,8 +508,7 @@ class Director { //////////////////////////////////////////////////////////////////////////////////////////// /** - * Sets the site mode (if it is the public site or the cms), - * and runs registered modules. + * Sets the site mode (if it is the public site or the cms), and runs registered modules. * * @param string $mode 'site' or 'cms' */