# All rights reserved. See LICENSE file for licensing details
/**
- * SHORT
- *
- * LONG
+ * Adds a new author account
*
* @access public
- * @param
- * @return
+ * @param string New username
+ * @param string New password
+ * @param string The realname of the user
+ * @param string The email address of the user
+ * @param int The userlevel of a user
+ * @return int The new user ID of the added author
*/
function serendipity_addAuthor($username, $password, $realname, $email, $userlevel=0) {
global $serendipity;
}
/**
- * SHORT
+ * Delete an author account
*
- * LONG
+ * (Note, this function does not delete entries by an author)
*
* @access public
- * @param
- * @return
+ * @param int The author ID to delete
+ * @return boolean True on success, false on error or unsufficient privileges
*/
function serendipity_deleteAuthor($authorid) {
global $serendipity;
}
/**
- * SHORT
+ * Removes a configuration value from the Serendipity Configuration
*
- * LONG
+ * Global config items have the authorid 0, author-specific configuration items have the corresponding authorid.
*
* @access public
- * @param
- * @return
+ * @param string The name of the configuration value
+ * @param int The ID of the owner of the config value (0: global)
+ * @return null
*/
function serendipity_remove_config_var($name, $authorid = 0) {
global $serendipity;
}
/**
- * SHORT
+ * Sets a configuration value for the Serendipity Configuration
*
- * LONG
+ * Global config items have the authorid 0, author-specific configuration items have the corresponding authorid.
*
* @access public
- * @param
- * @return
+ * @param string The name of the configuration value
+ * @param string The value of the configuration item
+ * @param int The ID of the owner of the config value (0: global)
+ * @return null
*/
function serendipity_set_config_var($name, $val, $authorid = 0) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Retrieve a global configuration value for a specific item of the current Serendipity Configuration
*
* @access public
- * @param
- * @return
+ * @param string The name of the configuration value
+ * @param string The default value of a configuration item, if not found in the Database
+ * @param boolean If set to true, the default value of a configuration item will be returned if the item is set, but empty. If false, an empty configuration value will be returned empty. This is required for getting default values if you do not want to store/allow empty config values.
+ * @return string The configuration value content
*/
function serendipity_get_config_var($name, $defval = false, $empty = false) {
global $serendipity;
}
/**
- * SHORT
+ * Retrieve an author-specific configuration value for an item of the Serendipity Configuration stored in the DB
*
- * LONG
+ * Despite the serendipity_get_config_var() function, this will retrieve author-specific values straight from the Database.
*
* @access public
- * @param
- * @return
+ * @param string The name of the configuration value
+ * @param int The ID of the owner of the config value (0: global)
+ * @param string The default value of a configuration option, if not set in the DB
+ * @return string The configuration value content
*/
function serendipity_get_user_config_var($name, $authorid, $default = '') {
global $serendipity;
}
/**
- * SHORT
+ * Retrieves an author-specific account value
*
- * LONG
+ * This retrieves specific account data from the user configuration, not from the serendipity configuration.
*
* @access public
- * @param
- * @return
+ * @param string The name of the configuration value
+ * @param int The ID of the author to fetch the configuration for
+ * @param string The default value of a configuration option, if not set in the DB
+ * @return string The configuration value content
*/
function serendipity_get_user_var($name, $authorid, $default) {
global $serendipity;
}
/**
- * SHORT
+ * Updates data from the author-specific account
*
- * LONG
+ * This sets the personal account data of a serendipity user within the 'authors' DB table
*
* @access public
- * @param
- * @return
+ * @param string The name of the configuration value
+ * @param string The content of the configuration value
+ * @param int The ID of the author to set the configuration for
+ * @param boolean If set to true, the stored config value will be imported to the Session/current config of the user. This is applied for example when you change your own user's preferences and want it to be immediately reflected in the interface.
+ * @return null
*/
function serendipity_set_user_var($name, $val, $authorid, $copy_to_s9y = true) {
global $serendipity;
}
/**
- * SHORT
+ * Gets the full filename and path of a template/style/theme file
*
- * LONG
+ * The returned full path is depending on the second parameter, where you can either fetch a HTTP path, or a realpath.
+ * The file is searched in the current template, and if it is not found there, it is returned from the default template.
*
* @access public
- * @param
- * @return
+ * @param string The filename to search for in the selected template
+ * @param string The path selector that tells whether to return a HTTP or realpath
+ * @return string The full path+filename to the requested file
*/
function serendipity_getTemplateFile($file, $key = 'serendipityHTTPPath') {
global $serendipity;
}
/**
- * SHORT
+ * Loads all configuration values and imports them to the $serendipity array
*
- * LONG
+ * This function may be called twice - once for the global config and once for
+ * user-specific config
*
* @access public
- * @param
- * @return
+ * @param int The Authorid to fetch the configuration from (0: global)
+ * @return null
*/
function serendipity_load_configuration($author = null) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Perform logout functions (destroys session data)
*
* @access public
- * @param
- * @return
+ * @return null
*/
function serendipity_logout() {
$_SESSION['serendipityAuthedUser'] = false;
}
/**
- * SHORT
- *
- * LONG
+ * Perform login to Serendipity
*
* @access public
- * @param
- * @return
+ * @param boolean If set to true, external plugins will be queried for getting a login
+ * @return boolean Return true, if the user is logged in. False if not.
*/
function serendipity_login($use_external = true) {
global $serendipity;
return true;
}
+ // First try login via POST data. If true, the userinformation will be stored in a cookie (optionally)
if (serendipity_authenticate_author($serendipity['POST']['user'], $serendipity['POST']['pass'], false, $use_external)) {
if (empty($serendipity['POST']['auto'])) {
serendipity_deleteCookie('author_information');
serendipity_setCookie('author_information', base64_encode($package));
return true;
}
+ // Now try login via COOKIE data
} elseif ( isset($serendipity['COOKIE']['author_information']) ) {
$cookie = unserialize(base64_decode($serendipity['COOKIE']['author_information']));
if (serendipity_authenticate_author($cookie['username'], $cookie['password'], false, $use_external)) {
}
/**
- * SHORT
- *
- * LONG
+ * Check if a user is logged in
*
* @access public
- * @param
- * @return
+ * @return boolean TRUE when logged in, FALSE when not.
*/
function serendipity_userLoggedIn() {
if ($_SESSION['serendipityAuthedUser'] === true && IS_installed) {
}
/**
- * SHORT
+ * A clone of an ifsetor() function to set a variable conditional on if the target already exists
*
- * LONG
+ * The function sets the contents of $source into the $target variable, but only if $target is not yet set. Eases up some if...else logic or multiple ternary operators
*
* @access public
- * @param
- * @return
+ * @param mixed Source variable that should be set into the target variable (reference call!)
+ * @param mixed Target variable, that should get the contents of the source variable (reference call!)
+ * @return boolean True, when $target was not yet set and has been altered. False when no changes where made.
*/
function serendipity_restoreVar(&$source, &$target) {
global $serendipity;
}
/**
- * SHORT
+ * Echo Javascript code to set a cookie variable
*
- * LONG
+ * This function is useful if your HTTP headers were already sent, but you still want to set a cookie
+ * Note that contents are echo'd, not return'd.
*
* @access public
- * @param
- * @return
+ * @param string The name of the cookie variable
+ * @param string The contents of the cookie variable
+ * @return null
*/
function serendipity_JSsetCookie($name, $value) {
$name = str_replace('"', '\"', $name);
}
/**
- * SHORT
- *
- * LONG
+ * Set a Cookie via HTTP calls, and update $_COOKIE plus $serendipity['COOKIE'] array.
*
* @access public
- * @param
- * @return
+ * @param string The name of the cookie variable
+ * @param string The contents of the cookie variable
+ * @return null
*/
function serendipity_setCookie($name,$value) {
global $serendipity;
}
/**
- * SHORT
+ * Deletes an existing cookie value
*
* LONG
*
* @access public
- * @param
+ * @param string Name of the cookie to delete
* @return
*/
function serendipity_deleteCookie($name) {
}
/**
- * SHORT
+ * Perform user authentication routine
*
- * LONG
+ * If a user is already authenticated via session data, this bypasses some routines.
+ * After a user has ben authenticated, several SESSION variables ar set.
+ * If the authentication fails, the session is destroyed.
*
* @access public
- * @param
- * @return
+ * @param string The username to check
+ * @param string The password to check (may contain plaintext or MD5 hash)
+ * @param boolean Indicates whether the input password is already in MD5 format (TRUE) or not (FALSE).
+ * @param boolean Indicates whether to query external plugins for authentication
+ * @return boolean True on success, False on error
*/
function serendipity_authenticate_author($username = '', $password = '', $is_md5 = false, $use_external = true) {
global $serendipity;
}
/**
- * SHORT
+ * Performs a check whether an iframe for the admin section shall be emitted
*
- * LONG
+ * The iframe is used for previewing an entry with the stylesheet of the frontend.
+ * It fetches its data from the session input data.
*
- * @access public
- * @param
- * @return
+ * @access private
+ * @return boolean True, if iframe was requested, false if not.
*/
function serendipity_is_iframe() {
global $serendipity;
}
/**
- * SHORT
+ * Prints the content of the iframe.
*
- * LONG
+ * Called by serendipity_is_iframe, when preview is requested. Fetches data from session.
+ * An iframe is used so that a single s9y page must not timeout on intensive operations,
+ * and so that the frontend stylesheet can be embedded without screwing up the backend.
*
- * @access public
- * @param
- * @return
+ * @access private
+ * @see serendipity_is_iframe()
+ * @param mixed The entry array (comes from session variable)
+ * @param string Indicates whether an entry is previewed or saved. Save performs XML-RPC calls.
+ * @return boolean Indicates whether iframe data was printed
*/
function serendipity_iframe(&$entry, $mode = null) {
global $serendipity;
}
/**
- * SHORT
+ * Creates the necessary session data to be used by later iframe calls
*
- * LONG
+ * This function emits the actual <iframe> call.
*
- * @access public
- * @param
- * @return
+ * @access private
+ * @see serendipity_is_iframe()
+ * @param string Indicates whether an entry is previewed or saved. Save performs XML-RPC calls.
+ * @param mixed The entry array (comes from HTTP POST request)
+ * @return boolean Indicates whether iframe data was stored
*/
function serendipity_iframe_create($mode, &$entry) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Pre-Checks certain server environments to indicate available options when installing Serendipity
*
* @access public
- * @param
- * @return
+ * @param string The name of the configuration option that needs to be checked for environmental data.
+ * @return array Returns the array of available options for the requested config option
*/
function serendipity_probeInstallation($item) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Sets a HTTP header
*
* @access public
- * @param
- * @return
+ * @param string The HTTP headre to set
+ * @return null
*/
function serendipity_header($header) {
if (!headers_sent()) {
}
/**
- * SHORT
+ * Gets the currently selected language. Either from the browser, or the personal configuration, or the global configuration.
*
- * LONG
+ * This function also sets HTTP Headers and cookies to contain the language for follow-up requests
+ * 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
+ * having loaded the right language.
+ * Find a way to let plugins hook into that sequence :-)
*
* @access public
- * @param
- * @return
+ * @return string Returns the name of the selected language.
*/
-/* 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
- having loaded the right language.
- Find a way to let plugins hook into that sequence :-) */
function serendipity_getSessionLanguage() {
global $serendipity;
}
/**
- * SHORT
+ * Retrieves an array of applying permissions to an author
*
- * LONG
+ * The privileges of each group an author is a member of are aggreated
+ * and stored in a larger array. So both memberships and all aplying
+ * privileges are returned.
*
* @access public
- * @param
- * @return
+ * @param int The ID of the author to fetch permissions/group memberships for
+ * @return array Multi-dimensional associative array which holds a 'membership' and permission name data
*/
function &serendipity_getPermissions($authorid) {
global $serendipity;
}
/**
- * SHORT
+ * Returns the list of available internal Serendipity permission field names
*
- * LONG
+ * This function also mapps which function was available to which userleves in older
+ * Serendipity versions. Thus if an author does not have a certain privilege he should
+ * have because of his userlevel, this can be reverse-mapped.
*
* @access public
- * @param
- * @return
+ * @return array Multi-dimensional associative array which the list of all permission items plus their userlevel associations
*/
function serendipity_getPermissionNames() {
return array(
}
/**
- * SHORT
+ * Checks if a permission is granted to a specific author
*
- * LONG
+ * This function caches all permission chacks in static function variables to not
+ * fetch all permissions time and again.
+ * The permission checks are performed agains the values of each group. If a privilege
+ * is set in one of the groups the author is a user of, the function returns true.
+ * If a privilege is not set, the userlevel of an author is checked to act for backwards-compatibility.
*
* @access public
- * @param
- * @return
+ * @see serendipity_getPermissionNames()
+ * @param string The name of the permission to check
+ * @param int The authorid for which the permission check should be performed
+ * @param boolean If set to true, all groups that the requested author is a user of will be returned. This bypasses the permission check and mainly acts as a mean to return cached permissions, since those variables are only available within this function.
+ * @return mixed Either returns true if a permission check is performed, or return an array of group memberships. Depends on the $returnMyGroups variable.
*/
function serendipity_checkPermission($permName, $authorid = null, $returnMyGroups = false) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Update author group membership(s)
*
* @access public
- * @param
+ * @param array The array of groups the author should be a member of. All memberships that were present before and not contained in this array will be removed.
+ * @param int The ID of the author to update
+ * @param boolean If set to true, the groups can only be updated if the user has the adminUsersMaintainOthers privilege. If set to false, group memberships will be changable for any user.
* @return
*/
function serendipity_updateGroups($groups, $authorid, $apply_acl = true) {
}
/**
- * SHORT
+ * Returns all authorgroups that are available
*
- * LONG
+ * If a groupname is prefixed with "USERLEVEL_" then the constant of that name is used to
+ * return the name of the group. This allows inserting the special groups Chief Editor, Editor
+ * and admin and still being able to use multilingual names for these groups.
*
* @access public
- * @param
- * @return
+ * @param int If set to an author ID value, only groups are fetched that this author is a member of. If set to false, all groups are returned, also those that the current user has no access to.
+ * @return array An associative array of group names.
*/
function &serendipity_getAllGroups($apply_ACL_user = false) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Fetch the permissions of a certain group
*
* @access public
- * @param
- * @return
+ * @param int The ID of the group that the permissions are fetched for
+ * @return array The associative array of permissions of a group.
*/
function &serendipity_fetchGroup($groupid) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Gets all groups a user is a member of
*
* @access public
- * @param
+ * @param int The authorid to fetch groups for
+ * @param boolean Indicate whether the original multi-dimensional DB result array shall be returned (FALSE) or if the array shall be flattened to be 1-dimensional (TRUE).
* @return
*/
function &serendipity_getGroups($authorid, $sequence = false) {
}
/**
- * SHORT
- *
- * LONG
+ * Gets all author IDs of a specific group
*
* @access public
- * @param
- * @return
+ * @param int The ID of the group to fetch the authors of
+ * @return array The assotiative array of author IDs and names
*/
function &serendipity_getGroupUsers($groupid) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Deletes a specific author group by ID
*
* @access public
- * @param
- * @return
+ * @param int The group ID to delete
+ * @return boolean Return true if group could be deleted, false if unsufficient privileges.
*/
function serendipity_deleteGroup($groupid) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Creates a new author group
*
* @access public
- * @param
- * @return
+ * @param string The name of the new group
+ * @return int The id of the created group
*/
function serendipity_addGroup($name) {
global $serendipity;
}
/**
- * SHORT
+ * Returns a list of all existing permission names.
*
- * LONG
+ * Additional plugins might insert specific properties into the groupconfig database to
+ * handle their own privileges. This call returns an array of all available permission names
+ * so that it can be intersected with the list of internal permission names (serendipity_getPermissionNames())
+ * and the be distincted.
*
* @access public
- * @param
- * @return
+ * @see serendipity_getPermissionNames()
+ * @return array associative array of all available permission names
*/
function &serendipity_getDBPermissionNames() {
global $serendipity;
}
/**
- * SHORT
+ * Gets the list of all Permissions and merges the two arrays
*
- * LONG
+ * The first call will fetch all existing permission names of the database. Then it will
+ * fetch the list of defined internal permission names, which has an array with extra information
+ * (like userlevel). This array will be merged with those permission names only found in the
+ * database. The returned array will then hold as much information about permission names as is
+ * available.
+ * TODO Might need further pushing and/or an event hook so that external plugins using the
+ * permission system can inject specific information into the array
*
* @access public
- * @param
- * @return
+ * @see serendipity_getPermissionNames()
+ * @see serendipity_getDBPermissionNames()
+ * @return array Returns the array with all information about all permission names
*/
function &serendipity_getAllPermissionNames() {
global $serendipity;
}
/**
- * SHORT
+ * Checks if two users are members of the same group
*
- * LONG
+ * This function will retrieve all group memeberships of a
+ * foreign user ($checkuser) and yourself ($myself). Then it
+ * will check if there is any group membership that those
+ * two users have in common.
+ * It can be used for detecting if a different author should
+ * be allowed to access your entries, because he's in the same
+ * group, for example.
*
* @access public
- * @param
- * @return
+ * @param int ID of the first author to check group memberships
+ * @param int ID of the second author to check group memberships
+ * @return boolea True if a membership intersects, false if not
*/
function serendipity_intersectGroup($checkuser = null, $myself = null) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Updates the configuration of permissions of a specific group
*
+ * This function ensures that a group can only be updated from users that have permissions to do so.
* @access public
- * @param
- * @return
+ * @param int The ID of the group to update
+ * @param array The associative array of permission names
+ * @param array The associative array of new values for the permissions. Needs the same associative keys like the $perms array.
+ * @return true
*/
function serendipity_updateGroupConfig($groupid, &$perms, &$values) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Adds a default internal group (Editor, Chief Editor, Admin)
*
* @access public
- * @param
- * @return
+ * @param string The name of the group to insert
+ * @param int The userlevel that represents this group (0|1|255 for Editor/Chief/Admin).
+ * @return true
*/
function serendipity_addDefaultGroup($name, $level) {
global $serendipity;
}
/**
- * SHORT
+ * Allow access to a specific item (category or entry) for a specific usergroup
*
- * LONG
+ * ACL are Access Control Lists. They indicate which read/write permissions a
+ * specific item has for specific usergroups.
+ * An artifact in terms of Serendipity can be either a category or an entry, or
+ * anything beyond that for future compatibility.
+ * This function sets up the ACLs.
*
* @access public
- * @param
- * @return
+ * @param int The ID of the artifact to set the access
+ * @param string The type of an artifact (category|entry)
+ * @param string The type of access to grant (read|write)
+ * @param array The ID of the group to grant access to
+ * @return boolean True if ACL was applied, false if not.
*/
function serendipity_ACLGrant($artifact_id, $artifact_type, $artifact_mode, $groups) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
- *
+ * Checks if a specific item (category or entry) can be accessed by a specific usergroup
+ *
+ * ACL are Access Control Lists. They indicate which read/write permissions a
+ * specific item has for specific usergroups.
+ * An artifact in terms of Serendipity can be either a category or an entry, or
+ * anything beyond that for future compatibility.
+ * This function retrieves the ACLs.
+ *
* @access public
- * @param
- * @return
+ * @param int The ID of the artifact to set the access
+ * @param string The type of an artifact (category|entry)
+ * @param string The type of access to check for (read|write)
+ * @return array Returns an array of all groups that are allowed for this kind of access. You can then check if you are the member of any of the groups returned here.
*/
function serendipity_ACLGet($artifact_id, $artifact_type, $artifact_mode) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
- *
+ * Checks if a specific item (category or entry) can be accessed by a specific Author
+ *
+ * ACL are Access Control Lists. They indicate which read/write permissions a
+ * specific item has for specific usergroups.
+ * An artifact in terms of Serendipity can be either a category or an entry, or
+ * anything beyond that for future compatibility.
+ * This function retrieves the ACLs for a specific user.
+ *
* @access public
- * @param
- * @return
+ * @param int The ID of the author to check against.
+ * @param int The ID of the artifact to set the access
+ * @param string The type of an artifact ('category', more to come)
+ * @param string The type of access to check for (read|write)
+ * @return boolean Returns true, if the author has access to this artifact. False if not.
*/
function serendipity_ACLCheck($authorid, $artifact_id, $artifact_type, $artifact_mode) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
- *
- * @access public
- * @param
- * @return
+ * Prepares a SQL statement to be used in queries that should be ACL restricted.
+ *
+ * ACL are Access Control Lists. They indicate which read/write permissions a
+ * specific item has for specific usergroups.
+ * An artifact in terms of Serendipity can be either a category or an entry, or
+ * anything beyond that for future compatibility.
+ * This function evaluates and applies the SQL statements required.
+ * It is currently only written for retrieving Category ACLs.
+ * All of the SQL code that will be used in serendipity_fetchEntries will be stored
+ * within the referenced $cond array.
+ *
+ * @access private
+ * @param array Associative array that holds the SQL part array to be used in other functions like serendipity_fetchEntries()
+ * @param boolean Some queries do not need to joins categories. When ACLs need to be applied, this column is required, so if $append_category is set to true it will perform this missing JOIN.
+ * @return true True if ACLs were applied, false if not.
*/
function serendipity_ACL_SQL(&$cond, $append_category = false) {
global $serendipity;
+ // A global configuration item controls whether the blog should apply ACLs or not!
if (!isset($serendipity['enableACL']) || $serendipity['enableACL'] == true) {
+
+ // If the user is logged in, we retrieve his authorid for the upcoming checks
if ($_SESSION['serendipityAuthedUser'] === true) {
$read_id = (int)$serendipity['authorid'];
$read_id_sql = 'acl_a.groupid OR acl_acc.groupid = 0';
}
/**
- * SHORT
+ * Check for Cross-Site-Request-Forgery attacks because of missing HTTP Referer
*
- * LONG
+ * http://de.wikipedia.org/wiki/XSRF
+ * This function checks the HTTP referer, and if it is part of the current Admin panel.
*
* @access public
- * @param
- * @return
+ * @return Returns true if XSRF was detected, false if not. The script should abort, if TRUE is returned.
*/
function serendipity_checkXSRF() {
global $serendipity;
}
/**
- * SHORT
+ * Report a XSRF attempt to the Serendipity Interface
+ *
+ * http://de.wikipedia.org/wiki/XSRF
*
* LONG
*
* @access public
- * @param
- * @return
+ * @see serendipity_checkXSRF()
+ * @param string The type of XSRF check that got hit. Used for CSS formatting.
+ * @param boolean If true, the XSRF error should be fatal
+ * @param boolean If true, tell Serendipity to check the $serendipity['referrerXSRF'] config option to decide if an error should be reported or not.
+ * @return string Returns the HTML error report
*/
function serendipity_reportXSRF($type = 0, $reset = true, $use_config = false) {
global $serendipity;
}
/**
- * SHORT
+ * Prevent XSRF attacks by checking for a form token
*
- * LONG
+ * http://de.wikipedia.org/wiki/XSRF
+ *
+ * This function checks, if a valid Form token was posted to the site.
*
* @access public
- * @param
- * @return
+ * @see serendipity_setFormToken()
+ * @return boolean Returns true, if XSRF attempt was found and the token was missing
*/
function serendipity_checkFormToken() {
global $serendipity;
}
/**
- * SHORT
+/**
+ * Prevent XSRF attacks by setting a form token within HTTP Forms
*
- * LONG
+ * http://de.wikipedia.org/wiki/XSRF
+ *
+ * By inserting a unique Form token that holds the session id, all requests
+ * to serendipity HTTP forms can only be processed if the token is present.
+ * This effectively makes XSRF attacks impossible. Only bundled with XSS
+ * attacks it can be bypassed.
+ *
+ * 'form' type tokens can be embedded within the <form> script.
+ * 'url' type token can be embedded within HTTP GET calls.
*
* @access public
- * @param
- * @return
+ * @param string The type of token to return (form|url|plain)
+ * @return string Returns the form token to be used in your functions
*/
function serendipity_setFormToken($type = 'form') {
global $serendipity;
# All rights reserved. See LICENSE file for licensing details
/**
- * SHORT
- *
- * LONG
+ * Delete a category or range of categories
*
* @access public
- * @param
- * @return
+ * @param string Holds the SQL string to pass to the 'BETWEEN' command. Like '1 5' would delete categories 1-5.
+ * @param string Holds the optional SQL string that contains an extra safety check so that only categories can be deleted if the user is an author of the category.
+ * @return array The DB result
*/
function serendipity_deleteCategory($category_range, $admin_category) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Fetch a SQL ID subset of the category tree
*
* @access public
- * @param
- * @return
+ * @param int The Id of the parent category to fetch categorie childs from. (0: all)
+ * @return array An associative array of the left and right category next to the chosen one
*/
function serendipity_fetchCategoryRange($categoryid) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Returns SQL code to use when fetching entries that are contained within multiple categories
*
* @access public
- * @param
- * @return
+ * @param string A listing of category ids to check, separated by ";"
+ * @return string Returns the SQL code for selecting entries of the calculated categories
*/
function serendipity_getMultiCategoriesSQL($cats) {
global $serendipity;
}
/**
- * SHORT
+ * Return the category properties of a specific category
*
- * LONG
+ * Either use the first or the second parameter to select a category by ID or name. It's not
+ * meant to be used with both parameters specified.
*
* @access public
- * @param
- * @return
+ * @param int The ID of the category to fetch
+ * @param string The Name of a category to fetch
+ * @return array Returns an array of category properties
*/
function serendipity_fetchCategoryInfo($categoryid, $categoryname = '') {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Fetch a list of all category properties to a specific entry ID
*
* @access public
- * @param
- * @return
+ * @param int The ID of the entry
+ * @return array The array of associated categories to that entry
*/
function serendipity_fetchEntryCategories($entryid) {
global $serendipity;
/**
- * SHORT
+ * Fetch a list of entries
*
- * LONG
+ * The most central and versatile function of Serendipity, allows you to fetch entries
+ * depending on a LOT of options.
+ * One of the parameters missing is a restriction by category. You need to do that by
+ * setting the superglobal $serendipity['GET']['category'] to the category you want to fetch.
+ * Separate multiple categories by ";".
+ * Other "external" variables that affect this function are:
+ * $serendipity['short_archives'] - Indicates if the short archive listing is wanted, without the full entry text
+ * $serendipity['range'] - If $range is not used, the time restriction is fetched from this array, which holds a start timestamp and end timestamp.
+ * $serendipity['GET']['category'] - The category ID to restrict fetching entries from
+ * $serendipity['GET']['viewAuthor'] - Only fetch entries by this author
+ * $serendipity['GET']['page'] - The page number to show entries, for pagination
*
- * @access public
- * @param
- * @return
+ * If you want to use any of these options, set the variable before calling serendipity_fetchEntries(). You can reset the variables to their original content after the function call, if you need to.
+ *
+ * Several options perform different commands when different types are passed, like the $range
+ * parameter which can either be a string or an array with START/END range.
+ *
+ * @access public
+ * @param mixed Restricts fetching entries to a specific timespan. Behaves differently depending on the type:
+ * Numeric:
+ * YYYYMMDD - Shows all entries from YYYY-MM-DD.
+ * If DD is "00", it will show all entries from that month.
+ * If DD is any other number, it will show entries of that specific day.
+ * 2-Dimensional Array:
+ * Key #0 - Specifies the start timestamp (unix seconds)
+ * Key #1 - Specifies the end timestamp (unix seconds)
+ * Other (null, 3-dimensional Array, ...):
+ * Entries newer than $modified_since will be fetched
+ * @param boolean Indicates if the full entry will be fetched (body+extended: TRUE), or only the body (FALSE).
+ * @param string Holds a "Y" or "X, Y" string that tells which entries to fetch. X is the first entry offset, Y is number of entries. If not set, the global fetchLimit will be applied (15 entries by default)
+ * @param boolean Indicates whether drafts should be fetched (TRUE) or not
+ * @param int Holds a unix timestamp to be used in conjunction with $range, to fetch all entries newer than this timestamp
+ * @param string Holds the SQL "ORDER BY" statement.
+ * @param string Can contain any SQL code to inject into the central SQL statement for fetching the entry
+ * @param boolean If set to TRUE, all entries will be fetched from scratch and any caching is ignored
+ * @param boolean If set to TRUE, all sticky entries will NOT be fetched.
+ * @return array Holds the super-array of all entries with all additional information
*/
-/**
-* Give it a range in YYYYMMDD format to gather the desired entries
-* (For february 2002 you would pass 200202 for all entries withing
-* two timestamps you would pass array(timestamp1,timestamp2)
-**/
function serendipity_fetchEntries($range = null, $full = true, $limit = '', $fetchDrafts = false, $modified_since = false, $orderby = 'timestamp DESC', $filter_sql = '', $noCache = false, $noSticky = false) {
global $serendipity;
}
/**
- * SHORT
+ * Fetch special entry data and attach it to a superarray of entries.
*
- * LONG
+ * Fetches all additional information like plugins, extended properties, additional categories for each entry.
*
- * @access public
- * @param
- * @return
- */
-/**
- * Attach special entry data to entry
+ * @access private
+ * @see serendipity_fetchEntries()
+ * @param array The array of entries where the output will be merged to (referenced)
+ * @return null
*/
function serendipity_fetchEntryData(&$ret) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Fetch a single entry by a specific condition
*
* @access public
- * @param
+ * @param string The column to compare $val against (like 'id')
+ * @param string The value of the colum $key to compare with (like '4711')
+ * @param boolean Indicates if the full entry will be fetched (body+extended: TRUE), or only the body (FALSE).
+ * @param string Indicates whether drafts should be fetched
* @return
*/
-/**
-* Fetches a specific entry
-**/
function serendipity_fetchEntry($key, $val, $full = true, $fetchDrafts = 'false') {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Fetches additional entry properties for a specific entry ID
*
* @access public
- * @param
- * @return
+ * @param int The ID of the entry to fetch additonal data for
+ * @return array The array of given properties to an entry
*/
function serendipity_fetchEntryProperties($id) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Fetch a list of available categories for an author
*
* @access public
- * @param
- * @return
+ * @param mixed If set, the list of categories will be fetched according to the author id. If not set, all categories will be fetched. If set to "all", then all categories will be fetched.
+ * @param string Restrict the list to be returned to a specific category NAME.
+ * @param string The SQL query part for ORDER BY of the categories
+ * @param string The ACL artifact condition. If set to "write" only categories will be shown that the author can write to. If set to "read", only categories will be show that the author can read or write to.
+ * @return array Returns the array of categories
*/
-/**
-* Fetches a users categories
-**/
function serendipity_fetchCategories($authorid = null, $name = null, $order = null, $artifact_mode = 'write') {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Rebuild the Category Nested Set tree
*
* @access public
- * @param
- * @return
+ * @see Based on http://www.sitepoint.com/article/hierarchical-data-database/1
+ * @param int The ID of the parent category to rebuild
+ * @param int The ID of the next left category
+ * @return int Returns the new ID
*/
function serendipity_rebuildCategoryTree($parent = 0, $left = 0) {
- // Based on http://www.sitepoint.com/article/hierarchical-data-database/1
global $serendipity;
$right = $left + 1;
}
/**
- * SHORT
- *
- * LONG
+ * Searches the list of entries by a specific term
*
+ * @todo: Allow to show results of staticpage plugins or others
* @access public
- * @param
- * @return
+ * @param string The searchterm (may contain wildcards)
+ * @param int Restrict the number of results [also uses $serendipity['GET']['page'] for pagination]
+ * @return array Returns the superarray of entries found
*/
-/**
-* Give it a raw searchstring, it'll search
-**/
function serendipity_searchEntries($term, $limit = '') {
global $serendipity;
}
/**
- * SHORT
+ * Creates the Footer below the entries, with pagination options and parses it to Smarty
*
- * LONG
+ * The list of total entries is calculated from the serendipity_getTotelEntries() function
*
* @access public
- * @param
- * @return
+ * @see serendipity_getTotalEntries()
+ * @return null
*/
function serendipity_printEntryFooter() {
global $serendipity;
}
}
+/**
+ * Calculates the amount of available entries.
+ *
+ * This function uses the SQL query portion of the central serendipity_fetchEntries() query
+ * and modifies it with different GROUP statements to calculate the number of entries.
+ *
+ * @access public
+ * @see serendipity_fetchEntries()
+ * @return int The number of total entries
+ */
function serendipity_getTotalEntries() {
global $serendipity;
}
/**
- * SHORT
+ * Passes the list of fetched entries from serendipity_fetchEntries() on to the Smarty layer
*
- * LONG
+ * This function contains all the core logic to group and prepare entries to be shown in your
+ * $entries.tpl template. It groups them by date, so that you can easily loop on the set of
+ * entries.
+ * This function is not only used for printing all entries, but also for printing individual
+ * entries.
+ * Several central Event hooks are executed here for the whole page flow, like header+footer data.
*
+ * @see serendipity_fetchEntries()
+ * @see serendipity_searchEntries()
* @access public
- * @param
+ * @param array The array of entries with all of its data
+ * @param boolean Toggle whether the extended portion of an entry is requested (via $serendipity['GET']['id'] single entry view)
+ * @param boolean Indicates if this is a preview
+ * @param string The name of the SMARTY block that this gets parsed into
+ * @param boolean Indicates whether the assigned smarty variables should be parsed
+ * @param boolean Indicates whether to apply footer/header event hooks
+ * @param boolean Indicates whether the pagination footer should be displayed
* @return
*/
-/**
-* Prints the entries you fetched with serendipity_fetchEntries/searchEntries in HTML.
-**/
function serendipity_printEntries($entries, $extended = 0, $preview = false, $smarty_block = 'ENTRIES', $smarty_fetch = true, $use_hooks = true, $use_footer = true) {
global $serendipity;
} // end function serendipity_printEntries
/**
- * SHORT
- *
- * LONG
+ * Deprecated: Delete some garbage when an entry was deleted, especially static pages
*
+ * @deprecated
* @access public
- * @param
- * @return
- */
-/**
-/**
- * purge a statically pregenerated entry
+ * @param int The deleted entry ID
+ * @param int A timestamp for the entry archive page
+ * @return null
*/
function serendipity_purgeEntry($id, $timestamp = null) {
global $serendipity;
}
/**
- * SHORT
+ * Inserts a new entry into the database or updates an existing entry
*
- * LONG
+ * Another central function, that parses, prepares and commits changes to an entry
*
* @access public
- * @param
- * @return
+ * @param array The new/modified entry data.
+ * @return mixed Integer with new entry ID if successfull, a string or array if error(s).
*/
-/**
-* Inserts a new entry into the database or updates an existing
-**/
function serendipity_updertEntry($entry) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Delete an entry and everything that belongs to it (comments)
*
* @access public
- * @param
- * @return
+ * @param int The Entry ID to delete
+ * @return mixed FALSE or NULL on error
*/
-/**
-* Deletes an entry and everything that belongs to it (comments, etc...) from
-* the database
-**/
function serendipity_deleteEntry($id) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
- *
- * @access public
- * @param
- * @return
- */
-/**
-* Print a list of categories
+* Return HTML containing a list of categories
*
* Prints a list of categories for use in forms, the sidebar, or whereever...
+*
+* @access public
* @param array An array of categories, typically gathered by serendipity_fetchCategories()
-* @param array Select
-* @param int Type
-* @param int ID
-* @param int Level
+* @param array An array which holds IDs which are meant to be selected within a HTML SELECT form field [used for recursion]
+* @param int The type of category list (0: HTML span list, 1/2: <option>s, 3: HTML Div list, 4: CSV data) to return
+* @param int The parent ID of a category [for recursion]
+* @param int The current nesting level [for recursion]
* @param string Tells the function, whether or not to display the XML button for each category.
* If empty, no links to the xml feeds will be displayed; If you want to, you can
* pass an image here (this setting is only used, when type==3).
}
/**
- * SHORT
- *
- * LONG
+ * Set category associations of a specific entry
*
* @access public
- * @param
- * @return
+ * @param int The ID of the entry
+ * @param array An array of category IDs that this entry is associated to.
+ * @return null
*/
function serendipity_updateEntryCategories($postid, $categories) {
global $serendipity;
}
/**
- * SHORT
+ * Gather an archive listing of older entries and passes it to Smarty
*
- * LONG
+ * The archives are created according to the current timestamp and show the current year.
+ * $serendipity['GET']['category'] is honoured like in serendipity_fetchEntries()
*
* @access public
- * @param
- * @return
+ * @return null
*/
function serendipity_printArchives() {
global $serendipity;
include_once(S9Y_INCLUDE_PATH . "include/functions_trackbacks.inc.php");\r
\r
/**\r
- * SHORT\r
+ * Prints the form for editing/creating new blog entries\r
*\r
- * LONG\r
+ * This is the core file where your edit form appears. The Heart Of Gold, so to say.\r
*\r
* @access public\r
- * @param\r
- * @return\r
+ * @param string The URL where the entry form is submitted to\r
+ * @param array An array of hidden input fields that should be passed on to the HTML FORM\r
+ * @param array The entry superarray with your entry's contents\r
+ * @param string Any error messages that might have occured on the last run\r
+ * @return null\r
*/\r
-/**\r
-* Prints a form to enter new diary entries\r
-**/\r
function serendipity_printEntryForm($targetURL, $hiddens = array(), $entry = array(), $errMsg = "") {\r
global $serendipity;\r
\r
# All rights reserved. See LICENSE file for licensing details
/**
- * SHORT
- *
- * LONG
+ * Check if an uploaded file is "evil"
*
* @access public
- * @param
- * @return
+ * @param string Input filename
+ * @return boolean
*/
function serendipity_isActiveFile($file) {
if (preg_match('@^\.@', $file)) {
}
/**
- * SHORT
+ * Gets a list of media items from our media database
*
* LONG
*
* @access public
- * @param
- * @return
+ * @param int The offset to start fetching media files
+ * @param int How many items to fetch
+ * @param int The number (referenced varaible) of fetched items
+ * @param string The "ORDER BY" sql part when fetching items
+ * @param string Order by DESC or ASC
+ * @param string Only fetch files from a specific directory
+ * @param string Only fetch specific filenames
+ * @return array Resultset of images
*/
-/**
-* Get a list of images
-**/
function serendipity_fetchImagesFromDatabase($start=0, $limit=0, &$total, $order = false, $ordermode = false, $directory = '', $filename = '') {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Fetch a specific media item from the mediadatabase
*
* @access public
- * @param
- * @return
+ * @param int The ID of an media item
+ * @return array The media info data
*/
function serendipity_fetchImageFromDatabase($id) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Update a media item
*
* @access public
- * @param
- * @return
+ * @param array An array of columns to update
+ * @param int The ID of an media item to update
+ * @return boolean
*/
function serendipity_updateImageInDatabase($updates, $id) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Delete a media item
*
* @access public
- * @param
+ * @param int The ID of a media item to delete
* @return
*/
function serendipity_deleteImage($id) {
}
/**
- * SHORT
- *
- * LONG
+ * Open a directory and fetch all existing media items
*
* @access public
- * @param
- * @return
+ * @param boolean deprecated
+ * @param int deprecated
+ * @param int deprecated
+ * @param array Array list of found items
+ * @param string sub-directory to investigate [recursive use]
+ * @return array List of media items
*/
-/**
-* Get a list of images
-**/
function serendipity_fetchImages($group = false, $start = 0, $end = 20, $images = '', $odir = '') {
global $serendipity;
}
/**
- * SHORT
+ * Inserts a hotlinked media file
*
- * LONG
+ * hotlinks are files that are only linked in your database, and not really stored on your server
*
* @access public
- * @param
- * @return
+ * @param string The filename to hotlink
+ * @param string The URL to hotlink with
+ * @param int The owner of the hotlinked media item
+ * @param int The timestamp of insertion (unix second)
+ * @param string A temporary filename for fetching the file to investigate it
+ * @return int The ID of the inserted media item
*/
function serendipity_insertHotlinkedImageInDatabase($filename, $url, $authorid = 0, $time = NULL, $tempfile = NULL) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Insert a media item in the database
*
* @access public
- * @param
- * @return
+ * @param string The filename of the media item
+ * @param string The path to the media item
+ * @param int The owner author of the item
+ * @param int The timestamp of when the media item was inserted
+ * @return int The new media ID
*/
function serendipity_insertImageInDatabase($filename, $directory, $authorid = 0, $time = NULL) {
global $serendipity;
/**
- * SHORT
+ * Create a thumbnail for an image
*
* LONG
*
* @access public
- * @param
- * @return
+ * @param string The input image filename
+ * @param string The directory to the image file
+ * @param array The target size of the thumbnail (2-dimensional array width,height)
+ * @return array The result size of the thumbnail
*/
-/**
-* Generate a thumbnail
-**/
function serendipity_makeThumbnail($file, $directory = '', $size = false) {
global $serendipity;
}
/**
- * SHORT
+ * Scale an image
*
* LONG
*
* @access public
- * @param
- * @return
+ * @param int The ID of an image
+ * @param int The target width
+ * @param int The target height
+ * @return true
*/
-/**
-* Scale an image (ignoring proportions)
-**/
function serendipity_scaleImg($id, $width, $height) {
global $serendipity;
}
/**
- * SHORT
+ * Rotate an image
*
* LONG
*
* @access public
- * @param
- * @return
+ * @param int The ID of an image
+ * @param int Number of degrees to rotate
+ * @return boolean
*/
-/**
- * Rotate an Image
- **/
function serendipity_rotateImg($id, $degrees) {
global $serendipity;
/**
- * SHORT
- *
- * LONG
+ * Creates thumbnails for all images in the upload dir
*
* @access public
- * @param
- * @return
+ * @return int Number of created thumbnails
*/
-/**
-* Creates thumbnails for all images in the upload dir
-**/
function serendipity_generateThumbs() {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Guess the MIME type of a file
*
* @access public
- * @param
- * @return
+ * @param string Filename extension
+ * @return string Mimetype
*/
function serendipity_guessMime($extension) {
$mime = '';
}
/**
- * SHORT
+ * Check all existing thumbnails if they are the right size, insert missing thumbnails
*
* LONG
*
* @access public
- * @param
- * @return
+ * @return int Number of updated thumbnails
*/
-/**
-* Creates thumbnails for all images in the upload dir
-**/
function serendipity_syncThumbs() {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Wrapper for GDLib functions
*
* @access public
- * @param
- * @return
+ * @param string Filename to operate on
+ * @return string Functionname to execute
*/
function serendipity_functions_gd($infilename) {
if (!function_exists('imagecopyresampled')) {
}
/**
- * SHORT
- *
- * LONG
+ * Rotate an image (GDlib)
*
* @access public
- * @param
- * @return
+ * @param string Source Filename to rotate
+ * @param string Target file
+ * @param int Degress to rotate
+ * @return array New width/height of the image
*/
function serendipity_rotate_image_gd($infilename, $outfilename, $degrees)
{
/**
- * SHORT
- *
- * LONG
+ * Resize an image (GDLib)
*
* @access public
- * @param
- * @return
+ * @param string Source Filename to resize
+ * @param string Target file
+ * @param int New width
+ * @return int New height (can be autodetected)
+ * @return array New image size
*/
function serendipity_resize_image_gd($infilename, $outfilename, $newwidth, $newheight=null)
{
}
/**
- * SHORT
- *
- * LONG
+ * Calculate aspect ratio of an image
*
* @access public
- * @param
- * @return
+ * @param int Image width
+ * @param int Image height
+ * @param int Target width
+ * @return int Target height
*/
function serendipity_calculate_aspect_size($width, $height, $newwidth) {
}
/**
- * SHORT
- *
- * LONG
+ * Display the list of images in our database
*
* @access public
- * @param
- * @return
+ * @param int The current page number
+ * @param string The HTML linebreak to use after a row of images
+ * @param boolean Should the toolbar for editing media files be shown?
+ * @param string The URL to use for pagination
+ * @param boolean Show the "upload media item" feature?
+ * @param boolean Restrict viewing images to a specific directory
+ * @return null
*/
function serendipity_displayImageList($page = 0, $lineBreak = NULL, $manage = false, $url = NULL, $show_upload = false, $limit_path = NULL) {
global $serendipity;
} // End serendipity_displayImageList()
/**
- * SHORT
- *
- * LONG
+ * Check if a media item is an image
*
* @access public
- * @param
- * @return
+ * @param array File information
+ * @param boolean Use a strict check that does not list PDFs as an image?
+ * @return boolean True if the file is an image
*/
function serendipity_isImage(&$file, $strict = false) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Recursively delete a directory tree
*
* @access public
- * @param
- * @return
+ * @param string The originating directory
+ * @param string The subdirectory
+ * @param boolean Force deleting an directory even if there are files left in it?
+ * @return true
*/
function serendipity_killPath($basedir, $directory = '', $forceDelete = false) {
static $n = "<br />\n";
/**
- * SHORT
- *
- * LONG
+ * Recursively walk a directory tree
*
* @access public
- * @param
- * @return
+ * @param string The core directory
+ * @param string The subdirectory
+ * @param boolean Only return directories instead of files as well?
+ * @param string A regexp patter to include files
+ * @param int Level of nesting (recursive use)
+ * @param int The maximum level of nesting (recursive use)
+ * @return array Array of files/directories
*/
function serendipity_traversePath($basedir, $dir='', $onlyDirs=true, $pattern = NULL, $depth = 1, $max_depth = null) {
}
/**
- * SHORT
- *
- * LONG
+ * Delete a directory with all its files
*
* @access public
- * @param
+ * @param string The directory to delete
* @return
*/
function serendipity_deletePath($dir) {
}
/**
- * SHORT
- *
- * LONG
+ * Check if a entered HTTP upload path is valid
*
* @access public
- * @param
- * @return
+ * @param string The input filename
+ * @param boolean Shall all paths be stripped?
+ * @param boolean Shall a trailing slash be appended?
+ * @return string The condom-wrapped path/file info
*/
function serendipity_uploadSecure($var, $strip_paths = true, $append_slash = false) {
$var = preg_replace('@[^0-9a-z\._/-]@i', '', $var);
}
/**
- * SHORT
- *
- * LONG
+ * Get the imagesize for a file
*
* @access public
- * @param
- * @return
+ * @param string The filename of the image
+ * @param string The mimetype of an image (can be autodetected)
+ * @param string The file extension of an image
+ * @return array The width/height of the file
*/
function serendipity_getimagesize($file, $ft_mime = '', $suf = '') {
if (empty($ft_mime) && !empty($suf)) {
}
/**
- * SHORT
- *
- * LONG
+ * Get the available fields of the media database
*
* @access public
- * @param
- * @return
+ * @return array Array with available, sortable fields
*/
function serendipity_getImageFields() {
return array(
}
/**
- * SHORT
- *
- * LONG
+ * Escape a shell argument for imagemagick use
*
* @access public
- * @param
- * @return
+ * @param string Input argument
+ * @return string Output argument
*/
function serendipity_escapeshellarg($string) {
return escapeshellarg(str_replace('%', '', $string));
/**
- * SHORT
- *
- * LONG
+ * Convert a PHP Ini setting to a boolean flag
*
* @access public
- * @param
- * @return
+ * @param mixed input variable
+ * @return boolean output variable
*/
function serendipity_ini_bool($var) {
return ($var === 'on' || $var == '1');
}
/**
- * SHORT
- *
- * LONG
+ * convert a size value from a PHP.ini to a bytesize
*
* @access public
- * @param
- * @return
+ * @param string size value from PHP.ini
+ * @return string bytesize
*/
function serendipity_ini_bytesize($val) {
if ( $val == '' )
}
/**
- * SHORT
- *
- * LONG
+ * Update the serendipity_config_local.inc.php file with core information
*
* @access public
- * @param
- * @return
+ * @param string Database name
+ * @param string Database prefix
+ * @param string Database host
+ * @param string Database user
+ * @param string Datapase Passwort
+ * @param string Database type
+ * @param string Use persistent connections?
+ * @param array An array of additional variables to be put into the config file
+ * @return true
*/
function serendipity_updateLocalConfig($dbName, $dbPrefix, $dbHost, $dbUser, $dbPass, $dbType, $dbPersistent, $privateVariables = null) {
global $serendipity;
}
/**
- * SHORT
+ * Setup the core database tables
*
- * LONG
+ * Creates the needed tables - beware, they will be empty and need to be stuffed with
+ * default templates and such...
*
* @access public
- * @param
- * @return
+ * @return null
*/
-/**
-* Creates the needed tables - beware, they will be empty and need to be stuffed with
-* default templates and such...
-*/
function serendipity_installDatabase() {
global $serendipity;
$queries = serendipity_parse_sql_tables(S9Y_INCLUDE_PATH . 'sql/db.sql');
}
/**
- * SHORT
- *
- * LONG
+ * Check a default value of a config item from the configuration template files
*
* @access public
- * @param
- * @return
+ * @param string Name of the config item to check
+ * @param string The default value, if none is found
+ * @param boolean If true, it's the personal config template, if false its the global config template
+ * @param string Protected fields will not be echo'd in the HTML form
+ * @return string The default value
*/
function serendipity_query_default($optname, $default, $usertemplate = false, $type = 'string') {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Parse a configuration template file
*
* @access public
- * @param
- * @return
+ * @param string Path to the s9y configuration template file
+ * @param array An array of config areas/sections that shall be returned from the template
+ * @param array Restrict the return of template variables to items containing a specific flag
+ * @return array An array with configuration items, keys and values
*/
function serendipity_parseTemplate($filename, $areas = null, $onlyFlags=null) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Replace some variables within config item values with the right values
*
* @access public
- * @param
- * @return
+ * @param string Input string
+ * @return string Output string
*/
function serendipity_replaceEmbeddedConfigVars ($s) {
return str_replace(
}
/**
- * SHORT
- *
- * LONG
+ * Preprocess the configuration value and put it into a HTML output field (radio, password, text, select, ...)
*
* @access public
- * @param
- * @return
+ * @param string The type of the configuration item
+ * @param string The name of the configuration item
+ * @param string The current value of the configuration item
+ * @param string The default value of the configuration item
+ * @return null
*/
function serendipity_guessInput($type, $name, $value='', $default='') {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Parses the configuration array and displays the configuration screen
*
* @access public
- * @param
- * @return
+ * @param array Configuration superarray
+ * @param array The previous values submitted by the user
+ * @param boolean If true, no HTML FORM container will be emitted
+ * @param boolean If true, the configuration sections will all be folded
+ * @param boolean If true, the user can turn config sections on and off
+ * @return null
*/
function serendipity_printConfigTemplate($config, $from = false, $noForm = false, $folded = true, $allowToggle = true) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Parse .sql files for use within Serendipity, query by query
*
* @access public
- * @param
- * @return
+ * @param string The filename of the SQL file
+ * @return array An array of queries to execute
*/
function serendipity_parse_sql_tables($filename) {
$in_table = 0;
}
/**
- * SHORT
- *
- * LONG
+ * Check the serendipity Installation for problems, during installation
*
* @access public
- * @param
- * @return
+ * @return boolean Errors encountered?
*/
function serendipity_checkInstallation() {
global $serendipity, $umask;
}
/**
- * SHORT
- *
- * LONG
+ * Create the files needed by Serendipity [htaccess/serendipity_config_local.inc.php]
*
* @access public
- * @param
- * @return
+ * @param string Path to the serendipity directory
+ * @return true
*/
function serendipity_installFiles($serendipity_core = '') {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Check the flags of a configuration item for their belonging into a template
*
* @access public
- * @param
- * @return
+ * @param array An item to check
+ * @param array The area (configuration|local) where the config item might be displayed
+ * @return boolean
*/
-/* Takes the item data from a config var, and checks the flags against the current area */
function serendipity_checkConfigItemFlags(&$item, $area) {
if ( in_array('nosave', $item['flags']) ) {
}
/**
- * SHORT
- *
- * LONG
+ * When paths or other options are changed in the s9y configuration, update the core files
*
* @access public
- * @param
- * @return
+ * @return boolean
*/
function serendipity_updateConfiguration() {
global $serendipity, $umask;
}
/**
- * SHORT
- *
- * LONG
+ * Get the root directory of Serendipity
*
* @access public
- * @param
- * @return
+ * @return string The root directory of Serendipity
*/
function serendipity_httpCoreDir() {
if (!empty($_SERVER['SCRIPT_FILENAME']) && substr(php_sapi_name(), 0, 3) != 'cgi') {
}
/**
- * SHORT
- *
- * LONG
+ * Delete obsolete files from Serendipity
*
* @access public
- * @param
- * @return
+ * @param array List of files to remove (backup is tried)
+ * @return boolean
*/
function serendipity_removeFiles($files = null) {
global $serendipity, $errors;
}
/**
- * SHORT
- *
- * LONG
+ * Get the real directory of this function file
*
* @access public
- * @param
- * @return
+ * @param string A filename to strip extra paths from
+ * @return string The real directory name
*/
function serendipity_getRealDir($file) {
$dir = str_replace( "\\", "/", dirname($file));
}
/**
- * SHORT
+ * Try to detect if apache URL rewriting is available
*
- * LONG
+ * This function makes a dummy HTTP request and sees if it works
*
* @access public
- * @param
- * @return
+ * @param string The default option when rewrite fails
+ * @return string The best preference option for URL rewriting
*/
function serendipity_check_rewrite($default) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Remove old configuration values that are no longer used by Serendipity
*
* @access public
- * @param
- * @return
+ * @return null
*/
function serendipity_removeObsoleteVars() {
global $serendipity;
# All rights reserved. See LICENSE file for licensing details
/**
- * SHORT
- *
- * LONG
+ * Converts a string into a filename that can be used safely in HTTP URLs
*
* @access public
- * @param
- * @return
+ * @param string input string
+ * @param boolean Shall dots in the filename be removed? (Required for certain regex rules)
+ * @return string output string
*/
function serendipity_makeFilename($str, $stripDots = false) {
static $from = array(
}
/**
- * SHORT
- *
- * LONG
+ * Initialize permalinks, if the user did not specify those yet
*
* @access public
- * @param
- * @return
+ * @return null
*/
function serendipity_initPermalinks() {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Build an array containing all regular expression permalinks
*
* @access public
- * @param
- * @return
+ * @param boolean If set to true, the list of permalinks will be returned. If false, all permalinks will be applied as Constants
+ * @return array (conditional on $return) List of permalinks
*/
function &serendipity_permalinkPatterns($return = false) {
global $serendipity;
}
/**
- * SHORT
+ * Search the reference to a specific permalink
*
- * LONG
+ * This query will show the Entry/Category/Author-ID to a permalink, if that permalink
+ * does not contain %id%.
*
* @access public
- * @param
- * @return
+ * @param string The permalink configuration string
+ * @param string The URL to check
+ * @param string A default return value if no permalink is found
+ * @param string The type of a permalink (entry|category|author)
+ * @return string The ID of the permalink type
*/
function serendipity_searchPermalink($struct, $url, $default, $type = 'entry') {
global $serendipity;
}
/**
- * SHORT
+ * Create a permalink for the given input data
*
- * LONG
+ * You can pass an entry array, or an author array to this function
+ * and then get a permalink valid for that array
*
* @access public
- * @param
- * @return
+ * @param array The input data used for building the permalink
+ * @param string The type of the permalink (entry|category|author)
+ * @return string The permalink
*/
function serendipity_getPermalink(&$data, $type = 'entry') {
switch($type) {
}
/**
- * SHORT
- *
- * LONG
+ * Update a permalink with new data
*
* @access public
- * @param
- * @return
+ * @param array The input data used for building the permalink
+ * @param string The type of the permalink (entry|category|author)
+ * @return string The database result
*/
function serendipity_updatePermalink(&$data, $type = 'entry') {
global $serendipity;
}
/**
- * SHORT
+ * Insert a new Permalink into the database for latter retrieval
*
- * LONG
+ * This function is basically only used if you have no '%id%' value in your permalink config.
*
* @access public
- * @param
- * @return
+ * @param array The input data used for building the permalink
+ * @param string The type of the permalink (entry|category|author)
+ * @return string The permalink
*/
function serendipity_insertPermalink(&$data, $type = 'entry') {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Build all permalinks for all current entries, authors and categories
*
* @access public
- * @param
- * @return
+ * @return null
*/
function serendipity_buildPermalinks() {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Uses logic to figure out how the URI should look, based on current rewrite rule
*
* @access public
- * @param
- * @return
+ * @param string The URL part that you want to format to "pretty urls"
+ * @param string The path/URL you want as a prefix for your pretty URL
+ * @param boolean If set to TRUE this will bypass all pretty URLs and format the link so that it works everywhere
+ * @return string The rewritten URL
*/
-/* 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
+ * Format a permalink according to the configured format
*
* @access public
- * @param
- * @return
+ * @param string The URL format to use
+ * @param array The input data to format a permalink
+ * @param string The type of the permalink (entry|category|author)
+ * @return string The formatted permalink
*/
function serendipity_makePermalink($format, $data, $type = 'entry') {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Convert a permalink configuration into a regular expression for use in rewrite rules
*
* @access public
- * @param
- * @return
+ * @param string The URL format to use
+ * @param string The type of the permalink (entry|category|author)
+ * @return string The regular expression to a permalink URL
*/
function serendipity_makePermalinkRegex($format, $type = 'entry') {
static $entryKeys = array('%id%', '%title%', '%day%', '%month%', '%year%');
}
/**
- * SHORT
- *
- * LONG
+ * Create a permalink for an entry permalink
*
* @access public
- * @param
- * @return
+ * @param int The entry ID
+ * @param string The entry title
+ * @param string The base URL/path key
+ * @param boolean Shall the link be rewritten to a pretty URL?
+ * @param array Additional entry data
+ * @return string The permalink
*/
function serendipity_archiveURL($id, $title, $key = 'baseURL', $checkrewrite = true, $entryData = null) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Create a permalink for an authors permalink
*
* @access public
- * @param
- * @return
+ * @param array The author data
+ * @param string The base URL/path key
+ * @param boolean Shall the link be rewritten to a pretty URL?
+ * @return string The permalink
*/
function serendipity_authorURL(&$data, $key = 'baseURL', $checkrewrite = true) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Create a permalink for an category permalink
*
* @access public
- * @param
- * @return
+ * @param array The category data
+ * @param string The base URL/path key
+ * @param boolean Shall the link be rewritten to a pretty URL?
+ * @return string The permalink
*/
function serendipity_categoryURL(&$data, $key = 'baseURL', $checkrewrite = true) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Create a permalink for an RSS feed permalink
*
* @access public
- * @param
- * @return
+ * @param array The entry data
+ * @param string The base URL/path key
+ * @param boolean Shall the link be rewritten to a pretty URL?
+ * @return string The permalink
*/
function serendipity_feedCategoryURL(&$data, $key = 'baseURL', $checkrewrite = true) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Create a permalink for an RSS authors' feed permalink
*
* @access public
- * @param
- * @return
+ * @param array The entry data
+ * @param string The base URL/path key
+ * @param boolean Shall the link be rewritten to a pretty URL?
+ * @return string The permalink
*/
function serendipity_feedAuthorURL(&$data, $key = 'baseURL', $checkrewrite = true) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Create a permalink for an archive date
*
* @access public
- * @param
- * @return
+ * @param string The archive's date
+ * @param boolean If true, only summary archive
+ * @param string The base URL/path key
+ * @return string The permalink
*/
function serendipity_archiveDateUrl($range, $summary=false, $key='baseURL') {
return serendipity_rewriteURL(PATH_ARCHIVES . '/' . $range . ($summary ? '/summary' : '') . '.html', $key);
}
/**
- * SHORT
- *
- * LONG
+ * Returns the URL to the current page that is being viewed
*
* @access public
- * @param
- * @return
+ * @return string the current URL
*/
function serendipity_currentURL() {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Get the URI Arguments for the current HTTP Request
*
* @access public
- * @param
+ * @param string The URI made for this request
+ * @param boolean If enabled, then no Dots are allowed in the URL for permalinks
* @return
*/
function serendipity_getUriArguments($uri, $wildcard = false) {
# All rights reserved. See LICENSE file for licensing details
/**
- * SHORT
+ * Parses entries to display them for RSS/Atom feeds to be passed on to generic Smarty templates
*
- * LONG
+ * This function searches for existing RSS feed template customizations. As long as a template
+ * with the same name as the $version variable exists, it will be emitted.
*
* @access public
- * @param
+ * @see serendipity_fetchEntries(), rss.php
+ * @param array A superarray of entries to output
+ * @param string The version/type of a RSS/Atom feed to display (atom1_0, rss2_0 etc)
+ * @param boolean If true, this is a comments feed. If false, it's an Entry feed.
+ * @param boolean Indicates if this feed is a fulltext feed (true) or only excercpt (false)
+ * @param boolean Indicates if E-Mail addresses should be shown (true) or hidden (false)
* @return
*/
function serendipity_printEntries_rss(&$entries, $version, $comments = false, $fullFeed = false, $showMail = true) {
# All rights reserved. See LICENSE file for licensing details
/**
- * SHORT
- *
- * LONG
+ * Fetch a list of trackbacks for an entry
*
* @access public
- * @param
+ * @param int The ID of the entry
+ * @param string How many trackbacks to show
+ * @param boolean If true, also non-approved trackbacks will be shown
* @return
*/
function serendipity_fetchTrackbacks($id, $limit = null, $showAll = false) {
}
/**
- * SHORT
+ * Show trackbacks for an entry
*
* LONG
*
* @access public
- * @param
+ * @param array The superarray of trackbacks to display
* @return
*/
function serendipity_printTrackbacks($trackbacks) {
}
/**
- * SHORT
- *
- * LONG
+ * Smarty: Fetch a smarty block and pass it on to Serendipity Templates
*
* @access public
- * @param
- * @return
+ * @param string The name of the block to parse data into ("COMMENTS" - virtual variable like {$COMMENTS})
+ * @param string The name of the template file to fetch. Only filename, the path is auto-detected
+ * @param boolean If true, the output of the smarty parser will be echoed instead of invisibly treated
+ * @return string The parsed HTML code
*/
function &serendipity_smarty_fetch($block, $file, $echo = false) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Smarty Modifier: Check if a string is not empty and prepend a prefix in that case. Else, leave empty
*
* @access public
- * @param
- * @return
+ * @param string The input string to check
+ * @param string The prefix to prepend, if $string is not empty
+ * @return string The return string
*/
function serendipity_emptyPrefix($string, $prefix = ': ') {
return (!empty($string) ? $prefix . htmlspecialchars($string) : '');
}
/**
- * SHORT
- *
- * LONG
+ * Smarty Function: Be able to include the output of a sidebar plugin within a smarty template
*
* @access public
- * @param
- * @return
+ * @param array Smarty parameter input array:
+ * class: The classname of the plugin to show
+ * id: An ID of a plugin to show
+ * side: The side of a plugin to show (left|right|hidden)
+ * negate: Revert previous filters
+ * @param object Smarty object
+ * @return string The Smarty HTML response
*/
function serendipity_smarty_showPlugin($params, &$smarty) {
global $serendipity;
}
/**
- * SHORT
+ * Smarty Function: Be able to execute the hook of an event plugin and return its output
*
- * LONG
+ * Listens to specific serendipity global variables:
+ * $serendipity['skip_smarty_hooks'] - If TRUE, no plugins will be executed at all
+ * $serendipity['skip_smarty_hook'] - Can be set to an array of plugin hooks to NOT execute
*
* @access public
- * @param
- * @return
+ * @param array Smarty parameter input array:
+ * hook: The name of the event hook
+ * hookAll: boolean whether unknown hooks shall be executed
+ * data: The $eventData to an event plugin
+ * addData: the $addData to an event plugin
+ * @param object Smarty object
+ * @return null
*/
function serendipity_smarty_hookPlugin($params, &$smarty) {
global $serendipity;
/**
- * SHORT
- *
- * LONG
+ * Smarty Function: Prints a list of sidebar plugins
*
* @access public
- * @param
- * @return
+ * @param array Smarty parameter input array:
+ * side: The plugin side to show (left|right|hidden)
+ * @param object Smarty object
+ * @return string The HTML code of a plugin's output
*/
function serendipity_smarty_printSidebar($params, &$smarty) {
if ( !isset($params['side']) ) {
}
/**
- * SHORT
- *
- * LONG
+ * Smarty Function: Get the full path to a template file
*
* @access public
- * @param
- * @return
+ * @param array Smarty parameter input array:
+ * file: The filename you want to include (any file within your template directry or the 'default' template if not found)
+ * @param object Smarty object
+ * @return string The requested filename with full path
*/
function serendipity_smarty_getFile($params, &$smarty) {
if ( !isset($params['file']) ) {
}
/**
- * SHORT
- *
- * LONG
+ * Smarty Function: Get a permalink for an entry
*
* @access public
- * @param
- * @return
+ * @param array Smarty parameter input array:
+ * entry: $entry data to pull title etc. out of
+ * is_comments: Whether a permalink for a comment feed should be embedded
+ * @param object Smarty object
+ * @return string The permalink
*/
function serendipity_smarty_rss_getguid($params, &$smarty) {
if ( !isset($params['entry']) ) {
}
/**
- * SHORT
- *
- * LONG
+ * Smarty Modifier: Format a timestamp
*
* @access public
- * @param
+ * @param int The timestamp to format (unix seconds)
+ * @param string The strftime() format options on how to format this string
+ * @param boolean Shall timezone conversions be applied?
* @return
*/
function serendipity_smarty_formatTime($timestamp, $format, $useOffset = true) {
}
/**
- * SHORT
- *
- * LONG
+ * Smarty Function: Show comments to an entry
*
* @access public
- * @param
- * @return
+ * @param array Smarty parameter input array:
+ * entry: The $entry data
+ * mode: The default viewmode (threaded/linear)
+ * @param object Smarty object
+ * @return string The HTML code with the comments
*/
function &serendipity_smarty_printComments($params, &$smarty) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Smarty Function: Show Trackbacks
*
* @access public
- * @param
+ * @param array Smarty parameter input array:
+ * entry: The $entry data for the trackbacks
+ * @param object Smarty object
* @return
*/
function serendipity_smarty_printTrackbacks($params, &$smarty) {
}
/**
- * SHORT
- *
- * LONG
+ * Smarty Prefilter: Replace constants to direkt $smarty.const. access
*
* @access public
- * @param
+ * @param string Template source content
+ * @param object Smarty object
* @return
*/
function &serendipity_replaceSmartyVars(&$tpl_source, &$smarty) {
}
/**
- * SHORT
- *
- * LONG
+ * Initialize the Smarty framework for use in Serendipity
*
* @access public
- * @param
- * @return
+ * @return null
*/
function serendipity_smarty_init() {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Purge compiled Smarty Templates
*
* @access public
- * @param
- * @return
+ * @return null
*/
-/* Nukes all Smarty compiled templates and cache */
function serendipity_smarty_purge() {
global $serendipity;
}
/**
- * SHORT
+ * Shut down the Smarty Framework, output all parsed data
*
- * LONG
+ * This function is meant to be used in embedded installations, like in Gallery.
+ * Function can be called from foreign applications. ob_start() needs to
+ * have been called before, and will be parsed into Smarty here
*
* @access public
- * @param
- * @return
+ * @param string The path to Serendipity
+ * @return null
*/
-/* 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 = '') {
global $serendipity;
# All rights reserved. See LICENSE file for licensing details
/**
- * SHORT
- *
- * LONG
+ * Check a HTTP response if it is a valid XML trackback response
*
* @access public
- * @param
- * @return
- */
-/**
- * validate trackback response
+ * @param string HTTP Response string
+ * @return mixed Boolean or error message
*/
function serendipity_trackback_is_success($resp) {
if (preg_match('@<error>(\d+)</error>@', $resp, $matches)) {
}
/**
- * SHORT
- *
- * LONG
+ * Perform a HTTP query for autodiscovering a pingback URL
*
* @access public
- * @param
+ * @param string (deprecated) The URL to try autodiscovery
+ * @param string The response of the original URL
* @return
*/
function serendipity_pingback_autodiscover($loc, $body) {
}
/**
- * SHORT
- *
- * LONG
+ * Send a track/pingback ping
*
* @access public
- * @param
- * @return
- */
-/**
- * Send a trackback ping
+ * @param string The URL to send a trackback to
+ * @param string The XML data with the trackback contents
+ * @return string Reponse
*/
function _serendipity_send($loc, $data) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Autodiscover a trackback location URL
*
* @access public
- * @param
- * @return
+ * @param string The HTML of the source URL
+ * @param string The source URL
+ * @param string The URL of our blog
+ * @param string The author of our entry
+ * @param string The title of our entry
+ * @param string The text of our entry
+ * @param string A comparsion URL
+
+ * @return string Response
*/
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)) {
}
/**
- * SHORT
- *
- * LONG
+ * Open a URL and autodetect contained ping/trackback locations
*
* @access public
- * @param
- * @return
+ * @param string The URL to autodetect/try
+ * @param string The URL to our blog
+ * @param string The author of our entry
+ * @param string The title of our entry
+ * @param string The body of our entry
+ * @return null
*/
function serendipity_reference_autodiscover($loc, $url, $author, $title, $text) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Receive a trackback
*
* @access public
- * @param
- * @return
+ * @param int The ID of our entry
+ * @param string The title of the foreign blog
+ * @param string The URL of the foreign blog
+ * @param string The name of the foreign blog
+ * @param string The excerpt text of the foreign blog
+ * @return true
*/
function add_trackback ($id, $title, $url, $name, $excerpt) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Receive a pingback
*
* @access public
- * @param
- * @return
+ * @param int The entryid to receive a pingback for
+ * @param string The foreign postdata to add
+ * @return boolean
*/
function add_pingback ($id, $postdata) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Create an excerpt for a trackback to send
*
* @access public
- * @param
- * @return
- */
-/**
- * Cut text
+ * @param string Input text
+ * @return string Output text
*/
function serendipity_trackback_excerpt($text) {
return substr(strip_tags($text), 0, 255);
}
/**
- * SHORT
- *
- * LONG
+ * Report success of a trackback
*
* @access public
- * @param
- * @return
*/
function report_trackback_success () {
print '<?xml version="1.0" encoding="iso-8859-1"?>' . "\n";
}
/**
- * SHORT
- *
- * LONG
+ * Report failure of a trackback
*
* @access public
- * @param
- * @return
*/
function report_trackback_failure () {
print '<?xml version="1.0" encoding="iso-8859-1"?>' . "\n";
}
/**
- * SHORT
- *
- * LONG
+ * Return success of a pingback
*
* @access public
- * @param
- * @return
*/
function report_pingback_success () {
print '<?xml version="1.0"?>' . "\n";
}
/**
- * SHORT
- *
- * LONG
+ * Return failure of a pingback
*
* @access public
- * @param
- * @return
*/
function report_pingback_failure () {
print '<?xml version="1.0"?>' . "\n";
}
/**
- * SHORT
+ * Search through link body, and automagically send a trackback ping.
*
- * LONG
+ * This is the trackback starter function that searches your text and sees if any
+ * trackback URLs are in there
*
* @access public
- * @param
+ * @param int The ID of our entry
+ * @param string The author of our entry
+ * @param string The title of our entry
+ * @param string The text of our entry
* @return
*/
-/**
- * search through link body, and automatically send a trackback ping.
- */
function serendipity_handle_references($id, $author, $title, $text) {
global $serendipity;
}
/**
- * SHORT
+ * Wrapper for multibyte string operations
*
- * LONG
+ * Multibyte string functions wrapper:
+ * strlen(), strpos(), strrpos(), strtolower(), strtoupper(), substr(), ucfirst()
*
* @access public
- * @param
- * @return
+ * @param mixed Any input array, dynamically evaluated for best emulation
+ * @return mixed
*/
- // Multibyte string functions wrapper:
- // strlen(), strpos(), strrpos(), strtolower(), strtoupper(), substr(), ucfirst()
function serendipity_mb() {
static $mbstring = null;
class serendipity_plugin_api {
/**
- * SHORT
- *
- * LONG
+ * Register the default list of plugins for installation.
*
* @access public
- * @param
- * @return
+ * @return null
*/
function register_default_plugins()
{
}
/**
- * SHORT
- *
- * LONG
+ * Removes a plugin by it's instance name
*
* @access public
- * @param
- * @return
+ * @param string The name of the plugin id ("serendipity_plugin_xxx:1232132fsdf")
+ * @return null
*/
function remove_plugin_instance($plugin_instance_id)
{
}
/**
- * SHORT
- *
- * LONG
+ * Removes an empty plugin configuration value
*
* @access public
- * @param
- * @return
+ * @param string The name of the plugin id ("serendipity_plugin_xxx:1232132fsdf")
+ * @param array An array of configuration item names
+ * @return null
*/
function remove_plugin_value($plugin_instance_id, $where)
{
}
/**
- * SHORT
+ * Retrieve a list of available plugin classes
*
- * LONG
+ * This function searches through all directories and loaded internal files and tries
+ * to detect the serendipity plugins.
*
* @access public
- * @param
+ * @param boolean If true, only event plugins will be searched. If false, sidebar plugins will be searched.
* @return
*/
- /* Retrieves a list of available plugins */
function &enum_plugin_classes($event_only = false)
{
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Traverse a specific directory and search if a serendipity plugin exists there.
*
* @access public
- * @param
+ * @param string The path to start from (usually '.')
+ * @param array A referenced array of currently found classes
+ * @param boolean If true, only event plugins will be searched. If false, only sidebar plugins will be searched.
+ * @param string The maindir where we started searching from [for recursive use]
* @return
*/
function traverse_plugin_dir($ppath, &$classes, $event_only, $maindir = '') {
}
/**
- * SHORT
- *
- * LONG
+ * Returns a list of currently installed plugins
*
* @access public
- * @param
- * @return
+ * @param string The filter for plugins (left|right|hidden|event)
+ * @return array The list of plugins
*/
function get_installed_plugins($filter = '*') {
$plugins = serendipity_plugin_api::enum_plugins($filter);
}
/**
- * SHORT
- *
- * LONG
+ * Searches for installed plugins based on specific conditions
*
* @access public
- * @param
- * @return
+ * @param string The filter for plugins (left|right|hidden|event)
+ * @param boolean If true, the filtering logic will be reversed an all plugins that are NOT part of the filter will be returned
+ * @param string Filter by a specific classname (like 'serendipity_plugin_archives'). Can take SQL wildcards.
+ * @param string Filter by a specific plugin instance id
+ * @return array Returns the associative array of found plugins in the database
*/
- /* Retrieves a list of plugin instances */
function enum_plugins($filter = '*', $negate = false, $classname = null, $id = null)
{
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Count the number of plugins to which the filter criteria matches
*
* @access public
- * @param
- * @return
+ * @param string The filter for plugins (left|right|hidden|event)
+ * @param boolean If true, the filtering logic will be reversed an all plugins that are NOT part of the filter will be evaluated
+ * @return int Number of plugins that were found.
*/
- /* Retrieves a list of plugin instances */
function count_plugins($filter = '*', $negate = false)
{
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Detect the filename to use for a specific plugin
*
* @access public
- * @param
- * @return
+ * @param string The name of the plugin ('serendipity_event_archive')
+ * @param string The path to the plugin file (if empty, the current path structure will be used.)
+ * @param string If an instance ID is passed this means, the plugin to be loaded is internally available
+ * @return string Returns the filename to include for a specific plugin
*/
function includePlugin($name, $pluginPath = '', $instance_id = '') {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Returns the plugin class name by a plugin instance ID
*
* @access public
- * @param
- * @return
+ * @param string The ID of a plugin
+ * @param boolean If true, the plugin is a internal plugin (prefixed with '@')
+ * @return string The classname of the plugin
*/
function getClassByInstanceID($instance_id, &$is_internal) {
$instance = explode(':', $instance_id);
}
/**
- * SHORT
- *
- * LONG
+ * Auto-detect a plugin and see if the file information is given, and if not, detect it.
*
* @access public
- * @param
- * @return
+ * @param string The ID of a plugin to load
+ * @param string A reference variable that will hold the class name of the plugin (do not pass manually)
+ * @param string A reference variable that will hold the path to the plugin (do not pass manually)
+ * @return string Returns the filename of a plugin to load
*/
/* Probes for the plugin filename */
function probePlugin($instance_id, &$class_name, &$pluginPath) {
}
/**
- * SHORT
- *
- * LONG
+ * Instantiates a plugin class
*
* @access public
- * @param
+ * @param string The ID of the plugin to load
+ * @param int The owner of the plugin (can be autodetected)
+ * @param string The path to a plugin (can be autodetected)
+ * @param string The filename of a plugin (can be autodetected)
* @return
*/
- /* Creates an instance of a named plugin */
function &load_plugin($instance_id, $authorid = null, $pluginPath = '', $pluginFile = null) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Gets cached properties/information about a specific plugin, auto-loads a cache of all plugins
*
* @access public
- * @param
- * @return
+ * @param string The filename of the plugin to get information about
+ * @param array A referenced array that holds information about the plugin instance (self::load_plugin() response)
+ * @param type The type of the plugin (local|spartacus|...)
+ * @return array Information about the plugin
*/
function &getPluginInfo(&$pluginFile, &$class_data, $type) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Set cache information about a plugin
*
* @access public
- * @param
+ * @param mixed Either an plugin object or a plugin information array that holds the information about the plugin
+ * @param string The filename of the plugin
+ * @param object The property bag object bundled with the plugin
+ * @param array Previous/additional information about the plugin
+ * @param string The location/type of a plugin (local|spartacus)
* @return
*/
function &setPluginInfo(&$plugin, &$pluginFile, &$bag, &$class_data, $pluginlocation = 'local') {
}
/**
- * SHORT
- *
- * LONG
+ * Moves a sidebar plugin to a different side or up/down
*
* @access public
- * @param
+ * @param string The instance ID of a plugin
+ * @param string The new placement of a plugin (left|right|hidden)
+ * @param string A new sort order for the plugin
* @return
*/
function update_plugin_placement($name, $placement, $order=null)
}
/**
- * SHORT
- *
- * LONG
+ * Updates the ownership information about a plugin
*
* @access public
- * @param
+ * @param string The instance ID of the plugin
+ * @param int The ID of the new author owner of the plugin
* @return
*/
function update_plugin_owner($name, $authorid)
}
/**
- * SHORT
- *
- * LONG
+ * Get a list of Sidebar plugins and pass them to Smarty
*
* @access public
- * @param
- * @return
+ * @param string The side of plugins to show (left/right/hidden)
+ * @param string deprecated: Indicated which wrapping HTML element to use for plugins
+ * @param boolean Indicates whether only all plugins should be shown that are not in the $side list
+ * @param string Only show plugins of this plugin class
+ * @param string Only show a plugin with this instance ID
+ * @return string Smarty HTML output
*/
function generate_plugins($side, $tag = '', $negate = false, $class = null, $id = null)
{
}
/**
- * SHORT
- *
- * LONG
+ * Gets the title of a plugin to be shown in plugin overview
*
* @access public
- * @param
- * @return
+ * @param object The plugin object
+ * @param string The default title, if none was configured
+ * @return string The title of the plugin
*/
function get_plugin_title(&$plugin, $default_title = '')
{
}
/**
- * SHORT
+ * Check if a plugin is an event plugin
*
- * LONG
+ * Refactoring: decompose conditional
*
* @access public
- * @param
- * @return
+ * @param string Name of a plugin
+ * @return boolean
*/
- /* 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
+ * Prepares a cache of all event plugins and load them in queue so that they can be fetched
*
* @access public
- * @param
- * @return
+ * @param mixed If set to a string, a certain event plugin cache object will be returned by this function
+ * @param boolean If set to true, the list of cached event plugins will be refreshed
+ * @return mixed Either returns the whole list of event plugins, or only a specific instance
*/
function &get_event_plugins($getInstance = false, $refresh = false) {
static $event_plugins;
}
/**
- * SHORT
+ * Executes a specific Eventhook
*
- * LONG
+ * If you want to temporarily block any event plugins, you can set $serendipity['no_events'] before
+ * this method call.
*
* @access public
- * @param
- * @return
+ * @param string The name of the event to hook on to
+ * @param mixed May contain any type of variables that are passed by reference to an event plugin
+ * @param mixed May contain any type of variables that are passed to an event plugin
+ * @return true
*/
function hook_event($event_name, &$eventData, $addData = null) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Checks if a specific plugin instance is already installed
*
* @access public
- * @param
- * @return
+ * @param string A name (may contain wildcards) of a plugin class to check
+ * @return boolean True if a plugin was found
*/
function exists($instance_id) {
global $serendipity;
}
/**
- * SHORT
- *
- * LONG
+ * Install a new plugin by ensuring that it does not already exist
*
* @access public
- * @param
- * @return
+ * @param string The classname of the plugin
+ * @param int The new owner author
+ * @param boolean Indicates if the plugin is an event plugin
+ * @return object Returns the plugin object or false, if failure
*/
function &autodetect_instance($plugin_name, $authorid, $is_event_plugin = false) {
if ($is_event_plugin) {
var $name = null;
/**
- * SHORT
- *
- * LONG
+ * Adds a property value to the bag
*
* @access public
- * @param
- * @return
+ * @param string The name of the property
+ * @param mixed The value of a property
+ * @return null
*/
function add($name, $value)
{
}
/**
- * SHORT
- *
- * LONG
+ * Returns a property value of a bag
*
* @access public
- * @param
- * @return
+ * @param string Name of property to fetch
+ * @return mixed The value of the property
*/
function &get($name)
{
}
/**
- * SHORT
- *
- * LONG
+ * Check if a specific property name is already set
*
* @access public
- * @param
- * @return
+ * @param string Name of the property to check
+ * @return boolean True, if already set.
*/
function is_set($name)
{
}
}
+/* A core plugin, with methods that both event and sidebar plugins share */
class serendipity_plugin {
var $instance = null;
var $protected = false;
var $title = null;
/**
- * SHORT
+ * The constructor of a plugin
*
- * LONG
+ * Needs to be implemented by your own class.
+ * Be sure to call this method from your derived classes constructors,
+ * otherwise your config data will not be stored or retrieved correctly
*
* @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
+ * @return true
*/
function serendipity_plugin($instance)
{
}
/**
- * SHORT
+ * Perform install routines
*
- * LONG
+ * Called by Serendipity when the plugin is first installed.
+ * Can be used to install database tables etc.
*
* @access public
- * @param
- * @return
- */
-/* Called by Serendipity when the plugin is first installed.
- * Can be used to install database tables etc.
+ * @return true
*/
function install()
{
}
/**
- * SHORT
+ * Perform uninstall routines
*
- * LONG
+ * Called by Serendipity when the plugin is removed/uninstalled.
+ * Can be used to drop installed database tables etc.
*
* @access public
- * @param
- * @return
- */
-/* Called by Serendipity when the plugin is removed/uninstalled.
- * Can be used to drop installed database tables etc.
+ * @param object A property bag object
+ * @return true
*/
function uninstall(&$propbag)
{
}
/**
- * SHORT
- *
- * LONG
+ * The introspection function of a plugin, to setup properties
*
- * @access public
- * @param
- * @return
- */
-/* Called by serendipity when it wants to display information
+ * Called by serendipity when it wants to display information
* about your plugin.
* You need to override this method in your child class.
+ *
+ * @access public
+ * @param object A property bag object you can manipulate
+ * @return true
*/
function introspect(&$propbag)
{
}
/**
- * SHORT
- *
- * LONG
+ * Introspection of a plugin configuration item
*
- * @access public
- * @param
- * @return
- */
-/* Called by serendipity when it wants to display the configuration
+ * 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.
* configuration option.
* You need to override this method in your child class if
* you have configuration options.
+ *
+ * @access public
+ * @param string Name of the config item
+ * @param object A property bag object you can store the configuration in
+ * @return
*/
function introspect_config_item($name, &$propbag)
{
}
/**
- * SHORT
+ * Validate plugin configuration options.
*
- * LONG
+ * Called from Plugin Configuration manager. Can be extended by your own plugin, if you need.
*
* @access public
- * @param
+ * @param string Name of the config item to validate
+ * @param object Property bag of the config item
+ * @param value The value of a config item
* @return
*/
- /* Called to validate a plugin option */
function validate($config_item, &$cbag, &$value) {
static $pattern_mail = '([\.\-\+~@_0-9a-z]+?)';
static $pattern_url = '([@!=~\?:&;0-9a-z#\.\-_\/]+?)';
}
/**
- * SHORT
+ * Output plugin's contents (Sidebar plugins)
*
- * LONG
- *
- * @access public
- * @param
- * @return
- */
-/* Called by serendipity when it wants your plugin to display itself.
+ * 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.
+ *
+ * @access public
+ * @param string The referenced varaiable that holds the sidebar title of your plugin.
+ * @return null
*/
function generate_content(&$title)
{
}
/**
- * SHORT
- *
- * LONG
+ * Get a config value of the plugin
*
* @access public
- * @param
- * @return
+ * @param string Name of the config value to fetch
+ * @param mixed The default value of a configuration item, if not set
+ * @param boolean If true, the default value will only be set if the plugin config item was not set.
+ * @return mixed The value of the config item
*/
- /* Fetches a configuration value for this plugin */
function get_config($name, $defaultvalue = null, $empty = true)
{
$_res = serendipity_get_config_var($this->instance . '/' . $name, $defaultvalue, $empty);
}
/**
- * SHORT
- *
- * LONG
+ * Sets a configuration value for a plugin
*
* @access public
- * @param
+ * @param string Name of the plugin configuration item
+ * @param string Value of the plugin configuration item
* @return
*/
function set_config($name, $value)
}
/**
- * SHORT
+ * Garbage Collection
*
- * LONG
+ * 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.
*
* @access public
- * @param
- * @return
+ * @return true
*/
- /* 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.
- */
function cleanup()
{
// Cleanup. Remove all empty configs on SAVECONF-Submit.
}
/**
- * SHORT
+ * Auto-Register dependencies of a plugin
*
- * LONG
+ * This method evaluates the "dependencies" member variable to check which plugins need to be installed.
*
* @access public
- * @param
- * @return
+ * @param boolean If true, a depending plugin will be removed when this plugin is uninstalled
+ * @param int The owner id of the current plugin
+ * @return true
*/
function register_dependencies($remove = false, $authorid = '0')
{
}
}
-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.
*/
+class serendipity_event extends serendipity_plugin {
/**
- * SHORT
+ * The class constructor
*
- * LONG
+ * Be sure to call this method from your derived classes constructors,
+ * otherwise your config data will not be stored or retrieved correctly
*
* @access public
- * @param
+ * @param string The instance name
* @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)
{
}
/**
- * SHORT
+ * Gets a reference to an $entry / $eventData array pointer, interacting with Cache-Options
*
- * LONG
+ * This function is used by specific event plugins that require to properly get a reference
+ * to the 'extended' or 'body' field of an entry superarray. If they would immediately operate
+ * on the 'body' field, it might get overwritten by other plugins later on.
*
* @access public
- * @param
- * @return
+ * @param string The fieldname to get a reference for
+ * @param array The entry superarray to get the reference from
+ * @return array The value of the array for the fieldname (reference)
*/
function &getFieldReference($fieldname = 'body', &$eventData) {
// Get a reference to a content field (body/extended) of
}
/**
- * SHORT
+ * Main logic for making a plugin "listen" to an event
*
- * LONG
+ * This method is called by the main plugin API for every event, that is executed.
+ * You need to implement each actions that shall be performed by your plugin here.
*
* @access public
- * @param
- * @return
+ * @param string The name of the executed event
+ * @param object A property bag for the current plugin
+ * @param mixed Any referenced event data from the serendipity_plugin_api::hook_event() function
+ * @param mixed Any additional data from the hook_event call
+ * @return true
*/
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.
projects / s9y.git / commitdiff