tonyair
/
silverstripe-framework
mirror of https://github.com/silverstripe/silverstripe-framework
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Improving API documentation 

git-svn-id: svn://svn.silverstripe.com/silverstripe/open/modules/sapphire/trunk@50453 467b73ca-7a2a-4603-9d3b-597d59a354a9
This commit is contained in:
Sam Minnee 2008-03-02 23:24:10 +00:00
parent a0fb07d8ba
commit 59d8a1ce8e
10 changed files with 118 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
api/RSSFeed.php
View File

@ -9,6 +9,7 @@
* RSSFeed class
*
* This class is used to create an RSS feed.
* @todo Improve documentation
* @package sapphire
* @subpackage integration
*/

1
api/SapphireSoapServer.php
View File

@ -7,6 +7,7 @@
/**
* Soap server class
* @todo Improve documentation
* @package sapphire
* @subpackage integration
*/

1
cli/DailyTask.php
View File

@ -7,6 +7,7 @@
/**
* Classes that must be run daily extend this class
* @todo Improve documentation
* @package sapphire
* @subpackage cron
*/

1
cli/ScheduledTask.php
View File

@ -7,6 +7,7 @@
/**
* Abstract task representing scheudled tasks
* @todo Improve documentation
* @package sapphire
* @subpackage cron
*/

3
core/ArrayLib.php
View File

@ -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){

18
core/ClassInfo.php
View File

@ -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;

4
core/control/ContentController.php
View File

@ -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

2
core/control/ContentNegotiator.php
View File

@ -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
*/

28
core/control/Controller.php
View File

@ -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;
}

76
core/control/Director.php
View File

@ -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:
* <code>
* if(Director::isLive()) Director::forceSSL();
* </code>
*/
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'
*/