From: garvinhicking Date: Thu, 24 Nov 2005 18:27:23 +0000 (+0000) Subject: First batch of phpDoc comments. X-Git-Tag: 1.0~274 X-Git-Url: http://git.mjollnir.org/gw?a=commitdiff_plain;h=1f98ca2fca6c4951f43af78c8fc20fbcf1914a28;p=s9y.git First batch of phpDoc comments. --- diff --git a/include/admin/entries.inc.php b/include/admin/entries.inc.php index a7756fe..a15194f 100644 --- a/include/admin/entries.inc.php +++ b/include/admin/entries.inc.php @@ -19,7 +19,14 @@ $sort_order = array('timestamp' => DATE, $per_page = array('12', '16', '50', '100'); -// A little helper we don't want in _functions.inc.php +/** + * Shows the entry panel overview + * + * Shows a list of existing entries, with pagination and cookie-remember settings. + * + * @access public + * @return null + */ function serendipity_drawList() { global $serendipity, $sort_order, $per_page; diff --git a/include/admin/import.inc.php b/include/admin/import.inc.php index 731451c..b7592f9 100644 --- a/include/admin/import.inc.php +++ b/include/admin/import.inc.php @@ -13,12 +13,29 @@ if (!serendipity_checkPermission('adminImport')) { /* This won't do anything if safe-mode is ON, but let's try anyway since importing could take a while */ @set_time_limit(0); -/* For later use */ +/* Class construct. Each importer plugin must extend this class. */ class Serendipity_Import { var $trans_table = ''; - function getImportNotes() { return ""; } +/** + * Return textual notes of an importer plugin + * + * If an importer plugin needs to show any notes on the userinterface, those can be returned in this method. + * + * @access public + * @return string HTML-code of a interface/user hint + */ + function getImportNotes() { + return ""; + } +/** + * Get a list of available charsets the user can choose from. Depends on current language of the blog. + * + * @access public + * @param boolean If set to true, returns the option "UTF-8" as first select choice, which is then preselected. If false, the current language of the blog will be the default. + * @return array Array of available charsets to choose from + */ function getCharsets($utf8_default = true) { $charsets = array(); @@ -41,6 +58,13 @@ class Serendipity_Import { return $charsets; } +/** + * Decodes/Transcodes a string according to the selected charset, and the charset of the blog + * + * @access public + * @param string input string to convert + * @return string converted string + */ function &decode($string) { // xml_parser_* functions to recoding from ISO-8859-1/UTF-8 if (LANG_CHARSET == 'ISO-8859-1' || LANG_CHARSET == 'UTF-8') { @@ -70,10 +94,27 @@ class Serendipity_Import { } } +/** + * Decode/Transcode a string with the indicated translation table (member property). Useful for transcoding HTML entities to native characters. + * + * @access public + * @param string input string + * @return string output string + */ function strtr($data) { return strtr($this->decode($data), $this->trans_table); } +/** + * Decode/Transcode an array of strings. + * + * LONG + * + * @access public + * @see $this->strtr() + * @param array input array + * @return array output array + */ function strtrRecursive($data) { foreach ($data as $key => $val) { if (is_array($val)) { @@ -86,6 +127,15 @@ class Serendipity_Import { return $data; } +/** + * Get the transcoding table, depending on whether it was enabled for the instance of the importer plugin + * + * The member property $this->trans_table will be filled with the output of this function + * + * @access public + * @see $this->strtr() + * @return null + */ function getTransTable() { if (!serendipity_db_bool($this->data['use_strtr'])) { $this->trans_table = array(); @@ -101,6 +151,14 @@ class Serendipity_Import { } } +/** + * Execute a DB query on the source database of the import, instead of a DB query on the target database + * + * @access public + * @param string SQL Query + * @param ressource DB connection resource + * @return ressource SQL response + */ function &nativeQuery($query, $db = false) { global $serendipity; @@ -206,4 +264,3 @@ if (isset($serendipity['GET']['importFrom']) && serendipity_checkFormToken()) { } /* vim: set sts=4 ts=4 expandtab : */ -?> diff --git a/include/admin/installer.inc.php b/include/admin/installer.inc.php index 76e9dfd..6213c37 100644 --- a/include/admin/installer.inc.php +++ b/include/admin/installer.inc.php @@ -11,6 +11,17 @@ define('S9Y_I_WARNING', 0); define('S9Y_I_SUCCESS', 1); $basedir = serendipity_query_default('serendipityPath', false); +/** + * Checks a return code constant if it's successfull or an error and return HTML code + * + * The diagnosis checks return codes of several PHP checks. Depending + * on the input, a specially formatted string is returned. + * + * @access public + * @param int Return code + * @param string String to return wrapped in special HTML markup + * @return string returned String + */ function serendipity_installerResultDiagnose($result, $s) { global $errorCount; if ( $result === S9Y_I_SUCCESS ) { @@ -455,4 +466,3 @@ if ( (int)$serendipity['GET']['step'] == 0 ) { } /* vim: set sts=4 ts=4 expandtab : */ -?> diff --git a/include/admin/plugins.inc.php b/include/admin/plugins.inc.php index 2397153..d96a31d 100644 --- a/include/admin/plugins.inc.php +++ b/include/admin/plugins.inc.php @@ -14,6 +14,18 @@ include_once S9Y_INCLUDE_PATH . 'include/plugin_api.inc.php'; include_once S9Y_INCLUDE_PATH . 'include/plugin_internal.inc.php'; include_once S9Y_INCLUDE_PATH . 'include/functions_entries_admin.inc.php'; +/** + * Returns the name of a usergroup. + * + * If a special constant is defined for the name of the group, the name has been + * internationalized. This applies to the Admin/Chief Editor/Editor group names, + * which are different for each language. If such a constant is not present, + * the simple name of the group will be returned. + * + * @access public + * @param string name of the group + * @return string realname of the group + */ function serendipity_groupname($group) { if (defined('PLUGIN_GROUP_' . $group)) { return constant('PLUGIN_GROUP_' . $group); @@ -22,10 +34,27 @@ function serendipity_groupname($group) { } } +/** + * Sort the pluginlist by case-insensitive string functions + * + * @access public + * @param array Compared Plugin #1 + * @param array Compared Plugin #2 + * @return boolean Return code for array comparison + */ function serendipity_pluginListSort($x, $y) { return strnatcasecmp($x['name'] . ' - ' . $x['description'], $y['name'] . ' - ' . $y['description']); } +/** + * Show the list of plugins + * + * Shows a HTML list of all installed plugins, complete with config/delete/sort order options + * + * @access public + * @param boolean Indicates if event plugins (TRUE) or sidebar plugins (FALSE) shall be shown + * @return null + */ function show_plugins($event_only = false) { global $serendipity; @@ -162,6 +191,18 @@ function show_plugins($event_only = false) diff --git a/include/compat.inc.php b/include/compat.inc.php index 3b83820..8523b4e 100644 --- a/include/compat.inc.php +++ b/include/compat.inc.php @@ -21,7 +21,14 @@ if (!defined('DIRECTORY_SEPARATOR')) { } } -/* Function to get a snapshot uf used memory */ +/** + * Create a snapshot of the current memory usage + * + * This functions makes use of static function properties to store the last used memory and the intermediate snapshots. + * @access public + * @param string A label for debugging output + * @return boolean Return whether the snapshot could be evaluated + */ function memSnap($tshow = '') { static $avail = null; static $show = true; @@ -146,6 +153,13 @@ if (isset($serendipity['GET']['searchTerm'])) { $serendipity['GET']['searchTerm'] = htmlspecialchars(strip_tags($serendipity['GET']['searchTerm'])); } +/** + * Translate values coming from the Database into native PHP variables to detect boolean values. + * + * @access public + * @param string input value + * @return boolean boolean output value + */ function serendipity_get_bool($item) { static $translation = array('true' => true, 'false' => false); @@ -157,7 +171,16 @@ function serendipity_get_bool($item) { } } -// Needs to be included here so that it's globally available also when installing +/** + * Detect the language of the User Agent/Visitor + * + * This function needs to be included at this point so that it is globally available, also + * during installation. + * + * @access public + * @param boolean Toggle whether to include the language that has been autodetected. + * @return string Return the detected language name + */ function serendipity_detectLang($use_include = false) { global $serendipity; @@ -179,10 +202,24 @@ function serendipity_detectLang($use_include = false) { return $serendipity['lang']; } +/** + * Get the current serendipity version, minus the "-alpha", "-beta" or whatever tags + * + * @access public + * @param string Serendipity version + * @return string Serendipity version, stripped of unneeded parts + */ function serendipity_getCoreVersion($version) { return preg_replace('@^([0-9\.]+).*$@', '\1', $version); } +/** + * Make Serendipity emit an error message and terminate the script + * + * @access public + * @param string HTML code to die with + * @return null + */ function serendipity_die($html) { die( ' @@ -205,4 +242,3 @@ if (!isset($serendipity['serendipityPath'])) { $serendipity['indexFile'] = 'index.php'; /* vim: set sts=4 ts=4 expandtab : */ -?> diff --git a/include/db/db.inc.php b/include/db/db.inc.php index a5069e4..c891c40 100644 --- a/include/db/db.inc.php +++ b/include/db/db.inc.php @@ -6,6 +6,18 @@ if (@include_once(S9Y_INCLUDE_PATH . "include/db/{$serendipity['dbType']}.inc.ph @define('S9Y_DB_INCLUDED', TRUE); } +/** + * Perform a query to update the data of a certain table row + * + * You can pass the tablename and an array of keys to select the row, + * and an array of values to UPDATE in the DB table. + * + * @access public + * @param string Name of the DB table + * @param array Input array that controls the "WHERE" condition part. Pass it an associative array like array('key1' => 'value1', 'key2' => 'value2') to get a statement like "WHERE key1 = value1 AND key2 = value2". Escaping is done automatically in this function. + * @param array Input array that controls the "SET" condition part. Pass it an associative array like array('key1' => 'value1', 'key2' => 'value2') to get a statement like "SET key1 = value1, key2 = value2". Escaping is done automatically in this function. + * @return array Returns the result of the SQL query + */ function serendipity_db_update($table, $keys, $values) { global $serendipity; @@ -32,6 +44,16 @@ function serendipity_db_update($table, $keys, $values) return serendipity_db_query("UPDATE {$serendipity['dbPrefix']}$table SET $set $where"); } +/** + * Perform a query to insert an associative array into a specific SQL table + * + * You can pass a tablename and an array of input data to insert into an array. + * + * @access public + * @param string Name of the SQL table + * @param array Associative array of keys/values to insert into the table. Escaping is done automatically. + * @return array Returns the result of the SQL query + */ function serendipity_db_insert($table, $values) { global $serendipity; @@ -48,7 +70,20 @@ function serendipity_db_insert($table, $values) return serendipity_db_query("INSERT INTO {$serendipity['dbPrefix']}$table ($names) values ($vals)"); } -function serendipity_db_bool ($val) +/** + * Check whether an input value corresponds to a TRUE/FALSE option in the SQL database. + * + * Because older DBs could not store TRUE/FALSE values to be restored into a PHP variable, + * this function tries to detect what the return code of a SQL column is, and convert it + * to a PHP native boolean. + * + * Values that will be recognized as TRUE are 'true', 't' and '1'. + * + * @access public + * @param string input value to compare + * @return boolean boolean conversion of the input value + */ +function serendipity_db_bool($val) { if(($val === true) || ($val == 'true') || ($val == 't') || ($val == '1')) return true; @@ -57,6 +92,14 @@ function serendipity_db_bool ($val) return false; } +/** + * Return a SQL statement for a time interval or timestamp, specific to certain SQL backends + * + * @access public + * @param string Indicate whether to return a timestamp, or an Interval + * @param int The interval one might want to use, if Interval return was selected + * @return string SQL statement + */ function serendipity_db_get_interval($val, $ival = 900) { global $serendipity; @@ -90,4 +133,3 @@ function serendipity_db_get_interval($val, $ival = 900) { } /* vim: set sts=4 ts=4 expandtab : */ -?> diff --git a/include/db/mysql.inc.php b/include/db/mysql.inc.php index df5b46a..ea7dadc 100644 --- a/include/db/mysql.inc.php +++ b/include/db/mysql.inc.php @@ -2,10 +2,21 @@ # Copyright (c) 2003-2005, Jannis Hermanns (on behalf the Serendipity Developer Team) # All rights reserved. See LICENSE file for licensing details +/** + * Tells the DB Layer to start a DB transaction. + * + * @access public + */ function serendipity_db_begin_transaction(){ serendipity_db_query('start transaction'); } +/** + * Tells the DB Layer to end a DB transaction. + * + * @access public + * @param boolean If true, perform the query. If false, rollback. + */ function serendipity_db_end_transaction($commit){ if ($commit){ serendipity_db_query('commit'); @@ -14,16 +25,38 @@ function serendipity_db_end_transaction($commit){ } } -function serendipity_db_in_sql($col, &$search_ids) { +/** + * Assemble and return SQL condition for a "IN (...)" clause + * + * @access public + * @param string table column name + * @param array referenced array of values to search for in the "IN (...)" clause + * @param string condition of how to associate the different input values of the $search_ids parameter + * @return string resulting SQL string + */ +function serendipity_db_in_sql($col, &$search_ids, $type = ' OR ') { return $col . " IN (" . implode(', ', $search_ids) . ")"; } -/* Issues a query to the underlying database; - * returns: +/** + * Perform a DB Layer SQL query. + * + * This function returns values dependin on the input parameters and the result of the query. + * It can return: * false if there was an error, * true if the query succeeded but did not generate any rows * array of field values if it returned a single row and $single is true - * array of array of field values if it returned row(s) + * array of array of field values if it returned row(s) [stacked array] + * + * @access public + * @param string SQL query to execute + * @param boolean Toggle whether the expected result is a single row (TRUE) or multiple rows (FALSE). This affects whether the returned array is 1 or 2 dimensional! + * @param string Result type of the array indexing. Can be one of "assoc" (associative), "num" (numerical), "both" (numerical and associative, default) + * @param boolean If true, errors will be reported. If false, errors will be ignored. + * @param string A possible array key name, so that you can control the multi-dimensional mapping of an array by the key column + * @param string A possible array field name, so that you can control the multi-dimensional mapping of an array by the key column and the field value. + * @param boolean If true, the executed SQL error is known to fail, and should be disregarded (errors can be ignroed on DUPLICATE INDEX queries and the likes) + * @return mixed Returns the result of the SQL query, depending on the input parameters */ function &serendipity_db_query($sql, $single = false, $result_type = "both", $reportErr = false, $assocKey = false, $assocVal = false, $expectError = false) { global $serendipity; @@ -92,18 +125,36 @@ function &serendipity_db_query($sql, $single = false, $result_type = "both", $re } } +/** + * Returns the latest INSERT_ID of an SQL INSERT INTO command, for auto-increment columns + * + * @access public + * @return int Value of the auto-increment column + */ function serendipity_db_insert_id() { global $serendipity; return mysql_insert_id($serendipity['dbConn']); } +/** + * Returns the number of affected rows of a SQL query + * + * @access public + * @return int Number of affected rows + */ function serendipity_db_affected_rows() { global $serendipity; return mysql_affected_rows($serendipity['dbConn']); } +/** + * Returns the number of updated rows in a SQL query + * + * @access public + * @return int Number of updated rows + */ function serendipity_db_updated_rows() { global $serendipity; @@ -116,6 +167,12 @@ function serendipity_db_updated_rows() { return $arr[2]; } +/** + * Returns the number of matched rows in a SQL query + * + * @access public + * @return int Number of matched rows + */ function serendipity_db_matched_rows() { global $serendipity; @@ -128,18 +185,46 @@ function serendipity_db_matched_rows() { return $arr[1]; } +/** + * Returns a escaped string, so that it can be safely included in a SQL string encapsulated within quotes, without allowing SQL injection. + * + * @access public + * @param string input string + * @return string output string + */ function serendipity_db_escape_string($string) { return mysql_escape_string($string); } +/** + * Returns the option to a LIMIT SQL statement, because it varies accross DB systems + * + * @access public + * @param int Number of the first row to return data from + * @param int Number of rows to return + * @return string SQL string to pass to a LIMIT statement + */ function serendipity_db_limit($start, $offset) { return $start . ', ' . $offset; } +/** + * Return a LIMIT SQL option to the DB Layer as a full LIMIT statement + * + * @access public + * @param SQL string of a LIMIT option + * @return SQL string containing a full LIMIT statement + */ function serendipity_db_limit_sql($limitstring) { return ' LIMIT ' . $limitstring; } +/** + * Connect to the configured Database + * + * @access public + * @return ressource connection handle + */ function serendipity_db_connect() { global $serendipity; @@ -158,6 +243,13 @@ function serendipity_db_connect() { return $serendipity['dbConn']; } +/** + * Prepares a Serendipty query input to fully valid SQL. Replaces certain "template" variables. + * + * @access public + * @param string SQL query with template variables to convert + * @return ressource SQL ressource handle of the executed query + */ function serendipity_db_schema_import($query) { static $search = array('{AUTOINCREMENT}', '{PRIMARY}', '{UNSIGNED}', '{FULLTEXT}', '{FULLTEXT_MYSQL}', '{BOOLEAN}'); @@ -188,7 +280,14 @@ function serendipity_db_schema_import($query) { } } -/* probes the usability of the DB during installation */ +/** + * Try to connect to the configured Database (during installation) + * + * @access public + * @param array input configuration array, holding the connection info + * @param array referenced array which holds the errors that might be encountered + * @return boolean return true on success, false on error + */ function serendipity_db_probe($hash, &$errs) { global $serendipity; @@ -214,9 +313,15 @@ function serendipity_db_probe($hash, &$errs) { return true; } +/** + * Returns the SQL code used for concatenating strings + * + * @access public + * @param string Input string/column to concatenate + * @return string SQL parameter + */ function serendipity_db_concat($string) { return 'concat(' . $string . ')'; } /* vim: set sts=4 ts=4 expandtab : */ -?> diff --git a/include/db/mysqli.inc.php b/include/db/mysqli.inc.php index f1b8802..d11ab37 100644 --- a/include/db/mysqli.inc.php +++ b/include/db/mysqli.inc.php @@ -2,10 +2,21 @@ # Copyright (c) 2003-2005, Jannis Hermanns (on behalf the Serendipity Developer Team) # All rights reserved. See LICENSE file for licensing details +/** + * Tells the DB Layer to start a DB transaction. + * + * @access public + */ function serendipity_db_begin_transaction(){ serendipity_db_query('start transaction'); } +/** + * Tells the DB Layer to end a DB transaction. + * + * @access public + * @param boolean If true, perform the query. If false, rollback. + */ function serendipity_db_end_transaction($commit){ if ($commit){ serendipity_db_query('commit'); @@ -14,16 +25,38 @@ function serendipity_db_end_transaction($commit){ } } -function serendipity_db_in_sql($col, &$search_ids) { +/** + * Assemble and return SQL condition for a "IN (...)" clause + * + * @access public + * @param string table column name + * @param array referenced array of values to search for in the "IN (...)" clause + * @param string condition of how to associate the different input values of the $search_ids parameter + * @return string resulting SQL string + */ +function serendipity_db_in_sql($col, &$search_ids, $type = ' OR ') { return $col . " IN (" . implode(', ', $search_ids) . ")"; } -/* Issues a query to the underlying database; - * returns: +/** + * Perform a DB Layer SQL query. + * + * This function returns values dependin on the input parameters and the result of the query. + * It can return: * false if there was an error, * true if the query succeeded but did not generate any rows * array of field values if it returned a single row and $single is true - * array of array of field values if it returned row(s) + * array of array of field values if it returned row(s) [stacked array] + * + * @access public + * @param string SQL query to execute + * @param boolean Toggle whether the expected result is a single row (TRUE) or multiple rows (FALSE). This affects whether the returned array is 1 or 2 dimensional! + * @param string Result type of the array indexing. Can be one of "assoc" (associative), "num" (numerical), "both" (numerical and associative, default) + * @param boolean If true, errors will be reported. If false, errors will be ignored. + * @param string A possible array key name, so that you can control the multi-dimensional mapping of an array by the key column + * @param string A possible array field name, so that you can control the multi-dimensional mapping of an array by the key column and the field value. + * @param boolean If true, the executed SQL error is known to fail, and should be disregarded (errors can be ignroed on DUPLICATE INDEX queries and the likes) + * @return mixed Returns the result of the SQL query, depending on the input parameters */ function &serendipity_db_query($sql, $single = false, $result_type = "both", $reportErr = false, $assocKey = false, $assocVal = false, $expectError = false) { global $serendipity; @@ -85,17 +118,34 @@ function &serendipity_db_query($sql, $single = false, $result_type = "both", $re } } - +/** + * Returns the latest INSERT_ID of an SQL INSERT INTO command, for auto-increment columns + * + * @access public + * @return int Value of the auto-increment column + */ function serendipity_db_insert_id() { global $serendipity; return mysqli_insert_id($serendipity['dbConn']); } +/** + * Returns the number of affected rows of a SQL query + * + * @access public + * @return int Number of affected rows + */ function serendipity_db_affected_rows() { global $serendipity; return mysqli_affected_rows($serendipity['dbConn']); } +/** + * Returns the number of updated rows in a SQL query + * + * @access public + * @return int Number of updated rows + */ function serendipity_db_updated_rows() { global $serendipity; @@ -108,6 +158,12 @@ function serendipity_db_updated_rows() { return $arr[1]; } +/** + * Returns the number of matched rows in a SQL query + * + * @access public + * @return int Number of matched rows + */ function serendipity_db_matched_rows() { global $serendipity; @@ -120,19 +176,47 @@ function serendipity_db_matched_rows() { return $arr[0]; } +/** + * Returns a escaped string, so that it can be safely included in a SQL string encapsulated within quotes, without allowing SQL injection. + * + * @access public + * @param string input string + * @return string output string + */ function serendipity_db_escape_string($string) { global $serendipity; return mysqli_escape_string($serendipity['dbConn'], $string); } +/** + * Returns the option to a LIMIT SQL statement, because it varies accross DB systems + * + * @access public + * @param int Number of the first row to return data from + * @param int Number of rows to return + * @return string SQL string to pass to a LIMIT statement + */ function serendipity_db_limit($start, $offset) { return $start . ', ' . $offset; } +/** + * Return a LIMIT SQL option to the DB Layer as a full LIMIT statement + * + * @access public + * @param SQL string of a LIMIT option + * @return SQL string containing a full LIMIT statement + */ function serendipity_db_limit_sql($limitstring) { return ' LIMIT ' . $limitstring; } +/** + * Connect to the configured Database + * + * @access public + * @return ressource connection handle + */ function serendipity_db_connect() { global $serendipity; @@ -152,6 +236,13 @@ function serendipity_db_connect() { return $serendipity['dbConn']; } +/** + * Prepares a Serendipty query input to fully valid SQL. Replaces certain "template" variables. + * + * @access public + * @param string SQL query with template variables to convert + * @return ressource SQL ressource handle of the executed query + */ function serendipity_db_schema_import($query) { static $search = array('{AUTOINCREMENT}', '{PRIMARY}', '{UNSIGNED}', '{FULLTEXT}', '{FULLTEXT_MYSQL}', '{BOOLEAN}'); @@ -181,7 +272,14 @@ function serendipity_db_schema_import($query) { } } -/* probes the usability of the DB during installation */ +/** + * Try to connect to the configured Database (during installation) + * + * @access public + * @param array input configuration array, holding the connection info + * @param array referenced array which holds the errors that might be encountered + * @return boolean return true on success, false on error + */ function serendipity_db_probe($hash, &$errs) { global $serendipity; @@ -207,9 +305,15 @@ function serendipity_db_probe($hash, &$errs) { return true; } +/** + * Returns the SQL code used for concatenating strings + * + * @access public + * @param string Input string/column to concatenate + * @return string SQL parameter + */ function serendipity_db_concat($string) { return 'concat(' . $string . ')'; } /* vim: set sts=4 ts=4 expandtab : */ -?> diff --git a/include/db/postgres.inc.php b/include/db/postgres.inc.php index d348fef..33bbbaa 100644 --- a/include/db/postgres.inc.php +++ b/include/db/postgres.inc.php @@ -2,10 +2,21 @@ # Copyright (c) 2003-2005, Jannis Hermanns (on behalf the Serendipity Developer Team) # All rights reserved. See LICENSE file for licensing details +/** + * Tells the DB Layer to start a DB transaction. + * + * @access public + */ function serendipity_db_begin_transaction(){ serendipity_db_query('begin work'); } +/** + * Tells the DB Layer to end a DB transaction. + * + * @access public + * @param boolean If true, perform the query. If false, rollback. + */ function serendipity_db_end_transaction($commit){ if ($commit){ serendipity_db_query('commit'); @@ -14,10 +25,25 @@ function serendipity_db_end_transaction($commit){ } } -function serendipity_db_in_sql($col, &$search_ids) { +/** + * Assemble and return SQL condition for a "IN (...)" clause + * + * @access public + * @param string table column name + * @param array referenced array of values to search for in the "IN (...)" clause + * @param string condition of how to associate the different input values of the $search_ids parameter + * @return string resulting SQL string + */ +function serendipity_db_in_sql($col, &$search_ids, $type = ' OR ') { return $col . " IN (" . implode(', ', $search_ids) . ")"; } +/** + * Connect to the configured Database + * + * @access public + * @return ressource connection handle + */ function serendipity_db_connect() { global $serendipity; @@ -40,14 +66,36 @@ function serendipity_db_connect() { return $serendipity['dbConn']; } +/** + * Returns a escaped string, so that it can be safely included in a SQL string encapsulated within quotes, without allowing SQL injection. + * + * @access public + * @param string input string + * @return string output string + */ function serendipity_db_escape_string($string) { return pg_escape_string($string); } +/** + * Returns the option to a LIMIT SQL statement, because it varies accross DB systems + * + * @access public + * @param int Number of the first row to return data from + * @param int Number of rows to return + * @return string SQL string to pass to a LIMIT statement + */ function serendipity_db_limit($start, $offset) { return $offset . ', ' . $start; } +/** + * Return a LIMIT SQL option to the DB Layer as a full LIMIT statement + * + * @access public + * @param SQL string of a LIMIT option + * @return SQL string containing a full LIMIT statement + */ function serendipity_db_limit_sql($limitstring) { $limit_split = split(',', $limitstring); if (count($limit_split) > 1) { @@ -58,11 +106,23 @@ function serendipity_db_limit_sql($limitstring) { return $limit; } +/** + * Returns the number of affected rows of a SQL query + * + * @access public + * @return int Number of affected rows + */ function serendipity_db_affected_rows() { global $serendipity; return pg_affected_rows($serendipity['dbLastResult']); } +/** + * Returns the number of updated rows in a SQL query + * + * @access public + * @return int Number of updated rows + */ function serendipity_db_updated_rows() { global $serendipity; // it is unknown whether pg_affected_rows returns number of rows @@ -70,6 +130,12 @@ function serendipity_db_updated_rows() { return pg_affected_rows($serendipity['dbLastResult']); } +/** + * Returns the number of matched rows in a SQL query + * + * @access public + * @return int Number of matched rows + */ function serendipity_db_matched_rows() { global $serendipity; // it is unknown whether pg_affected_rows returns number of rows @@ -77,6 +143,14 @@ function serendipity_db_matched_rows() { return pg_affected_rows($serendipity['dbLastResult']); } +/** + * Returns the latest INSERT_ID of an SQL INSERT INTO command, for auto-increment columns + * + * @access public + * @param string Name of the table to get a INSERT ID for + * @param string Name of the column to get a INSERT ID for + * @return int Value of the auto-increment column + */ function serendipity_db_insert_id($table = '', $id = '') { global $serendipity; if (empty($table) || empty($id)) { @@ -94,6 +168,26 @@ function serendipity_db_insert_id($table = '', $id = '') { } } +/** + * Perform a DB Layer SQL query. + * + * This function returns values dependin on the input parameters and the result of the query. + * It can return: + * false if there was an error, + * true if the query succeeded but did not generate any rows + * array of field values if it returned a single row and $single is true + * array of array of field values if it returned row(s) [stacked array] + * + * @access public + * @param string SQL query to execute + * @param boolean Toggle whether the expected result is a single row (TRUE) or multiple rows (FALSE). This affects whether the returned array is 1 or 2 dimensional! + * @param string Result type of the array indexing. Can be one of "assoc" (associative), "num" (numerical), "both" (numerical and associative, default) + * @param boolean If true, errors will be reported. If false, errors will be ignored. + * @param string A possible array key name, so that you can control the multi-dimensional mapping of an array by the key column + * @param string A possible array field name, so that you can control the multi-dimensional mapping of an array by the key column and the field value. + * @param boolean If true, the executed SQL error is known to fail, and should be disregarded (errors can be ignroed on DUPLICATE INDEX queries and the likes) + * @return mixed Returns the result of the SQL query, depending on the input parameters + */ function &serendipity_db_query($sql, $single = false, $result_type = "both", $reportErr = false, $assocKey = false, $assocVal = false, $expectError = false) { global $serendipity; static $type_map = array( @@ -160,6 +254,13 @@ function &serendipity_db_query($sql, $single = false, $result_type = "both", $re } } +/** + * Prepares a Serendipty query input to fully valid SQL. Replaces certain "template" variables. + * + * @access public + * @param string SQL query with template variables to convert + * @return ressource SQL ressource handle of the executed query + */ function serendipity_db_schema_import($query) { static $search = array('{AUTOINCREMENT}', '{PRIMARY}', '{UNSIGNED}', '{FULLTEXT}', '{BOOLEAN}', 'int(1)', 'int(10)', 'int(11)', 'int(4)', '{UTF_8}'); @@ -179,6 +280,14 @@ function serendipity_db_schema_import($query) { } } +/** + * Try to connect to the configured Database (during installation) + * + * @access public + * @param array input configuration array, holding the connection info + * @param array referenced array which holds the errors that might be encountered + * @return boolean return true on success, false on error + */ function serendipity_db_probe($hash, &$errs) { global $serendipity; @@ -206,9 +315,15 @@ function serendipity_db_probe($hash, &$errs) { return true; } +/** + * Returns the SQL code used for concatenating strings + * + * @access public + * @param string Input string/column to concatenate + * @return string SQL parameter + */ function serendipity_db_concat($string) { return '(' . str_replace(', ', '||', $string) . ')'; } /* vim: set sts=4 ts=4 expandtab : */ -?> diff --git a/include/db/sqlite.inc.php b/include/db/sqlite.inc.php index 36e6421..ab04339 100644 --- a/include/db/sqlite.inc.php +++ b/include/db/sqlite.inc.php @@ -7,10 +7,21 @@ if (!function_exists('sqlite_open')) { @dl('sqlite.dll'); } +/** + * Tells the DB Layer to start a DB transaction. + * + * @access public + */ function serendipity_db_begin_transaction(){ serendipity_db_query('begin transaction'); } +/** + * Tells the DB Layer to end a DB transaction. + * + * @access public + * @param boolean If true, perform the query. If false, rollback. + */ function serendipity_db_end_transaction($commit){ if ($commit){ serendipity_db_query('commit transaction'); @@ -19,6 +30,12 @@ function serendipity_db_end_transaction($commit){ } } +/** + * Connect to the configured Database + * + * @access public + * @return ressource connection handle + */ function serendipity_db_connect() { global $serendipity; @@ -39,6 +56,13 @@ function serendipity_db_connect() return $serendipity['dbConn']; } +/** + * Returns a escaped string, so that it can be safely included in a SQL string encapsulated within quotes, without allowing SQL injection. + * + * @access public + * @param string input string + * @return string output string + */ function serendipity_db_escape_string($string) { static $search = array("\x00", '%', "'", '\"'); @@ -47,6 +71,12 @@ function serendipity_db_escape_string($string) return str_replace($search, $replace, $string); } +/** + * Returns the number of affected rows of a SQL query + * + * @access public + * @return int Number of affected rows + */ function serendipity_db_affected_rows() { global $serendipity; @@ -54,6 +84,12 @@ function serendipity_db_affected_rows() return sqlite_changes($serendipity['dbConn']); } +/** + * Returns the number of updated rows in a SQL query + * + * @access public + * @return int Number of updated rows + */ function serendipity_db_updated_rows() { global $serendipity; @@ -61,6 +97,12 @@ function serendipity_db_updated_rows() return sqlite_changes($serendipity['dbConn']); } +/** + * Returns the number of matched rows in a SQL query + * + * @access public + * @return int Number of matched rows + */ function serendipity_db_matched_rows() { global $serendipity; @@ -68,6 +110,12 @@ function serendipity_db_matched_rows() return sqlite_changes($serendipity['dbConn']); } +/** + * Returns the latest INSERT_ID of an SQL INSERT INTO command, for auto-increment columns + * + * @access public + * @return int Value of the auto-increment column + */ function serendipity_db_insert_id() { global $serendipity; @@ -75,6 +123,18 @@ function serendipity_db_insert_id() return sqlite_last_insert_rowid($serendipity['dbConn']); } +/** + * Parse result arrays into expected format for further operations + * + * SQLite does not support to return "e.entryid" within a $row['entryid'] return. + * So this function manually iteratse through all result rows and rewrites 'X.yyyy' to 'yyyy'. + * Yeah. This sucks. Don't tell me! + * + * @access private + * @param ressource The row ressource handle + * @param int Bitmask to tell whether to fetch numerical/associative arrays + * @return array Propper array containing the ressource results + */ function serendipity_db_sqlite_fetch_array($res, $type = SQLITE_BOTH) { static $search = array('%00', '%25'); @@ -99,6 +159,15 @@ function serendipity_db_sqlite_fetch_array($res, $type = SQLITE_BOTH) return $row; } +/** + * Assemble and return SQL condition for a "IN (...)" clause + * + * @access public + * @param string table column name + * @param array referenced array of values to search for in the "IN (...)" clause + * @param string condition of how to associate the different input values of the $search_ids parameter + * @return string resulting SQL string + */ function serendipity_db_in_sql($col, &$search_ids, $type = ' OR ') { $sql = array(); if (!is_array($search_ids)) { @@ -113,6 +182,26 @@ function serendipity_db_in_sql($col, &$search_ids, $type = ' OR ') { return $cond; } +/** + * Perform a DB Layer SQL query. + * + * This function returns values dependin on the input parameters and the result of the query. + * It can return: + * false if there was an error, + * true if the query succeeded but did not generate any rows + * array of field values if it returned a single row and $single is true + * array of array of field values if it returned row(s) [stacked array] + * + * @access public + * @param string SQL query to execute + * @param boolean Toggle whether the expected result is a single row (TRUE) or multiple rows (FALSE). This affects whether the returned array is 1 or 2 dimensional! + * @param string Result type of the array indexing. Can be one of "assoc" (associative), "num" (numerical), "both" (numerical and associative, default) + * @param boolean If true, errors will be reported. If false, errors will be ignored. + * @param string A possible array key name, so that you can control the multi-dimensional mapping of an array by the key column + * @param string A possible array field name, so that you can control the multi-dimensional mapping of an array by the key column and the field value. + * @param boolean If true, the executed SQL error is known to fail, and should be disregarded (errors can be ignroed on DUPLICATE INDEX queries and the likes) + * @return mixed Returns the result of the SQL query, depending on the input parameters + */ function &serendipity_db_query($sql, $single = false, $result_type = "both", $reportErr = true, $assocKey = false, $assocVal = false, $expectError = false) { global $serendipity; @@ -190,6 +279,14 @@ function &serendipity_db_query($sql, $single = false, $result_type = "both", $re } } +/** + * Try to connect to the configured Database (during installation) + * + * @access public + * @param array input configuration array, holding the connection info + * @param array referenced array which holds the errors that might be encountered + * @return boolean return true on success, false on error + */ function serendipity_db_probe($hash, &$errs) { global $serendipity; @@ -211,6 +308,13 @@ function serendipity_db_probe($hash, &$errs) return false; } +/** + * Prepares a Serendipty query input to fully valid SQL. Replaces certain "template" variables. + * + * @access public + * @param string SQL query with template variables to convert + * @return ressource SQL ressource handle of the executed query + */ function serendipity_db_schema_import($query) { static $search = array('{AUTOINCREMENT}', '{PRIMARY}', '{UNSIGNED}', '{FULLTEXT}', '{BOOLEAN}', '{UTF_8}'); @@ -229,17 +333,38 @@ function serendipity_db_schema_import($query) } } +/** + * Returns the option to a LIMIT SQL statement, because it varies accross DB systems + * + * @access public + * @param int Number of the first row to return data from + * @param int Number of rows to return + * @return string SQL string to pass to a LIMIT statement + */ function serendipity_db_limit($start, $offset) { return $start . ', ' . $offset; } +/** + * Return a LIMIT SQL option to the DB Layer as a full LIMIT statement + * + * @access public + * @param SQL string of a LIMIT option + * @return SQL string containing a full LIMIT statement + */ function serendipity_db_limit_sql($limitstring) { return ' LIMIT ' . $limitstring; } +/** + * Returns the SQL code used for concatenating strings + * + * @access public + * @param string Input string/column to concatenate + * @return string SQL parameter + */ function serendipity_db_concat($string) { return 'concat(' . $string . ')'; } /* vim: set sts=4 ts=4 expandtab : */ -?> diff --git a/include/functions.inc.php b/include/functions.inc.php index 2503c72..2d8eeb9 100644 --- a/include/functions.inc.php +++ b/include/functions.inc.php @@ -14,6 +14,14 @@ include_once(S9Y_INCLUDE_PATH . "include/functions_comments.inc.php"); include_once(S9Y_INCLUDE_PATH . "include/functions_permalinks.inc.php"); include_once(S9Y_INCLUDE_PATH . "include/functions_smarty.inc.php"); +/** + * Truncate a string to a specific length, multibyte aware. Appends '...' if successfully truncated + * + * @access public + * @param string Input string + * @param int Length the final string should have + * @return string Truncated string + */ function serendipity_truncateString($s, $len) { if ( strlen($s) > ($len+3) ) { $s = serendipity_mb('substr', $s, 0, $len) . '...'; @@ -21,6 +29,11 @@ function serendipity_truncateString($s, $len) { return $s; } +/** + * Optionally turn on GZip Compression, if configured + * + * @access public + */ function serendipity_gzCompression() { global $serendipity; if (isset($serendipity['useGzip']) && serendipity_db_bool($serendipity['useGzip']) && function_exists('ob_gzhandler') && extension_loaded('zlib') && serendipity_ini_bool(ini_get('zlib.output_compression')) == false && serendipity_ini_bool(ini_get('session.use_trans_sid')) == false) { @@ -28,6 +41,14 @@ function serendipity_gzCompression() { } } +/** + * Returns a timestamp formatted according to the current Server timezone offset + * + * @access public + * @param int The timestamp you want to convert into the current server timezone. Defaults to "now". + * @param boolean A toggle to indicate, if the timezone offset should be ADDED or SUBSTRACTED from the timezone. Substracting is required to restore original time when posting an entry. + * @return int The final timestamp + */ function serendipity_serverOffsetHour($timestamp = null, $negative = false) { global $serendipity; @@ -42,6 +63,17 @@ function serendipity_serverOffsetHour($timestamp = null, $negative = false) { } } +/** + * Format a timestamp + * + * This function can convert an input timestamp into specific PHP strftime() outputs, including applying necessary timezone calculations. + * + * @access public + * @param string Output format for the timestamp + * @param int Timestamp to use for displaying + * @param boolean Indicates, if timezone calculations shall be used. + * @return string The formatted timestamp + */ function serendipity_strftime($format, $timestamp = null, $useOffset = true) { global $serendipity; @@ -67,6 +99,17 @@ function serendipity_strftime($format, $timestamp = null, $useOffset = true) { } } +/** + * A wrapper function call for formatting Timestamps. + * + * Utilizes serendipity_strftime() and prepares the output timestamp with a few tweaks, and applies automatic uppercasing of the return. + * + * @see serendipity_strftime() + * @param string Output format for the timestamp + * @param int Timestamp to use for displaying + * @param boolean Indicates, if timezone calculations shall be used. + * @return string The formatted timestamp + */ function serendipity_formatTime($format, $time, $useOffset = true) { static $cache; if (!isset($cache)) { @@ -82,6 +125,13 @@ function serendipity_formatTime($format, $time, $useOffset = true) { return serendipity_mb('ucfirst', serendipity_strftime($cache[$format], (int)$time, $useOffset)); } +/** + * Fetches the list of available templates/themes/styles. + * + * @access public + * @param string Directory to search for a template [recursive use] + * @return array Sorted array of available template names + */ function serendipity_fetchTemplates($dir = '') { global $serendipity; @@ -104,6 +154,14 @@ function serendipity_fetchTemplates($dir = '') { return $rv; } +/** + * Get information about a specific theme/template/style + * + * @access public + * @param string Directory name of a theme + * @param string Absolute path to the templates [for use on CVS mounted directories] + * @return array Associative array if template information + */ function serendipity_fetchTemplateInfo($theme, $abspath = null) { global $serendipity; @@ -142,6 +200,19 @@ function serendipity_fetchTemplateInfo($theme, $abspath = null) { return $data; } +/** + * Recursively walks an 1-dimensional array to map parent IDs and depths, depending on the nested array set. + * + * Used for sorting a list of comments, for example. The list of comment is iterated, and the nesting level is calculated, and the array will be sorted to represent the amount of nesting. + * + * @access public + * @param array Input array to investigate [consecutively sliced for recursive calls] + * @param string Array index name to indicate the ID value of an array index + * @param string Array index name to indicate the PARENT ID value of an array index, matched against the $child_name value + * @param int The parent id to check an element against for recursive nesting + * @param int The current depth of the cycled array + * @return array The sorted and shiny polished result array + */ function serendipity_walkRecursive($ary, $child_name = 'id', $parent_name = 'parent_id', $parentid = 0, $depth = 0) { global $serendipity; static $_resArray; @@ -176,6 +247,15 @@ function serendipity_walkRecursive($ary, $child_name = 'id', $parent_name = 'par return $_resArray; } +/** + * Fetch the list of Serendipity Authors + * + * @access public + * @param int Fetch only a specific User + * @param array Can contain an array of group IDs you only want to fetch authors of. + * @param boolean If set to TRUE, the amount of entries per author will also be returned + * @return array Result of the SQL query + */ function serendipity_fetchUsers($user = '', $group = null, $is_count = false) { global $serendipity; @@ -260,6 +340,18 @@ function serendipity_fetchUsers($user = '', $group = null, $is_count = false) { } +/** + * Sends a Mail with Serendipity formatting + * + * @access public + * @param string The recipient address of the mail + * @param string The subject of the mail + * @param string The body of the mail + * @param string The sender mail address of the mail + * @param array additional headers to pass to the E-Mail + * @param string The name of the sender + * @return int Return code of the PHP mail() function + */ function serendipity_sendMail($to, $subject, $message, $fromMail, $headers = NULL, $fromName = NULL) { global $serendipity; @@ -310,6 +402,13 @@ function serendipity_sendMail($to, $subject, $message, $fromMail, $headers = NUL return mail($to, $subject, $message, implode("\n", $headers)); } +/** + * Fetch all references (links) from a given entry ID + * + * @access public + * @param int The entry ID + * @return array The SQL result containing the references/links of an entry + */ function serendipity_fetchReferences($id) { global $serendipity; @@ -319,6 +418,13 @@ function serendipity_fetchReferences($id) { } +/** + * Encode a string to UTF-8, if not already in UTF-8 format. + * + * @access public + * @param string The input string + * @return string The output string + */ function serendipity_utf8_encode($string) { if (strtolower(LANG_CHARSET) != 'utf-8') { if (function_exists('iconv')) { @@ -333,6 +439,14 @@ function serendipity_utf8_encode($string) { } } +/** + * Create a link that can be used within a RSS feed to indicate a permalink for an entry or comment + * + * @access public + * @param array The input entry array + * @param boolean Toggle whether the link will be for a COMMENT [true] or an ENTRY [false] + * @return string A permalink for the given entry + */ function serendipity_rss_getguid($entry, $comments = false) { global $serendipity; @@ -361,20 +475,26 @@ function serendipity_rss_getguid($entry, $comments = false) { return $guid; } -// jbalcorn: starter function to clean up xhtml for atom feed. Add things to this as we find common -// mistakes, unless someone finds a better way to do this. -// DONE: -// since someone encoded all the urls, we can now assume any amp followed by -// whitespace or a HTML tag (i.e. &
)should be -// encoded and most not with a space are intentional -// TODO: -// check ALL ampersands, find out if it's a valid code, and encode if not +/** + * Perform some replacement calls to make valid XHTML content + * + * jbalcorn: starter function to clean up xhtml for atom feed. Add things to this as we find common + * mistakes, unless someone finds a better way to do this. + * DONE: + * since someone encoded all the urls, we can now assume any amp followed by + * whitespace or a HTML tag (i.e. &
)should be + * encoded and most not with a space are intentional + * + * @access public + * @param string Input HTML code + * @return string Cleaned HTML code + */ function xhtml_cleanup($html) { static $p = array( - '/\&([\s\<])/', // ampersand followed by whitespace or tag - '/\&$/', // ampersand at end of body + '/\&([\s\<])/', // ampersand followed by whitespace or tag + '/\&$/', // ampersand at end of body '/<(br|hr|img)([^\/>]*)>/i', // unclosed br tag - attributes included - '/\ /' + '/\ /' // Protect whitespace ); static $r = array( @@ -387,6 +507,13 @@ function xhtml_cleanup($html) { return preg_replace($p, $r, $html); } +/** + * Fetch user data for a specific Serendipity author + * + * @access public + * @param int The requested author id + * @return array The SQL result array + */ function serendipity_fetchAuthor($author) { global $serendipity; @@ -394,8 +521,12 @@ function serendipity_fetchAuthor($author) { } /** -* Split up a filename -**/ + * Split a filename into basename and extension parts + * + * @access public + * @param string Filename + * @return array Return array containing the basename and file extension + */ function serendipity_parseFileName($file) { $x = explode('.', $file); $suf = array_pop($x); @@ -403,6 +534,13 @@ function serendipity_parseFileName($file) { return array($f, $suf); } +/** + * Track the referer to a specific Entry ID + * + * @access public + * @param int Entry ID + * @return null + */ function serendipity_track_referrer($entry = 0) { global $serendipity; @@ -480,6 +618,15 @@ function serendipity_track_referrer($entry = 0) { } } +/** + * Garbage Collection for suppressed referrers + * + * "Bad" referrers, that only occured once to your entry are put within a + * SUPPRESS database table. Entries contained there will be cleaned up eventually. + * + * @access public + * @return null + */ function serendipity_track_referrer_gc() { global $serendipity; @@ -489,6 +636,15 @@ function serendipity_track_referrer_gc() { serendipity_db_query($gc); } +/** + * Track a URL used in your Blog (Exit-Tracking) + * + * @access public + * @param string Name of the DB table where to store the link (exits|referrers) + * @param string The URL to track + * @param int The Entry ID to relate the track to + * @return null + */ function serendipity_track_url($list, $url, $entry_id = 0) { global $serendipity; @@ -539,14 +695,45 @@ function serendipity_track_url($list, $url, $entry_id = 0) { } } +/** + * Display the list of top referrers + * + * @access public + * @see serendipity_displayTopUrlList() + * @param int Number of referrers to show + * @param boolean Whether to use HTML links for URLs + * @param int Interval for which the top referrers are aggregated + * @return string List of Top referrers + */ function serendipity_displayTopReferrers($limit = 10, $use_links = true, $interval = 7) { serendipity_displayTopUrlList('referrers', $limit, $use_links, $interval); } +/** + * Display the list of top exits + * + * @access public + * @see serendipity_displayTopUrlList() + * @param int Number of exits to show + * @param boolean Whether to use HTML links for URLs + * @param int Interval for which the top exits are aggregated + * @return string List of Top exits + */ function serendipity_displayTopExits($limit = 10, $use_links = true, $interval = 7) { serendipity_displayTopUrlList('exits', $limit, $use_links, $interval); } +/** + * Display HTML output data of a Exit/Referrer list + * + * @access public + * @see serendipity_displayTopExits() + * @see serendipity_displayTopReferrers() + * @param string Name of the DB table to show data from (exits|referrers) + * @param boolean Whether to use HTML links for URLs + * @param int Interval for which the top exits are aggregated + * @return + */ function serendipity_displayTopUrlList($list, $limit, $use_links = true, $interval = 7) { global $serendipity; @@ -598,6 +785,13 @@ function serendipity_displayTopUrlList($list, $limit, $use_links = true, $interv echo ""; } +/** + * Return either HTML or XHTML code for an ' attribute. + * + * @access public + * @param string The target to use (_blank, _parent, ...) + * @return string HTML string containig the valid markup for the target attribute. + */ function serendipity_xhtml_target($target) { global $serendipity; @@ -611,6 +805,14 @@ function serendipity_xhtml_target($target) { } } +/** + * Parse a URI portion to return which RSS Feed version was requested + * + * @access public + * @param string Name of the core URI part + * @param string File extension name of the URI + * @return string RSS feed type/version + */ function serendipity_discover_rss($name, $ext) { static $default = '2.0'; @@ -639,10 +841,28 @@ function serendipity_discover_rss($name, $ext) { return array($ver, $type); } +/** + * Check whether an input string contains "evil" characters used for HTTP Response Splitting + * + * @access public + * @param string String to check for evil characters + * @return boolean Return true on success, false on failure + */ function serendipity_isResponseClean($d) { return (strpos($d, "\r") === false && strpos($d, "\n") === false); } +/** + * Create a new Category + * + * @access public + * @param string The new category name + * @param string The new category description + * @param int The category owner + * @param string An icon representing the category + * @param int A possible parentid to a category + * @return int The new category's ID + */ function serendipity_addCategory($name, $desc, $authorid, $icon, $parentid) { global $serendipity; $query = "INSERT INTO {$serendipity['dbPrefix']}category @@ -670,6 +890,18 @@ function serendipity_addCategory($name, $desc, $authorid, $icon, $parentid) { return $cid; } +/** + * Update an existing category + * + * @access public + * @param int Category ID to update + * @param string The new category name + * @param string The new category description + * @param int The new category owner + * @param string The new category icon + * @param int The new category parent ID + * @return null + */ function serendipity_updateCategory($cid, $name, $desc, $authorid, $icon, $parentid) { global $serendipity; diff --git a/include/functions_calendars.inc.php b/include/functions_calendars.inc.php index edf3ade..e14cdee 100644 --- a/include/functions_calendars.inc.php +++ b/include/functions_calendars.inc.php @@ -2,7 +2,16 @@ # Copyright (c) 2003-2005, Jannis Hermanns (on behalf the Serendipity Developer Team) # All rights reserved. See LICENSE file for licensing details -// Gregorian to Jalali Convertor, by farsiweb.info +/** + * Gregorian to Jalali Convertor + * + * @author farsiweb.info + * @access public + * @param int year + * @param int month + * @param int day + * @return array converted time + */ function g2j($g_y, $g_m, $g_d){ $g_days_in_month = array(31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31); $j_days_in_month = array(31, 31, 31, 31, 31, 31, 30, 30, 30, 30, 30, 29); @@ -45,7 +54,16 @@ function g2j($g_y, $g_m, $g_d){ return array($jy, $jm, $jd, $j_all_days); } -// Gregorian to Jalali Convertor, by farsiweb.info +/** + * Gregorian to Jalali Convertor + * + * @author farsiweb.info + * @access public + * @param int year + * @param int month + * @param int day + * @return array converted time + */ function j2g($j_y, $j_m, $j_d){ $g_days_in_month = array(31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31); $j_days_in_month = array(31, 31, 31, 31, 31, 31, 30, 30, 30, 30, 30, 29); @@ -88,7 +106,15 @@ function j2g($j_y, $j_m, $j_d){ return array($gy, $gm, $gd); } -// Jalali UTF Calendar code by Omid Mottaghi +/** + * Format a string according to Jalali calendar + * + * @author Omid Mottaghi + * @access public + * @param string Formatting string + * @param int Timestamp to format + * @return string Formatted stamp + */ function jalali_strftime_utf($format, $timestamp) { $g_d=date('j', $timestamp); @@ -225,7 +251,15 @@ function jalali_strftime_utf($format, $timestamp) { return $output_str; } -// Jalali UTF Calendar code by Omid Mottaghi +/** + * Format a string according to Jalali calendar (UTF) + * + * @author Omid Mottaghi + * @access public + * @param string Formatting string + * @param int Timestamp to format + * @return + */ function jalali_date_utf($format, $timestamp) { $g_d=date('j', $timestamp); @@ -361,9 +395,21 @@ function jalali_date_utf($format, $timestamp) { return $output_str; } -// Jalali UTF Calendar code by Omid Mottaghi +/** + * Create a jalali timestamp from a gregorian timestamp + * + * @author Omid Mottaghi + * @access public + * @param int hour + * @param int minute + * @param int second + * @param int month + * @param int day + * @param int year + * @param int DST-Format? + * @return int returned timestamp + */ function jalali_mktime($hour=0, $min=0, $sec=0, $mon=1, $day=1, $year=1970, $is_dst=-1){ list($year, $mon, $day)=j2g($year, $mon, $day); return mktime($hour, $min, $sec, $mon, $day, $year, $is_dst); } -?> \ No newline at end of file diff --git a/include/functions_comments.inc.php b/include/functions_comments.inc.php index 0946fa5..5611c3d 100644 --- a/include/functions_comments.inc.php +++ b/include/functions_comments.inc.php @@ -2,6 +2,12 @@ # Copyright (c) 2003-2005, Jannis Hermanns (on behalf the Serendipity Developer Team) # All rights reserved. See LICENSE file for licensing details +/** + * Store the personal details of a commenting user in a cookie (or delete that cookie) + * + * @access public + * @return null + */ function serendipity_rememberComment() { global $serendipity; @@ -19,6 +25,13 @@ function serendipity_rememberComment() { } } +/** + * Store all options of an array within a permanent cookie + * + * @access public + * @param array input array + * @return null + */ function serendipity_rememberCommentDetails($details) { global $serendipity; @@ -27,6 +40,15 @@ function serendipity_rememberCommentDetails($details) { } } +/** + * Purge stored options from a permanent cookie + * + * LONG + * + * @access public + * @param array Array of key names that shall be deleted inside cookies + * @return null + */ function serendipity_forgetCommentDetails($keys) { global $serendipity; if (!$serendipity['COOKIE']) { @@ -38,6 +60,19 @@ function serendipity_forgetCommentDetails($keys) { } } +/** + * Display the Comment form for entries + * + * @access public + * @param int The EntryID to show the commentform for + * @param string The URL that acts as the target of the HTML Form + * @param array Array of existing comments to this entry + * @param array Array of personal details data (i.e. from Cookie or POST input) + * @param boolean Toggle whether to show extended options of the comment form + * @param boolean Toggle whether comments to this entry are allowed + * @param array The data of the entry that the comment is referring to + * @return null + */ function serendipity_displayCommentForm($id, $url = '', $comments = NULL, $data = NULL, $showToolbar = true, $moderate_comments = true, $entry = null) { global $serendipity; @@ -66,6 +101,16 @@ function serendipity_displayCommentForm($id, $url = '', $comments = NULL, $data serendipity_smarty_fetch('COMMENTFORM', 'commentform.tpl'); } +/** + * Fetch an array of comments to a specific entry id + * + * @access public + * @param int The Entry ID to fetch comments for + * @param int How many comments to fetch (empty: all) + * @param string How shall comments be ordered (ASC|DESC) + * @param boolean Shall non-approved comments be displayed? + * @return array The SQL result of comments + */ function serendipity_fetchComments($id, $limit = null, $order = '', $showAll = false) { global $serendipity; $and = ''; @@ -120,6 +165,18 @@ function serendipity_fetchComments($id, $limit = null, $order = '', $showAll = f return $comments; } +/** + * Create a HTML SELECT dropdown field which represents all hierarchical comments + * + * @access public + * @param int The entry ID to show comments for + * @param array The existing comments for this entry + * @param int The ID of the comment that is being referred to (last selection) + * @param int The parent ID of the last comment [for recursive usage] + * @param int The current nesting/hierarchy level [for recursive usage] + * @param string The HTML indention string that gets prepended to a comment [for recursive usage] + * @return string The HTML SELECT code + */ function serendipity_generateCommentList($id, $comments = NULL, $selected = 0, $parent = 0, $level = 0, $indent = '') { global $serendipity; @@ -145,6 +202,16 @@ function serendipity_generateCommentList($id, $comments = NULL, $selected = 0, $ return $retval; } +/** + * Print a list of comments to an entry + * + * @access public + * @param array The list of comments to display + * @param int The parentID of a comment to show. Can contain the constant for VIEWMODE_THREADED/LINEAR. [recursive usage] + * @param int The current nesting depth of a comment [recursive usage] + * @param string A string repesenting the actual comment (1.1.2.1) + * @return string The HTML construct of all comments + */ function serendipity_printComments($comments, $parentid = 0, $depth = 0, $trace = null) { global $serendipity; static $_smartyComments; @@ -216,6 +283,15 @@ function serendipity_printComments($comments, $parentid = 0, $depth = 0, $trace return serendipity_smarty_fetch('COMMENTS', 'comments.tpl'); } +/** + * Delete a specific comment + * + * @access public + * @param int The ID of the comment to delete + * @param int The ID of the entry the comment belongs to [safety] + * @param string The type of a comment (comments/trackback) + * @return boolean Return whether the action was successful) + */ function serendipity_deleteComment($id, $entry_id, $type='comments') { global $serendipity; @@ -249,6 +325,14 @@ function serendipity_deleteComment($id, $entry_id, $type='comments') { } } +/** + * Toggle whether an entry allows comments + * + * @access public + * @param int The ID of the entry where the switch shall be toggled + * @param string Whether the entry shall be opened or closed for comments + * @return null + */ function serendipity_allowCommentsToggle($entry_id, $switch = 'disable') { global $serendipity; @@ -268,6 +352,17 @@ function serendipity_allowCommentsToggle($entry_id, $switch = 'disable') { } } +/** + * Approve a comment + * + * LONG + * + * @access public + * @param int The ID of the comment to approve + * @param int The ID of the entry a comment belongs to + * @param boolean Whether to force approving a comment despite of its current status + * @return boolean Success or failure + */ function serendipity_approveComment($cid, $entry_id, $force = false) { global $serendipity; @@ -309,6 +404,16 @@ function serendipity_approveComment($cid, $entry_id, $force = false) { return true; } +/** + * Save a comment made by a visitor + * + * @access public + * @param int The ID of an entry + * @param array An array that holds the input data from the visitor + * @param string The type of a comment (normal/trackback) + * @param string Where did a comment come from? (internal|trackback|plugin) + * @return boolean Returns true if the comment could be added + */ function serendipity_saveComment($id, $commentInfo, $type = 'NORMAL', $source = 'internal') { global $serendipity; @@ -371,6 +476,18 @@ function serendipity_saveComment($id, $commentInfo, $type = 'NORMAL', $source = } } +/** + * Send a mail to all subscribers of an entry about a new comment + * + * @access public + * @param int The ID of the entry where a new comment has been made + * @param string The name of the latest poster to an entry + * @param string The email addre ssof the latest poster to an entry + * @param string The title of the entry + * @param string The mail address used to send emails from + * @param int The ID of the comment that has been made + * @return null + */ function serendipity_mailSubscribers($entry_id, $poster, $posterMail, $title, $fromEmail = 'none@example.com', $cid = null) { global $serendipity; @@ -425,6 +542,14 @@ function serendipity_mailSubscribers($entry_id, $poster, $posterMail, $title, $f } } +/** + * Cancel a subscription to an entry + * + * @access public + * @param string E-Mail address to cancel subscription + * @param int The entry ID to unsubscribe from + * @return int Return number of unsubscriptions + */ function serendipity_cancelSubscription($email, $entry_id) { global $serendipity; $sql = "UPDATE {$serendipity['dbPrefix']}comments @@ -436,6 +561,21 @@ function serendipity_cancelSubscription($email, $entry_id) { return serendipity_db_affected_rows(); } +/** + * Send a comment notice to the admin/author of an entry + * + * @access public + * @param int ID of the comment that has been made + * @param string Author's email address to send the mail to + * @param string The name of the sender + * @param string The URL of the sender + * @param int The ID of the entry that has been commented + * @param string The title of the entry that has been commented + * @param string The text of the comment + * @param string The type of the comment (normal|trackback) + * @param boolean Toggle Whether comments to this entry need approval + * @return boolean Return success of sending the mails + */ function serendipity_sendComment($comment_id, $to, $fromName, $fromEmail, $fromUrl, $id, $title, $comment, $type = 'NORMAL', $moderate_comment = false) { global $serendipity; diff --git a/include/functions_config.inc.php b/include/functions_config.inc.php index f4dffb3..3b1306e 100644 --- a/include/functions_config.inc.php +++ b/include/functions_config.inc.php @@ -2,6 +2,15 @@ # Copyright (c) 2003-2005, Jannis Hermanns (on behalf the Serendipity Developer Team) # All rights reserved. See LICENSE file for licensing details +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_addAuthor($username, $password, $realname, $email, $userlevel=0) { global $serendipity; $password = md5($password); @@ -25,6 +34,15 @@ function serendipity_addAuthor($username, $password, $realname, $email, $userlev return $cid; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_deleteAuthor($authorid) { global $serendipity; @@ -38,11 +56,29 @@ function serendipity_deleteAuthor($authorid) { return true; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_remove_config_var($name, $authorid = 0) { global $serendipity; serendipity_db_query("DELETE FROM {$serendipity['dbPrefix']}config where name='" . serendipity_db_escape_string($name) . "' AND authorid = " . (int)$authorid); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_set_config_var($name, $val, $authorid = 0) { global $serendipity; @@ -62,6 +98,15 @@ function serendipity_set_config_var($name, $val, $authorid = 0) { } } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_get_config_var($name, $defval = false, $empty = false) { global $serendipity; if (isset($serendipity[$name])) { @@ -75,6 +120,15 @@ function serendipity_get_config_var($name, $defval = false, $empty = false) { } } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_get_user_config_var($name, $authorid, $default = '') { global $serendipity; @@ -92,6 +146,15 @@ function serendipity_get_user_config_var($name, $authorid, $default = '') { } } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_get_user_var($name, $authorid, $default) { global $serendipity; @@ -104,6 +167,15 @@ function serendipity_get_user_var($name, $authorid, $default) { } } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_set_user_var($name, $val, $authorid, $copy_to_s9y = true) { global $serendipity; @@ -148,6 +220,15 @@ function serendipity_set_user_var($name, $val, $authorid, $copy_to_s9y = true) { } } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_getTemplateFile($file, $key = 'serendipityHTTPPath') { global $serendipity; @@ -170,6 +251,15 @@ function serendipity_getTemplateFile($file, $key = 'serendipityHTTPPath') { return false; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_load_configuration($author = null) { global $serendipity; @@ -193,12 +283,30 @@ function serendipity_load_configuration($author = null) { } } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_logout() { $_SESSION['serendipityAuthedUser'] = false; @session_destroy(); serendipity_deleteCookie('author_information'); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_login($use_external = true) { global $serendipity; @@ -231,6 +339,15 @@ function serendipity_login($use_external = true) { } } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_userLoggedIn() { if ($_SESSION['serendipityAuthedUser'] === true && IS_installed) { return true; @@ -239,6 +356,15 @@ function serendipity_userLoggedIn() { } } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_restoreVar(&$source, &$target) { global $serendipity; @@ -250,6 +376,15 @@ function serendipity_restoreVar(&$source, &$target) { return false; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_JSsetCookie($name, $value) { $name = str_replace('"', '\"', $name); $value = str_replace('"', '\"', $value); @@ -257,6 +392,15 @@ function serendipity_JSsetCookie($name, $value) { echo '' . "\n"; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_setCookie($name,$value) { global $serendipity; @@ -265,6 +409,15 @@ function serendipity_setCookie($name,$value) { $serendipity['COOKIE'][$name] = $value; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_deleteCookie($name) { global $serendipity; @@ -273,6 +426,15 @@ function serendipity_deleteCookie($name) { unset($serendipity['COOKIE'][$name]); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_authenticate_author($username = '', $password = '', $is_md5 = false, $use_external = true) { global $serendipity; @@ -321,6 +483,15 @@ function serendipity_authenticate_author($username = '', $password = '', $is_md5 return false; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_is_iframe() { global $serendipity; @@ -366,6 +537,15 @@ function serendipity_is_iframe() { return false; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_iframe(&$entry, $mode = null) { global $serendipity; @@ -409,6 +589,15 @@ function serendipity_iframe(&$entry, $mode = null) { return false; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_iframe_create($mode, &$entry) { global $serendipity; @@ -435,6 +624,15 @@ function serendipity_iframe_create($mode, &$entry) { . '

'; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_probeInstallation($item) { global $serendipity; $res = NULL; @@ -469,12 +667,30 @@ function serendipity_probeInstallation($item) { return $res; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_header($header) { if (!headers_sent()) { header($header); } } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /* TODO: This previously was handled inside a plugin with an event hook, but caching the event plugins that early in sequence created trouble with plugins not @@ -519,6 +735,15 @@ function serendipity_getSessionLanguage() { return $lang; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function &serendipity_getPermissions($authorid) { global $serendipity; @@ -540,6 +765,15 @@ function &serendipity_getPermissions($authorid) { return $perm; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_getPermissionNames() { return array( 'personalConfiguration' @@ -615,6 +849,15 @@ function serendipity_getPermissionNames() { ); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_checkPermission($permName, $authorid = null, $returnMyGroups = false) { global $serendipity; @@ -674,6 +917,15 @@ function serendipity_checkPermission($permName, $authorid = null, $returnMyGroup return false; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_updateGroups($groups, $authorid, $apply_acl = true) { global $serendipity; @@ -689,6 +941,15 @@ function serendipity_updateGroups($groups, $authorid, $apply_acl = true) { return true; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function &serendipity_getAllGroups($apply_ACL_user = false) { global $serendipity; @@ -720,6 +981,15 @@ function &serendipity_getAllGroups($apply_ACL_user = false) { return $groups; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function &serendipity_fetchGroup($groupid) { global $serendipity; @@ -748,7 +1018,15 @@ function &serendipity_fetchGroup($groupid) { return $conf; } - +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function &serendipity_getGroups($authorid, $sequence = false) { global $serendipity; @@ -775,6 +1053,15 @@ function &serendipity_getGroups($authorid, $sequence = false) { return $groups; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function &serendipity_getGroupUsers($groupid) { global $serendipity; @@ -790,6 +1077,15 @@ function &serendipity_getGroupUsers($groupid) { return $groups; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_deleteGroup($groupid) { global $serendipity; @@ -811,6 +1107,15 @@ function serendipity_deleteGroup($groupid) { return true; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_addGroup($name) { global $serendipity; @@ -820,6 +1125,15 @@ function serendipity_addGroup($name) { return $gid; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function &serendipity_getDBPermissionNames() { global $serendipity; @@ -828,6 +1142,15 @@ function &serendipity_getDBPermissionNames() { return $config; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function &serendipity_getAllPermissionNames() { global $serendipity; @@ -843,6 +1166,15 @@ function &serendipity_getAllPermissionNames() { return $perms; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_intersectGroup($checkuser = null, $myself = null) { global $serendipity; @@ -862,6 +1194,15 @@ function serendipity_intersectGroup($checkuser = null, $myself = null) { return false; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_updateGroupConfig($groupid, &$perms, &$values) { global $serendipity; @@ -925,6 +1266,15 @@ function serendipity_updateGroupConfig($groupid, &$perms, &$values) { return true; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_addDefaultGroup($name, $level) { global $serendipity; @@ -956,6 +1306,15 @@ function serendipity_addDefaultGroup($name, $level) { return true; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_ACLGrant($artifact_id, $artifact_type, $artifact_mode, $groups) { global $serendipity; @@ -988,6 +1347,15 @@ function serendipity_ACLGrant($artifact_id, $artifact_type, $artifact_mode, $gro return true; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_ACLGet($artifact_id, $artifact_type, $artifact_mode) { global $serendipity; @@ -1009,6 +1377,15 @@ function serendipity_ACLGet($artifact_id, $artifact_type, $artifact_mode) { return $acl; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_ACLCheck($authorid, $artifact_id, $artifact_type, $artifact_mode) { global $serendipity; @@ -1048,6 +1425,15 @@ function serendipity_ACLCheck($authorid, $artifact_id, $artifact_type, $artifact return false; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_ACL_SQL(&$cond, $append_category = false) { global $serendipity; @@ -1103,6 +1489,15 @@ function serendipity_ACL_SQL(&$cond, $append_category = false) { return false; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_checkXSRF() { global $serendipity; @@ -1144,6 +1539,15 @@ function serendipity_checkXSRF() { return false; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_reportXSRF($type = 0, $reset = true, $use_config = false) { global $serendipity; @@ -1163,6 +1567,15 @@ function serendipity_reportXSRF($type = 0, $reset = true, $use_config = false) { return $string; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_checkFormToken() { global $serendipity; @@ -1187,6 +1600,15 @@ function serendipity_checkFormToken() { return true; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_setFormToken($type = 'form') { global $serendipity; diff --git a/include/functions_entries.inc.php b/include/functions_entries.inc.php index 081d38e..dd20ed6 100644 --- a/include/functions_entries.inc.php +++ b/include/functions_entries.inc.php @@ -2,6 +2,15 @@ # Copyright (c) 2003-2005, Jannis Hermanns (on behalf the Serendipity Developer Team) # All rights reserved. See LICENSE file for licensing details +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_deleteCategory($category_range, $admin_category) { global $serendipity; @@ -14,6 +23,15 @@ function serendipity_deleteCategory($category_range, $admin_category) { return serendipity_db_query("DELETE FROM {$serendipity['dbPrefix']}category WHERE category_left BETWEEN {$category_range} {$admin_category}"); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_fetchCategoryRange($categoryid) { global $serendipity; @@ -25,6 +43,15 @@ function serendipity_fetchCategoryRange($categoryid) { return array('category_left' => $res[0]['category_left'], 'category_right' => $res[0]['category_right']); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_getMultiCategoriesSQL($cats) { global $serendipity; @@ -41,6 +68,15 @@ function serendipity_getMultiCategoriesSQL($cats) { return implode(' OR ', $cat_sql_array); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_fetchCategoryInfo($categoryid, $categoryname = '') { global $serendipity; @@ -73,6 +109,15 @@ function serendipity_fetchCategoryInfo($categoryid, $categoryname = '') { } } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_fetchEntryCategories($entryid) { global $serendipity; @@ -98,6 +143,15 @@ function serendipity_fetchEntryCategories($entryid) { } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /** * Give it a range in YYYYMMDD format to gather the desired entries * (For february 2002 you would pass 200202 for all entries withing @@ -292,6 +346,15 @@ function serendipity_fetchEntries($range = null, $full = true, $limit = '', $fet return $ret; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /** * Attach special entry data to entry */ @@ -330,6 +393,15 @@ function serendipity_fetchEntryData(&$ret) { } } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /** * Fetches a specific entry **/ @@ -387,6 +459,15 @@ function serendipity_fetchEntry($key, $val, $full = true, $fetchDrafts = 'false' return $ret; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_fetchEntryProperties($id) { global $serendipity; @@ -406,6 +487,15 @@ function serendipity_fetchEntryProperties($id) { return $property; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /** * Fetches a users categories **/ @@ -488,6 +578,15 @@ function serendipity_fetchCategories($authorid = null, $name = null, $order = nu return serendipity_db_query($querystring); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_rebuildCategoryTree($parent = 0, $left = 0) { // Based on http://www.sitepoint.com/article/hierarchical-data-database/1 global $serendipity; @@ -506,6 +605,15 @@ function serendipity_rebuildCategoryTree($parent = 0, $left = 0) { return $right + 1; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /** * Give it a raw searchstring, it'll search **/ @@ -590,6 +698,15 @@ function serendipity_searchEntries($term, $limit = '') { return $search; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_printEntryFooter() { global $serendipity; @@ -648,19 +765,30 @@ function serendipity_getTotalEntries() { return 0; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /** * Prints the entries you fetched with serendipity_fetchEntries/searchEntries in HTML. **/ -function serendipity_printEntries($entries, $extended = 0, $preview = false) { +function serendipity_printEntries($entries, $extended = 0, $preview = false, $smarty_block = 'ENTRIES', $smarty_fetch = true, $use_hooks = true, $use_footer = true) { global $serendipity; - $addData = array('extended' => $extended, 'preview' => $preview); - serendipity_plugin_api::hook_event('entry_display', $entries, $addData); + if ($use_hooks) { + $addData = array('extended' => $extended, 'preview' => $preview); + serendipity_plugin_api::hook_event('entry_display', $entries, $addData); - if (isset($entries['clean_page']) && $entries['clean_page'] === true) { - $serendipity['smarty']->assign('plugin_clean_page', true); - serendipity_smarty_fetch('ENTRIES', 'entries.tpl', true); - return; // no display of this item + if (isset($entries['clean_page']) && $entries['clean_page'] === true) { + $serendipity['smarty']->assign('plugin_clean_page', true); + serendipity_smarty_fetch($smarty_block, 'entries.tpl', true); + return; // no display of this item + } } // We shouldn't return here, because we want Smarty to handle the output @@ -797,7 +925,8 @@ function serendipity_printEntries($entries, $extended = 0, $preview = false) { if (!isset($serendipity['GET']['id']) && (!isset($serendipity['hidefooter']) || $serendipity['hidefooter'] == false) && - ($num_entries <= $serendipity['fetchLimit'])) { + ($num_entries <= $serendipity['fetchLimit']) && + $use_footer) { serendipity_printEntryFooter(); } @@ -805,13 +934,22 @@ function serendipity_printEntries($entries, $extended = 0, $preview = false) { unset($entries, $dategroup); if (isset($serendipity['short_archives']) && $serendipity['short_archives']) { - serendipity_smarty_fetch('ENTRIES', 'entries_summary.tpl', true); - } else { - serendipity_smarty_fetch('ENTRIES', 'entries.tpl', true); + serendipity_smarty_fetch($smarty_block, 'entries_summary.tpl', true); + } elseif ($smarty_fetch == true) { + serendipity_smarty_fetch($smarty_block, 'entries.tpl', true); } } // end function serendipity_printEntries +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /** /** * purge a statically pregenerated entry @@ -840,6 +978,15 @@ function serendipity_purgeEntry($id, $timestamp = null) { @unlink("{$serendipity['serendipityPath']}/index.html"); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /** * Inserts a new entry into the database or updates an existing **/ @@ -973,6 +1120,15 @@ function serendipity_updertEntry($entry) { return (int)$entry['id']; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /** * Deletes an entry and everything that belongs to it (comments, etc...) from * the database @@ -1003,6 +1159,15 @@ function serendipity_deleteEntry($id) { serendipity_db_query("DELETE FROM {$serendipity['dbPrefix']}permalinks WHERE entry_id='$id'"); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /** * Print a list of categories * @@ -1070,6 +1235,15 @@ function serendipity_generateCategoryList($cats, $select = array(0), $type = 0, return $ret; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_updateEntryCategories($postid, $categories) { global $serendipity; @@ -1090,6 +1264,15 @@ function serendipity_updateEntryCategories($postid, $categories) { } } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_printArchives() { global $serendipity; diff --git a/include/functions_entries_admin.inc.php b/include/functions_entries_admin.inc.php index 2695d18..954ab56 100644 --- a/include/functions_entries_admin.inc.php +++ b/include/functions_entries_admin.inc.php @@ -4,6 +4,15 @@ include_once(S9Y_INCLUDE_PATH . "include/functions_trackbacks.inc.php"); +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /** * Prints a form to enter new diary entries **/ diff --git a/include/functions_images.inc.php b/include/functions_images.inc.php index 36e36c9..cc9399e 100644 --- a/include/functions_images.inc.php +++ b/include/functions_images.inc.php @@ -2,6 +2,15 @@ # Copyright (c) 2003-2005, Jannis Hermanns (on behalf the Serendipity Developer Team) # All rights reserved. See LICENSE file for licensing details +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_isActiveFile($file) { if (preg_match('@^\.@', $file)) { return true; @@ -10,6 +19,15 @@ function serendipity_isActiveFile($file) { return preg_match('@\.(php[345]?|[psj]html?|aspx?|cgi|jsp|py|pl)$@i', $file); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /** * Get a list of images **/ @@ -67,12 +85,30 @@ function serendipity_fetchImagesFromDatabase($start=0, $limit=0, &$total, $order return $rs; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_fetchImageFromDatabase($id) { global $serendipity; $rs = serendipity_db_query("SELECT * FROM {$serendipity['dbPrefix']}images WHERE id = ". (int)$id, true, 'assoc'); return $rs; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_updateImageInDatabase($updates, $id) { global $serendipity; @@ -92,6 +128,15 @@ function serendipity_updateImageInDatabase($updates, $id) { return $i; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_deleteImage($id) { global $serendipity; $file = serendipity_fetchImageFromDatabase($id); @@ -129,6 +174,15 @@ function serendipity_deleteImage($id) { } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /** * Get a list of images **/ @@ -160,6 +214,15 @@ function serendipity_fetchImages($group = false, $start = 0, $end = 20, $images return $images; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_insertHotlinkedImageInDatabase($filename, $url, $authorid = 0, $time = NULL, $tempfile = NULL) { global $serendipity; @@ -227,6 +290,15 @@ function serendipity_insertHotlinkedImageInDatabase($filename, $url, $authorid = return 0; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_insertImageInDatabase($filename, $directory, $authorid = 0, $time = NULL) { global $serendipity; @@ -299,6 +371,15 @@ function serendipity_insertImageInDatabase($filename, $directory, $authorid = 0, } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /** * Generate a thumbnail **/ @@ -346,6 +427,15 @@ function serendipity_makeThumbnail($file, $directory = '', $size = false) { return $r; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /** * Scale an image (ignoring proportions) **/ @@ -376,6 +466,15 @@ function serendipity_scaleImg($id, $width, $height) { return true; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /** * Rotate an Image **/ @@ -426,6 +525,15 @@ function serendipity_rotateImg($id, $degrees) { } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /** * Creates thumbnails for all images in the upload dir **/ @@ -489,6 +597,15 @@ function serendipity_generateThumbs() { return $i; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_guessMime($extension) { $mime = ''; switch (strtolower($extension)) { @@ -684,6 +801,15 @@ function serendipity_guessMime($extension) { return $mime; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /** * Creates thumbnails for all images in the upload dir **/ @@ -757,6 +883,15 @@ function serendipity_syncThumbs() { return $i; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_functions_gd($infilename) { if (!function_exists('imagecopyresampled')) { return false; @@ -803,6 +938,15 @@ function serendipity_functions_gd($infilename) { return $func; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_rotate_image_gd($infilename, $outfilename, $degrees) { $func = serendipity_functions_gd($infilename); @@ -825,6 +969,15 @@ function serendipity_rotate_image_gd($infilename, $outfilename, $degrees) } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_resize_image_gd($infilename, $outfilename, $newwidth, $newheight=null) { $func = serendipity_functions_gd($infilename); @@ -858,6 +1011,15 @@ function serendipity_resize_image_gd($infilename, $outfilename, $newwidth, $newh return array($newwidth, $newheight); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_calculate_aspect_size($width, $height, $newwidth) { // calculate aspect ratio @@ -884,6 +1046,15 @@ function serendipity_calculate_aspect_size($width, $height, $newwidth) { return array($newwidth, $newheight); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_displayImageList($page = 0, $lineBreak = NULL, $manage = false, $url = NULL, $show_upload = false, $limit_path = NULL) { global $serendipity; $sort_row_interval = array(8, 16, 50, 100); @@ -1123,6 +1294,15 @@ if ( !$manage ) { } } // End serendipity_displayImageList() +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_isImage(&$file, $strict = false) { global $serendipity; @@ -1140,6 +1320,15 @@ function serendipity_isImage(&$file, $strict = false) { return (0 === strpos(strtolower($file['displaymime']), 'image/')); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_killPath($basedir, $directory = '', $forceDelete = false) { static $n = "
\n"; static $serious = true; @@ -1212,6 +1401,15 @@ function serendipity_killPath($basedir, $directory = '', $forceDelete = false) { } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_traversePath($basedir, $dir='', $onlyDirs=true, $pattern = NULL, $depth = 1, $max_depth = null) { @@ -1242,7 +1440,15 @@ function serendipity_traversePath($basedir, $dir='', $onlyDirs=true, $pattern = return $files; } - +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_deletePath($dir) { $d = dir($dir); if ($d) { @@ -1263,6 +1469,15 @@ function serendipity_deletePath($dir) { } } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_uploadSecure($var, $strip_paths = true, $append_slash = false) { $var = preg_replace('@[^0-9a-z\._/-]@i', '', $var); if ($strip_paths) { @@ -1280,6 +1495,15 @@ function serendipity_uploadSecure($var, $strip_paths = true, $append_slash = fal return $var; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_getimagesize($file, $ft_mime = '', $suf = '') { if (empty($ft_mime) && !empty($suf)) { $ft_mime = serendipity_guessMime($suf); @@ -1313,6 +1537,15 @@ function serendipity_getimagesize($file, $ft_mime = '', $suf = '') { return $fdim; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_getImageFields() { return array( 'date' => SORT_ORDER_DATE, @@ -1325,7 +1558,15 @@ function serendipity_getImageFields() { ); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_escapeshellarg($string) { return escapeshellarg(str_replace('%', '', $string)); } -?> diff --git a/include/functions_installer.inc.php b/include/functions_installer.inc.php index 97e2f7e..6554674 100644 --- a/include/functions_installer.inc.php +++ b/include/functions_installer.inc.php @@ -3,10 +3,28 @@ # All rights reserved. See LICENSE file for licensing details +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_ini_bool($var) { return ($var === 'on' || $var == '1'); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_ini_bytesize($val) { if ( $val == '' ) return 0; @@ -25,6 +43,15 @@ function serendipity_ini_bytesize($val) { } } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_updateLocalConfig($dbName, $dbPrefix, $dbHost, $dbUser, $dbPass, $dbType, $dbPersistent, $privateVariables = null) { global $serendipity; umask(0000); @@ -89,6 +116,15 @@ function serendipity_updateLocalConfig($dbName, $dbPrefix, $dbHost, $dbUser, $db return true; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /** * Creates the needed tables - beware, they will be empty and need to be stuffed with * default templates and such... @@ -103,6 +139,15 @@ function serendipity_installDatabase() { } } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_query_default($optname, $default, $usertemplate = false, $type = 'string') { global $serendipity; @@ -189,6 +234,15 @@ function serendipity_query_default($optname, $default, $usertemplate = false, $t } } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_parseTemplate($filename, $areas = null, $onlyFlags=null) { global $serendipity; @@ -266,6 +320,15 @@ function serendipity_parseTemplate($filename, $areas = null, $onlyFlags=null) { return $config; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_replaceEmbeddedConfigVars ($s) { return str_replace( array( @@ -279,6 +342,15 @@ function serendipity_replaceEmbeddedConfigVars ($s) { $s); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_guessInput($type, $name, $value='', $default='') { global $serendipity; @@ -338,6 +410,15 @@ function serendipity_guessInput($type, $name, $value='', $default='') { } } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_printConfigTemplate($config, $from = false, $noForm = false, $folded = true, $allowToggle = true) { global $serendipity; if (!isset($serendipity['XHTML11'])) { @@ -495,6 +576,15 @@ function showConfigAll(count) { } } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_parse_sql_tables($filename) { $in_table = 0; $queries = array(); @@ -526,6 +616,15 @@ function serendipity_parse_sql_tables($filename) { return $queries; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_checkInstallation() { global $serendipity, $umask; @@ -593,6 +692,15 @@ function serendipity_checkInstallation() { return (count($errs) > 0 ? $errs : ''); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_installFiles($serendipity_core = '') { global $serendipity; @@ -746,6 +854,15 @@ function serendipity_installFiles($serendipity_core = '') { } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /* Takes the item data from a config var, and checks the flags against the current area */ function serendipity_checkConfigItemFlags(&$item, $area) { @@ -764,6 +881,15 @@ function serendipity_checkConfigItemFlags(&$item, $area) { return true; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_updateConfiguration() { global $serendipity, $umask; @@ -831,6 +957,15 @@ function serendipity_updateConfiguration() { } } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_httpCoreDir() { if (!empty($_SERVER['SCRIPT_FILENAME']) && substr(php_sapi_name(), 0, 3) != 'cgi') { return dirname($_SERVER['SCRIPT_FILENAME']) . '/'; @@ -839,6 +974,15 @@ function serendipity_httpCoreDir() { return $_SERVER['DOCUMENT_ROOT'] . dirname($_SERVER['PHP_SELF']) . '/'; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_removeFiles($files = null) { global $serendipity, $errors; @@ -881,12 +1025,30 @@ function serendipity_removeFiles($files = null) { } } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_getRealDir($file) { $dir = str_replace( "\\", "/", dirname($file)); $base = preg_replace('@/include$@', '', $dir) . '/'; return $base; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_check_rewrite($default) { global $serendipity; @@ -943,6 +1105,15 @@ function serendipity_check_rewrite($default) { } } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_removeObsoleteVars() { global $serendipity; @@ -957,4 +1128,3 @@ global $serendipity; } } -?> diff --git a/include/functions_permalinks.inc.php b/include/functions_permalinks.inc.php index 7d2fb68..32d16dd 100644 --- a/include/functions_permalinks.inc.php +++ b/include/functions_permalinks.inc.php @@ -2,6 +2,15 @@ # Copyright (c) 2003-2005, Jannis Hermanns (on behalf the Serendipity Developer Team) # All rights reserved. See LICENSE file for licensing details +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_makeFilename($str, $stripDots = false) { static $from = array( ' ', @@ -129,6 +138,15 @@ function serendipity_makeFilename($str, $stripDots = false) { return $str; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_initPermalinks() { global $serendipity; @@ -225,6 +243,15 @@ function serendipity_initPermalinks() { return true; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function &serendipity_permalinkPatterns($return = false) { global $serendipity; @@ -258,6 +285,15 @@ function &serendipity_permalinkPatterns($return = false) { } } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_searchPermalink($struct, $url, $default, $type = 'entry') { global $serendipity; @@ -283,6 +319,15 @@ function serendipity_searchPermalink($struct, $url, $default, $type = 'entry') { return $default; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_getPermalink(&$data, $type = 'entry') { switch($type) { case 'entry': @@ -307,6 +352,15 @@ function serendipity_getPermalink(&$data, $type = 'entry') { return false; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_updatePermalink(&$data, $type = 'entry') { global $serendipity; @@ -321,6 +375,15 @@ function serendipity_updatePermalink(&$data, $type = 'entry') { serendipity_db_escape_string($type)))); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_insertPermalink(&$data, $type = 'entry') { global $serendipity; @@ -349,6 +412,15 @@ function serendipity_insertPermalink(&$data, $type = 'entry') { serendipity_db_escape_string($type)))); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_buildPermalinks() { global $serendipity; @@ -383,12 +455,30 @@ function serendipity_buildPermalinks() { } } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /* Uses logic to figure out how the URI should look, based on current rewrite rule */ function serendipity_rewriteURL($path, $key='baseURL', $forceNone = false) { global $serendipity; return $serendipity[$key] . ($serendipity['rewrite'] == 'none' || ($serendipity['rewrite'] != 'none' && $forceNone) ? $serendipity['indexFile'] . '?/' : '') . $path; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_makePermalink($format, $data, $type = 'entry') { global $serendipity; static $entryKeys = array('%id%', '%title%', '%day%', '%month%', '%year%'); @@ -445,6 +535,15 @@ function serendipity_makePermalink($format, $data, $type = 'entry') { return false; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_makePermalinkRegex($format, $type = 'entry') { static $entryKeys = array('%id%', '%title%', '%day%', '%month%', '%year%'); static $entryRegexValues = array('([0-9]+)', '[0-9a-z\.\_!;,\+\-]+', '[0-9]{1,2}', '[0-9]{1,2}', '[0-9]{4}'); @@ -470,6 +569,15 @@ function serendipity_makePermalinkRegex($format, $type = 'entry') { } } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_archiveURL($id, $title, $key = 'baseURL', $checkrewrite = true, $entryData = null) { global $serendipity; $path = serendipity_makePermalink($serendipity['permalinkStructure'], array('id'=> $id, 'title' => $title, 'entry' => $entryData)); @@ -479,6 +587,15 @@ function serendipity_archiveURL($id, $title, $key = 'baseURL', $checkrewrite = t return $path; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_authorURL(&$data, $key = 'baseURL', $checkrewrite = true) { global $serendipity; $path = serendipity_makePermalink($serendipity['permalinkAuthorStructure'], $data, 'author'); @@ -488,6 +605,15 @@ function serendipity_authorURL(&$data, $key = 'baseURL', $checkrewrite = true) { return $path; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_categoryURL(&$data, $key = 'baseURL', $checkrewrite = true) { global $serendipity; $path = serendipity_makePermalink($serendipity['permalinkCategoryStructure'], $data, 'category'); @@ -497,6 +623,15 @@ function serendipity_categoryURL(&$data, $key = 'baseURL', $checkrewrite = true) return $path; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_feedCategoryURL(&$data, $key = 'baseURL', $checkrewrite = true) { global $serendipity; $path = serendipity_makePermalink($serendipity['permalinkFeedCategoryStructure'], $data, 'category'); @@ -506,6 +641,15 @@ function serendipity_feedCategoryURL(&$data, $key = 'baseURL', $checkrewrite = t return $path; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_feedAuthorURL(&$data, $key = 'baseURL', $checkrewrite = true) { global $serendipity; $path = serendipity_makePermalink($serendipity['permalinkFeedAuthorStructure'], $data, 'author'); @@ -515,10 +659,28 @@ function serendipity_feedAuthorURL(&$data, $key = 'baseURL', $checkrewrite = tru return $path; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_archiveDateUrl($range, $summary=false, $key='baseURL') { return serendipity_rewriteURL(PATH_ARCHIVES . '/' . $range . ($summary ? '/summary' : '') . '.html', $key); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_currentURL() { global $serendipity; @@ -554,6 +716,15 @@ function serendipity_currentURL() { return $url; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_getUriArguments($uri, $wildcard = false) { global $serendipity; diff --git a/include/functions_rss.inc.php b/include/functions_rss.inc.php index a8c74bf..f73d5e7 100644 --- a/include/functions_rss.inc.php +++ b/include/functions_rss.inc.php @@ -2,6 +2,15 @@ # Copyright (c) 2003-2005, Jannis Hermanns (on behalf the Serendipity Developer Team) # All rights reserved. See LICENSE file for licensing details +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_printEntries_rss(&$entries, $version, $comments = false, $fullFeed = false, $showMail = true) { global $serendipity; diff --git a/include/functions_smarty.inc.php b/include/functions_smarty.inc.php index c2610de..33d204a 100644 --- a/include/functions_smarty.inc.php +++ b/include/functions_smarty.inc.php @@ -2,6 +2,15 @@ # Copyright (c) 2003-2005, Jannis Hermanns (on behalf the Serendipity Developer Team) # All rights reserved. See LICENSE file for licensing details +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_fetchTrackbacks($id, $limit = null, $showAll = false) { global $serendipity; @@ -23,6 +32,15 @@ function serendipity_fetchTrackbacks($id, $limit = null, $showAll = false) { return $comments; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_printTrackbacks($trackbacks) { global $serendipity; @@ -31,6 +49,15 @@ function serendipity_printTrackbacks($trackbacks) { return serendipity_smarty_fetch('TRACKBACKS', 'trackbacks.tpl'); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function &serendipity_smarty_fetch($block, $file, $echo = false) { global $serendipity; @@ -40,10 +67,28 @@ function &serendipity_smarty_fetch($block, $file, $echo = false) { return $output; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_emptyPrefix($string, $prefix = ': ') { return (!empty($string) ? $prefix . htmlspecialchars($string) : ''); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_smarty_showPlugin($params, &$smarty) { global $serendipity; @@ -63,6 +108,15 @@ function serendipity_smarty_showPlugin($params, &$smarty) { return serendipity_plugin_api::generate_plugins($params['side'], null, $params['negate'], $params['class'], $params['id']); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_smarty_hookPlugin($params, &$smarty) { global $serendipity; static $hookable = array('frontend_header', @@ -93,6 +147,15 @@ function serendipity_smarty_hookPlugin($params, &$smarty) { } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_smarty_printSidebar($params, &$smarty) { if ( !isset($params['side']) ) { $smarty->trigger_error(__FUNCTION__ .": missing 'side' parameter"); @@ -101,6 +164,15 @@ function serendipity_smarty_printSidebar($params, &$smarty) { return serendipity_plugin_api::generate_plugins($params['side']); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_smarty_getFile($params, &$smarty) { if ( !isset($params['file']) ) { $smarty->trigger_error(__FUNCTION__ .": missing 'file' parameter"); @@ -109,6 +181,15 @@ function serendipity_smarty_getFile($params, &$smarty) { return serendipity_getTemplateFile($params['file']); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_smarty_rss_getguid($params, &$smarty) { if ( !isset($params['entry']) ) { $smarty->trigger_error(__FUNCTION__ .": missing 'entry' parameter"); @@ -122,6 +203,15 @@ function serendipity_smarty_rss_getguid($params, &$smarty) { return serendipity_rss_getguid($params['entry'], $params['is_comments']); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_smarty_formatTime($timestamp, $format, $useOffset = true) { if (defined($format)) { return serendipity_formatTime(constant($format), $timestamp, $useOffset); @@ -130,6 +220,15 @@ function serendipity_smarty_formatTime($timestamp, $format, $useOffset = true) { } } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function &serendipity_smarty_printComments($params, &$smarty) { global $serendipity; @@ -160,6 +259,15 @@ function &serendipity_smarty_printComments($params, &$smarty) { return $out; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_smarty_printTrackbacks($params, &$smarty) { if ( !isset($params['entry']) ) { $smarty->trigger_error(__FUNCTION__ .": missing 'entry' parameter"); @@ -169,11 +277,29 @@ function serendipity_smarty_printTrackbacks($params, &$smarty) { return serendipity_printTrackbacks(serendipity_fetchTrackbacks($params['entry'])); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function &serendipity_replaceSmartyVars(&$tpl_source, &$smarty) { $tpl_source = str_replace('$CONST.', '$smarty.const.', $tpl_source); return $tpl_source; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_smarty_init() { global $serendipity; @@ -281,6 +407,15 @@ function serendipity_smarty_init() { return true; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /* Nukes all Smarty compiled templates and cache */ function serendipity_smarty_purge() { global $serendipity; @@ -299,6 +434,15 @@ function serendipity_smarty_purge() { } } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /* Function can be called from foreign applications. ob_start() needs to have been called before, and will be parsed into Smarty here */ function serendipity_smarty_shutdown($serendipity_directory = '') { diff --git a/include/functions_trackbacks.inc.php b/include/functions_trackbacks.inc.php index af5e51c..ec57532 100644 --- a/include/functions_trackbacks.inc.php +++ b/include/functions_trackbacks.inc.php @@ -2,6 +2,15 @@ # Copyright (c) 2003-2005, Jannis Hermanns (on behalf the Serendipity Developer Team) # All rights reserved. See LICENSE file for licensing details +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /** * validate trackback response */ @@ -21,6 +30,15 @@ function serendipity_trackback_is_success($resp) { return true; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_pingback_autodiscover($loc, $body) { global $serendipity; if (!empty($_SERVER['X-PINGBACK'])) { @@ -50,6 +68,15 @@ global $serendipity; return; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /** * Send a trackback ping */ @@ -90,6 +117,15 @@ function _serendipity_send($loc, $data) { return $res; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_trackback_autodiscover($res, $loc, $url, $author, $title, $text, $loc2 = '') { if (!preg_match('@trackback:ping(\s*rdf:resource)?\s*=\s*["\'](https?:[^"\']+)["\']@i', $res, $matches)) { $matches = array(); @@ -130,6 +166,15 @@ function serendipity_trackback_autodiscover($res, $loc, $url, $author, $title, $ return $response; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function serendipity_reference_autodiscover($loc, $url, $author, $title, $text) { global $serendipity; $timeout = 30; @@ -191,7 +236,13 @@ global $serendipity; } /** + * SHORT + * + * LONG * + * @access public + * @param + * @return */ function add_trackback ($id, $title, $url, $name, $excerpt) { global $serendipity; @@ -217,6 +268,15 @@ function add_trackback ($id, $title, $url, $name, $excerpt) { return 1; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function add_pingback ($id, $postdata) { global $serendipity; @@ -234,6 +294,15 @@ function add_pingback ($id, $postdata) { return 0; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /** * Cut text */ @@ -241,6 +310,15 @@ function serendipity_trackback_excerpt($text) { return substr(strip_tags($text), 0, 255); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function report_trackback_success () { print '' . "\n"; print <<' . "\n"; print <<' . "\n"; print <<' . "\n"; print << \ No newline at end of file diff --git a/include/lang.inc.php b/include/lang.inc.php index 7b70946..ce89098 100644 --- a/include/lang.inc.php +++ b/include/lang.inc.php @@ -30,6 +30,15 @@ if (!defined('serendipity_MB_LOADED') && defined('serendipity_LANG_LOADED')) { @mb_internal_encoding(LANG_CHARSET); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ // Multibyte string functions wrapper: // strlen(), strpos(), strrpos(), strtolower(), strtoupper(), substr(), ucfirst() function serendipity_mb() { @@ -78,4 +87,3 @@ if (!defined('serendipity_MB_LOADED') && defined('serendipity_LANG_LOADED')) { } /* vim: set sts=4 ts=4 expandtab : */ -?> \ No newline at end of file diff --git a/include/plugin_api.inc.php b/include/plugin_api.inc.php index 72985b1..aadf36d 100644 --- a/include/plugin_api.inc.php +++ b/include/plugin_api.inc.php @@ -28,6 +28,16 @@ include_once S9Y_INCLUDE_PATH . 'include/functions.inc.php'; */ class serendipity_plugin_api { + +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function register_default_plugins() { /* Register default sidebar plugins, order matters */ @@ -47,18 +57,28 @@ class serendipity_plugin_api { serendipity_plugin_api::create_plugin_instance('serendipity_event_spamblock', null, 'event'); } - /* Create an instance of a plugin. - * $plugin_class_id is of the form: - * @class_name for a built-in plugin - * or - * plugin_dir_name for a third-party plugin - * returns the instance identifier for the newly created plugin. - * - * TO BE IMPLEMENTED: - * If $copy_from_instance is not null, and identifies another plugin - * of the same class, then the persistent state will be copied. - * This allows the user to clone a plugin. - */ +/** + * Create an instance of a plugin. + * + * $plugin_class_id is of the form: + * @class_name for a built-in plugin + * or + * plugin_dir_name for a third-party plugin + * returns the instance identifier for the newly created plugin. + * + * TO BE IMPLEMENTED: + * If $copy_from_instance is not null, and identifies another plugin + * of the same class, then the persistent state will be copied. + * This allows the user to clone a plugin. + * + * @access public + * @param string classname of the plugin to insert (see description above for details) + * @param boolean (reserved) variable to indicate a copy of an existing instance + * @param string The type of the plugin to insert (event/left/right/hidden) + * @param int The authorid of the plugin owner + * @param string The source path of the plugin file + * @return string ID of the new plugin + */ function create_plugin_instance($plugin_class_id, $copy_from_instance = null, $default_placement = 'right', $authorid = '0', $pluginPath = '') { global $serendipity; @@ -102,6 +122,15 @@ class serendipity_plugin_api { return $key; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function remove_plugin_instance($plugin_instance_id) { global $serendipity; @@ -122,6 +151,15 @@ class serendipity_plugin_api { serendipity_db_query("DELETE FROM {$serendipity['dbPrefix']}config where name LIKE '$plugin_instance_id/%'"); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function remove_plugin_value($plugin_instance_id, $where) { global $serendipity; @@ -136,6 +174,15 @@ class serendipity_plugin_api { serendipity_db_query($query); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /* Retrieves a list of available plugins */ function &enum_plugin_classes($event_only = false) { @@ -181,6 +228,15 @@ class serendipity_plugin_api { return $classes; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function traverse_plugin_dir($ppath, &$classes, $event_only, $maindir = '') { $d = @opendir($ppath); if ($d) { @@ -243,6 +299,15 @@ class serendipity_plugin_api { } } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function get_installed_plugins($filter = '*') { $plugins = serendipity_plugin_api::enum_plugins($filter); $res = array(); @@ -256,6 +321,15 @@ class serendipity_plugin_api { return $res; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /* Retrieves a list of plugin instances */ function enum_plugins($filter = '*', $negate = false, $classname = null, $id = null) { @@ -289,6 +363,15 @@ class serendipity_plugin_api { return serendipity_db_query($sql); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /* Retrieves a list of plugin instances */ function count_plugins($filter = '*', $negate = false) { @@ -312,6 +395,15 @@ class serendipity_plugin_api { return 0; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function includePlugin($name, $pluginPath = '', $instance_id = '') { global $serendipity; @@ -334,6 +426,15 @@ class serendipity_plugin_api { return $file; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function getClassByInstanceID($instance_id, &$is_internal) { $instance = explode(':', $instance_id); $name = $instance[0]; @@ -347,6 +448,15 @@ class serendipity_plugin_api { return $class_name; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /* Probes for the plugin filename */ function probePlugin($instance_id, &$class_name, &$pluginPath) { global $serendipity; @@ -386,6 +496,15 @@ class serendipity_plugin_api { return $filename; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /* Creates an instance of a named plugin */ function &load_plugin($instance_id, $authorid = null, $pluginPath = '', $pluginFile = null) { global $serendipity; @@ -426,6 +545,15 @@ class serendipity_plugin_api { return $p; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function &getPluginInfo(&$pluginFile, &$class_data, $type) { global $serendipity; @@ -465,6 +593,15 @@ class serendipity_plugin_api { return $plugin; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function &setPluginInfo(&$plugin, &$pluginFile, &$bag, &$class_data, $pluginlocation = 'local') { global $serendipity; @@ -558,6 +695,15 @@ class serendipity_plugin_api { return $data; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function update_plugin_placement($name, $placement, $order=null) { global $serendipity; @@ -579,6 +725,15 @@ class serendipity_plugin_api { return serendipity_db_query($sql); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function update_plugin_owner($name, $authorid) { global $serendipity; @@ -597,6 +752,15 @@ class serendipity_plugin_api { return serendipity_db_query($sql); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function generate_plugins($side, $tag = '', $negate = false, $class = null, $id = null) { global $serendipity; @@ -657,6 +821,15 @@ class serendipity_plugin_api { return serendipity_smarty_fetch('sidebar_'. $side, 'sidebar.tpl', true); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function get_plugin_title(&$plugin, $default_title = '') { global $serendipity; @@ -687,12 +860,30 @@ class serendipity_plugin_api { return $title; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /* conditional to see if the named plugin is an event plugin Refactoring: decompose conditional */ function is_event_plugin($name) { return (strstr($name, '_event_')); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function &get_event_plugins($getInstance = false, $refresh = false) { static $event_plugins; static $false = false; @@ -735,6 +926,15 @@ class serendipity_plugin_api { return $event_plugins; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function hook_event($event_name, &$eventData, $addData = null) { global $serendipity; @@ -764,6 +964,15 @@ class serendipity_plugin_api { return true; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function exists($instance_id) { global $serendipity; @@ -780,6 +989,15 @@ class serendipity_plugin_api { return false; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function &autodetect_instance($plugin_name, $authorid, $is_event_plugin = false) { if ($is_event_plugin) { $side = 'event'; @@ -800,19 +1018,55 @@ class serendipity_plugin_api { /* holds a bunch of properties; since serendipity 0.8 only one value per key is allowed [was never really useful] */ class serendipity_property_bag { +/** + * @access private + * @var array property storage container. + */ var $properties = array(); + +/** + * @access private + * @var string Name of the property bag + */ var $name = null; +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function add($name, $value) { $this->properties[$name] = $value; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function &get($name) { return $this->properties[$name]; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function is_set($name) { if (isset($this->properties[$name])) { @@ -831,35 +1085,70 @@ class serendipity_plugin { var $content_class = 'serendipitySideBarContent'; var $title = null; - /* Be sure to call this method from your derived classes constructors, - * otherwise your config data will not be stored or retrieved correctly - */ - +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ +/* Be sure to call this method from your derived classes constructors, + * otherwise your config data will not be stored or retrieved correctly + */ function serendipity_plugin($instance) { $this->instance = $instance; } - /* Called by Serendipity when the plugin is first installed. - * Can be used to install database tables etc. - */ +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ +/* Called by Serendipity when the plugin is first installed. + * Can be used to install database tables etc. + */ function install() { return true; } - /* Called by Serendipity when the plugin is removed/uninstalled. - * Can be used to drop installed database tables etc. - */ +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ +/* Called by Serendipity when the plugin is removed/uninstalled. + * Can be used to drop installed database tables etc. + */ function uninstall(&$propbag) { return true; } - /* Called by serendipity when it wants to display information - * about your plugin. - * You need to override this method in your child class. - */ +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ +/* Called by serendipity when it wants to display information + * about your plugin. + * You need to override this method in your child class. + */ function introspect(&$propbag) { $propbag->add('copyright', 'MIT License'); @@ -878,21 +1167,39 @@ class serendipity_plugin { return true; } - /* Called by serendipity when it wants to display the configuration - * editor for your plugin. - * $name is the name of a configuration item you added in - * your instrospect method. - * You need to fill the property bag with appropriate items - * that describe the type and value(s) for that particular - * configuration option. - * You need to override this method in your child class if - * you have configuration options. - */ +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ +/* Called by serendipity when it wants to display the configuration + * editor for your plugin. + * $name is the name of a configuration item you added in + * your instrospect method. + * You need to fill the property bag with appropriate items + * that describe the type and value(s) for that particular + * configuration option. + * You need to override this method in your child class if + * you have configuration options. + */ function introspect_config_item($name, &$propbag) { return false; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /* Called to validate a plugin option */ function validate($config_item, &$cbag, &$value) { static $pattern_mail = '([\.\-\+~@_0-9a-z]+?)'; @@ -959,19 +1266,37 @@ class serendipity_plugin { return true; } - /* Called by serendipity when it wants your plugin to display itself. - * You need to set $title to be whatever text you want want to - * appear in the item caption space. - * Simply echo/print your content to the output; serendipity will - * capture it and make things work. - * You need to override this method in your child class. - */ +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ +/* Called by serendipity when it wants your plugin to display itself. + * You need to set $title to be whatever text you want want to + * appear in the item caption space. + * Simply echo/print your content to the output; serendipity will + * capture it and make things work. + * You need to override this method in your child class. + */ function generate_content(&$title) { $title = 'Sample!'; echo 'This is a sample!'; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /* Fetches a configuration value for this plugin */ function get_config($name, $defaultvalue = null, $empty = true) { @@ -994,6 +1319,15 @@ class serendipity_plugin { return $_res; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function set_config($name, $value) { $name = $this->instance . '/' . $name; @@ -1001,6 +1335,15 @@ class serendipity_plugin { return serendipity_set_config_var($name, $value); } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ /* Called by serendipity after insertion of a config item. If you want to kick out certain * elements based on contents, create the corresponding function here. */ @@ -1011,6 +1354,15 @@ class serendipity_plugin { return true; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function register_dependencies($remove = false, $authorid = '0') { global $serendipity; @@ -1056,19 +1408,36 @@ class serendipity_plugin { } class serendipity_event extends serendipity_plugin { - /* Events can be called on several occasions when s9y performs an action. - * One or multiple plugin can be registered for each of those hooks. - */ - - /* Be sure to call this method from your derived classes constructors, - * otherwise your config data will not be stored or retrieved correctly - */ +/* Events can be called on several occasions when s9y performs an action. + * One or multiple plugin can be registered for each of those hooks. + */ +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ +/* Be sure to call this method from your derived classes constructors, + * otherwise your config data will not be stored or retrieved correctly + */ function serendipity_event($instance) { $this->instance = $instance; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function &getFieldReference($fieldname = 'body', &$eventData) { // Get a reference to a content field (body/extended) of // $entries input data. This is a unifying function because @@ -1102,6 +1471,15 @@ class serendipity_event extends serendipity_plugin { return $key; } +/** + * SHORT + * + * LONG + * + * @access public + * @param + * @return + */ function event_hook($event, &$bag, &$eventData, $addData = null) { // Define event hooks here, if you want you plugin to execute those instead of being a sidebar item. // Look at external plugins 'serendipity_event_mailer' or 'serendipity_event_weblogping' for usage. @@ -1117,4 +1495,3 @@ class serendipity_event extends serendipity_plugin { include_once S9Y_INCLUDE_PATH . 'include/plugin_internal.inc.php'; /* vim: set sts=4 ts=4 expandtab : */ -?>