Skip to content
Snippets Groups Projects
Commit 140cfbcd authored by Gerrit Uitslag's avatar Gerrit Uitslag
Browse files

PHPDocs for common.php

parent 8f3419f5
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 127 additions and 4 deletions
inc/common.php
+ 127
− 4
View file @ 140cfbcd
......@@ -22,6 +22,9 @@ define('RECENTS_MEDIA_PAGES_MIXED', 32);
*
* @author Andreas Gohr <andi@splitbrain.org>
* @see htmlspecialchars()
*
* @param string $string the string being converted
* @return string converted string
*/
function hsc($string) {
return htmlspecialchars($string, ENT_QUOTES, 'UTF-8');
......@@ -33,6 +36,9 @@ function hsc($string) {
* You can give an indention as optional parameter
*
* @author Andreas Gohr <andi@splitbrain.org>
*
* @param string $string line of text
* @param int $indent number of spaces indention
*/
function ptln($string, $indent = 0) {
echo str_repeat(' ', $indent)."$string\n";
......@@ -42,6 +48,9 @@ function ptln($string, $indent = 0) {
* strips control characters (<32) from the given string
*
* @author Andreas Gohr <andi@splitbrain.org>
*
* @param $string string being stripped
* @return string
*/
function stripctl($string) {
return preg_replace('/[\x00-\x1F]+/s', '', $string);
......@@ -63,6 +72,9 @@ function getSecurityToken() {
/**
* Check the secret CSRF token
*
* @param null|string $token security token or null to read it from request variable
* @return bool success if the token matched
*/
function checkSecurityToken($token = null) {
/** @var Input $INPUT */
......@@ -81,6 +93,9 @@ function checkSecurityToken($token = null) {
* Print a hidden form field with a secret CSRF token
*
* @author Andreas Gohr <andi@splitbrain.org>
*
* @param bool $print if true print the field, otherwise html of the field is returned
* @return void|string html of hidden form field
*/
function formSecurityToken($print = true) {
$ret = '<div class="no"><input type="hidden" name="sectok" value="'.getSecurityToken().'" /></div>'."\n";
......@@ -93,6 +108,11 @@ function formSecurityToken($print = true) {
*
* @author Andreas Gohr <andi@splitbrain.org>
* @author Chris Smith <chris@jalakai.co.uk>
*
* @param string $id pageid
* @param bool $htmlClient add info about whether is mobile browser
* @return array with info for a request of $id
*
*/
function basicinfo($id, $htmlClient=true){
global $USERINFO;
......@@ -139,6 +159,8 @@ function basicinfo($id, $htmlClient=true){
* array.
*
* @author Andreas Gohr <andi@splitbrain.org>
*
* @return array with info about current document
*/
function pageinfo() {
global $ID;
......@@ -246,6 +268,8 @@ function pageinfo() {
/**
* Return information about the current media item as an associative array.
*
* @return array with info about current media item
*/
function mediainfo(){
global $NS;
......@@ -261,6 +285,10 @@ function mediainfo(){
* Build an string of URL parameters
*
* @author Andreas Gohr
*
* @param array $params array with key-value pairs
* @param string $sep series of pairs are separated by this character
* @return string query string
*/
function buildURLparams($params, $sep = '&amp;') {
$url = '';
......@@ -281,6 +309,10 @@ function buildURLparams($params, $sep = '&amp;') {
* Skips keys starting with '_', values get HTML encoded
*
* @author Andreas Gohr
*
* @param array $params array with (attribute name-attribute value) pairs
* @param bool $skipempty skip empty string values?
* @return string
*/
function buildAttributes($params, $skipempty = false) {
$url = '';
......@@ -302,6 +334,8 @@ function buildAttributes($params, $skipempty = false) {
* This builds the breadcrumb trail and returns it as array
*
* @author Andreas Gohr <andi@splitbrain.org>
*
* @return array(pageid=>name, ... )
*/
function breadcrumbs() {
// we prepare the breadcrumbs early for quick session closing
......@@ -361,6 +395,10 @@ function breadcrumbs() {
* Urlencoding is ommitted when the second parameter is false
*
* @author Andreas Gohr <andi@splitbrain.org>
*
* @param string $id pageid being filtered
* @param bool $ue apply urlencoding?
* @return string
*/
function idfilter($id, $ue = true) {
global $conf;
......@@ -574,6 +612,8 @@ function ml($id = '', $more = '', $direct = true, $sep = '&amp;', $abs = false)
* Consider using wl() instead, unless you absoutely need the doku.php endpoint
*
* @author Andreas Gohr <andi@splitbrain.org>
*
* @return string
*/
function script() {
return DOKU_BASE.DOKU_SCRIPT;
......@@ -600,6 +640,7 @@ function script() {
*
* @author Andreas Gohr <andi@splitbrain.org>
* @author Michael Klier <chi@chimeric.de>
*
* @param string $text - optional text to check, if not given the globals are used
* @return bool - true if a spam word was found
*/
......@@ -668,6 +709,7 @@ function checkwordblock($text = '') {
* headers
*
* @author Andreas Gohr <andi@splitbrain.org>
*
* @param boolean $single If set only a single IP is returned
* @return string
*/
......@@ -739,6 +781,8 @@ function clientIP($single = false) {
* Adapted from the example code at url below
*
* @link http://www.brainhandles.com/2007/10/15/detecting-mobile-browsers/#code
*
* @return bool if true, client is mobile browser; otherwise false
*/
function clientismobile() {
/* @var Input $INPUT */
......@@ -763,6 +807,7 @@ function clientismobile() {
* If $conf['dnslookups'] is disabled it simply returns the input string
*
* @author Glen Harris <astfgl@iamnota.org>
*
* @param string $ips comma separated list of IP addresses
* @return string a comma separated list of hostnames
*/
......@@ -789,6 +834,9 @@ function gethostsbyaddrs($ips) {
* removes stale lockfiles
*
* @author Andreas Gohr <andi@splitbrain.org>
*
* @param string $id page id
* @return bool page is locked?
*/
function checklock($id) {
global $conf;
......@@ -819,6 +867,8 @@ function checklock($id) {
* Lock a page for editing
*
* @author Andreas Gohr <andi@splitbrain.org>
*
* @param string $id page id to lock
*/
function lock($id) {
global $conf;
......@@ -841,6 +891,7 @@ function lock($id) {
* Unlock a page if it was locked by the user
*
* @author Andreas Gohr <andi@splitbrain.org>
*
* @param string $id page id to unlock
* @return bool true if a lock was removed
*/
......@@ -866,6 +917,9 @@ function unlock($id) {
*
* @see formText() for 2crlf conversion
* @author Andreas Gohr <andi@splitbrain.org>
*
* @param string $text
* @return string
*/
function cleanText($text) {
$text = preg_replace("/(\015\012)|(\015)/", "\012", $text);
......@@ -885,6 +939,9 @@ function cleanText($text) {
*
* @see cleanText() for 2unix conversion
* @author Andreas Gohr <andi@splitbrain.org>
*
* @param string $text
* @return string
*/
function formText($text) {
$text = str_replace("\012", "\015\012", $text);
......@@ -895,6 +952,10 @@ function formText($text) {
* Returns the specified local text in raw format
*
* @author Andreas Gohr <andi@splitbrain.org>
*
* @param string $id page id
* @param string $ext extension of file being read, default 'txt'
* @return string
*/
function rawLocale($id, $ext = 'txt') {
return io_readFile(localeFN($id, $ext));
......@@ -904,6 +965,10 @@ function rawLocale($id, $ext = 'txt') {
* Returns the raw WikiText
*
* @author Andreas Gohr <andi@splitbrain.org>
*
* @param string $id page id
* @param string $rev timestamp when a revision of wikitext is desired
* @return string
*/
function rawWiki($id, $rev = '') {
return io_readWikiPage(wikiFN($id, $rev), $id, $rev);
......@@ -914,6 +979,9 @@ function rawWiki($id, $rev = '') {
*
* @triggers COMMON_PAGETPL_LOAD
* @author Andreas Gohr <andi@splitbrain.org>
*
* @param string $id the id of the page to be created
* @return string parsed pagetemplate content
*/
function pageTemplate($id) {
global $conf;
......@@ -965,6 +1033,9 @@ function pageTemplate($id) {
* This works on data from COMMON_PAGETPL_LOAD
*
* @author Andreas Gohr <andi@splitbrain.org>
*
* @param array $data array with event data
* @return string
*/
function parsePageTemplate(&$data) {
/**
......@@ -1032,6 +1103,11 @@ function parsePageTemplate(&$data) {
* The returned order is prefix, section and suffix.
*
* @author Andreas Gohr <andi@splitbrain.org>
*
* @param string $range in form "from-to"
* @param string $id page id
* @param string $rev optional, the revision timestamp
* @return array with three slices
*/
function rawWikiSlices($range, $id, $rev = '') {
$text = io_readWikiPage(wikiFN($id, $rev), $id, $rev);
......@@ -1056,6 +1132,12 @@ function rawWikiSlices($range, $id, $rev = '') {
* lines between sections if needed (used on saving).
*
* @author Andreas Gohr <andi@splitbrain.org>
*
* @param string $pre prefix
* @param string $text text in the middle
* @param string $suf suffix
* @param bool $pretty add additional empty lines between sections
* @return string
*/
function con($pre, $text, $suf, $pretty = false) {
if($pretty) {
......@@ -1080,6 +1162,11 @@ function con($pre, $text, $suf, $pretty = false) {
*
* @author Andreas Gohr <andi@splitbrain.org>
* @author Ben Coburn <btcoburn@silicodon.net>
*
* @param string $id page id
* @param string $text wikitext being saved
* @param string $summary summary of text update
* @param bool $minor mark this saved version as minor update
*/
function saveWikiText($id, $text, $summary, $minor = false) {
/* Note to developers:
......@@ -1184,6 +1271,9 @@ function saveWikiText($id, $text, $summary, $minor = false) {
* revision date
*
* @author Andreas Gohr <andi@splitbrain.org>
*
* @param string $id page id
* @return int|string revision timestamp
*/
function saveOldRevision($id) {
$oldf = wikiFN($id);
......@@ -1203,8 +1293,8 @@ function saveOldRevision($id) {
* @param string $summary What changed
* @param boolean $minor Is this a minor edit?
* @param array $replace Additional string substitutions, @KEY@ to be replaced by value
*
* @return bool
*
* @author Andreas Gohr <andi@splitbrain.org>
*/
function notify($id, $who, $rev = '', $summary = '', $minor = false, $replace = array()) {
......@@ -1242,6 +1332,8 @@ function notify($id, $who, $rev = '', $summary = '', $minor = false, $replace =
*
* @author Andreas Gohr <andi@splitbrain.org>
* @author Todd Augsburger <todd@rollerorgans.com>
*
* @return array|string
*/
function getGoogleQuery() {
/* @var Input $INPUT */
......@@ -1283,6 +1375,7 @@ function getGoogleQuery() {
* @param int $size A file size
* @param int $dec A number of decimal places
* @return string human readable size
*
* @author Martin Benjamin <b.martin@cybernet.ch>
* @author Aidan Lister <aidan@php.net>
* @version 1.0.0
......@@ -1304,6 +1397,9 @@ function filesize_h($size, $dec = 1) {
* Return the given timestamp as human readable, fuzzy age
*
* @author Andreas Gohr <gohr@cosmocode.de>
*
* @param int $dt timestamp
* @return string
*/
function datetime_h($dt) {
global $lang;
......@@ -1338,6 +1434,10 @@ function datetime_h($dt) {
*
* @see datetime_h
* @author Andreas Gohr <gohr@cosmocode.de>
*
* @param int|null $dt timestamp when given, null will take current timestamp
* @param string $format empty default to $conf['dformat'], or provide format as recognized by strftime()
* @return string
*/
function dformat($dt = null, $format = '') {
global $conf;
......@@ -1355,6 +1455,7 @@ function dformat($dt = null, $format = '') {
*
* @author <ungu at terong dot com>
* @link http://www.php.net/manual/en/function.date.php#54072
*
* @param int $int_date: current date in UNIX timestamp
* @return string
*/
......@@ -1371,6 +1472,9 @@ function date_iso8601($int_date) {
*
* @author Harry Fuecks <hfuecks@gmail.com>
* @author Christopher Smith <chris@jalakai.co.uk>
*
* @param string $email email address
* @return string
*/
function obfuscate($email) {
global $conf;
......@@ -1398,6 +1502,10 @@ function obfuscate($email) {
* Removes quoting backslashes
*
* @author Andreas Gohr <andi@splitbrain.org>
*
* @param string $string
* @param string $char backslashed character
* @return string
*/
function unslash($string, $char = "'") {
return str_replace('\\'.$char, $char, $string);
......@@ -1408,6 +1516,9 @@ function unslash($string, $char = "'") {
*
* @author <gilthans dot NO dot SPAM at gmail dot com>
* @link http://de3.php.net/manual/en/ini.core.php#79564
*
* @param string $v shorthands
* @return int|string
*/
function php_to_byte($v) {
$l = substr($v, -1);
......@@ -1437,6 +1548,9 @@ function php_to_byte($v) {
/**
* Wrapper around preg_quote adding the default delimiter
*
* @param string $string
* @return string
*/
function preg_quote_cb($string) {
return preg_quote($string, '/');
......@@ -1606,6 +1720,7 @@ function userlink($username = null, $textonly = false) {
* When no image exists, returns an empty string
*
* @author Andreas Gohr <andi@splitbrain.org>
*
* @param string $type - type of image 'badge' or 'button'
* @return string
*/
......@@ -1636,9 +1751,8 @@ function license_img($type) {
* @author Filip Oscadal <webmaster@illusionsoftworks.cz>
* @author Andreas Gohr <andi@splitbrain.org>
*
* @param int $mem Size of memory you want to allocate in bytes
* @param int $bytes
* @internal param int $used already allocated memory (see above)
* @param int $mem Size of memory you want to allocate in bytes
* @param int $bytes already allocated memory (see above)
* @return bool
*/
function is_mem_available($mem, $bytes = 1048576) {
......@@ -1669,6 +1783,8 @@ function is_mem_available($mem, $bytes = 1048576) {
*
* @link http://support.microsoft.com/kb/q176113/
* @author Andreas Gohr <andi@splitbrain.org>
*
* @param string $url url being directed to
*/
function send_redirect($url) {
/* @var Input $INPUT */
......@@ -1740,6 +1856,10 @@ function valid_input_set($param, $valid_values, $array, $exc = '') {
/**
* Read a preference from the DokuWiki cookie
* (remembering both keys & values are urlencoded)
*
* @param string $pref preference key
* @param string $default value returned when preference not found
* @return string preference value
*/
function get_doku_pref($pref, $default) {
$enc_pref = urlencode($pref);
......@@ -1758,6 +1878,9 @@ function get_doku_pref($pref, $default) {
/**
* Add a preference to the DokuWiki cookie
* (remembering $_COOKIE['DOKU_PREFS'] is urlencoded)
*
* @param string $pref preference key
* @param string $val preference value
*/
function set_doku_pref($pref, $val) {
global $conf;
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment