golem
/
twentyGOLEM
9
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

PHPDoc updates for functions.php. See #5639 props jacobsantos. 

git-svn-id: http://svn.automattic.com/wordpress/trunk@8092 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
westi 2008-06-15 09:38:32 +00:00
parent bf35dedced
commit d9d640809b
1 changed files with 408 additions and 75 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

483
wp-includes/functions.php
View File

@ -1,5 +1,27 @@
<?php
/**
* Main WordPress API
*
* @package WordPress
*/
/**
* Converts MySQL DATETIME field to user specified date format.
*
* If $dateformatstring has 'G' value, then gmmktime() function will be used to
* make the time. If $dateformatstring is set to 'U', then mktime() function
* will be used to make the time.
*
* The $translate will only be used, if it is set to true and it is by default
* and if the $wp_locale object has the month and weekday set.
*
* @since 0.71
*
* @param string $dateformatstring Either 'G', 'U', or php date format.
* @param string $mysqlstring Time from mysql DATETIME field.
* @param bool $translate Optional. Default is true. Will switch format to locale.
* @return string Date formated by $dateformatstring or locale (if available).
*/
function mysql2date( $dateformatstring, $mysqlstring, $translate = true ) {
global $wp_locale;
$m = $mysqlstring;
@ -51,7 +73,21 @@ function mysql2date( $dateformatstring, $mysqlstring, $translate = true ) {
return $j;
}
/**
* Retrieve the current time based on specified type.
*
* The 'mysql' type will return the time in the format for MySQL DATETIME field.
* The 'timestamp' type will return the current timestamp.
*
* If the $gmt is set to either '1' or 'true', then both types will use the
* GMT offset in the WordPress option to add the GMT offset to the time.
*
* @since 1.0.0
*
* @param string $type Either 'mysql' or 'timestamp'.
* @param int|bool $gmt Optional. Whether to use $gmt offset. Default is false.
* @return unknown
*/
function current_time( $type, $gmt = 0 ) {
switch ( $type ) {
case 'mysql':
@ -88,7 +124,15 @@ function date_i18n( $dateformatstring, $unixtimestamp ) {
return $j;
}
/**
* Convert number to format based on the locale.
*
* @since 2.3.0
*
* @param mixed $number The number to convert based on locale.
* @param int $decimals Precision of the number of decimal places.
* @return string Converted number in string format.
*/
function number_format_i18n( $number, $decimals = null ) {
global $wp_locale;
// let the user override the precision only
@ -97,10 +141,28 @@ function number_format_i18n( $number, $decimals = null ) {
return number_format( $number, $decimals, $wp_locale->number_format['decimal_point'], $wp_locale->number_format['thousands_sep'] );
}
/**
* Convert number of bytes largest unit bytes will fit into.
*
* It is easier to read 1kB than 1024 bytes and 1MB than 1048576 bytes. Converts
* number of bytes to human readable number by taking the number of that unit
* that the bytes will go into it. Supports TB value.
*
* Please note that integers in PHP are limited to 32 bits, unless they are on
* 64 bit architecture, then they have 64 bit size. If you need to place the
* larger size then what PHP integer type will hold, then use a string. It will
* be converted to a double, which should always have 64 bit length.
*
* Technically the correct unit names for powers of 1024 are KiB, MiB etc.
* @link http://en.wikipedia.org/wiki/Byte
*
* @since 2.3.0
*
* @param int|string $bytes Number of bytes. Note max integer size for integers.
* @param int $decimals Precision of number of decimal places.
* @return unknown
*/
function size_format( $bytes, $decimals = null ) {
// technically the correct unit names for powers of 1024 are KiB, MiB etc
// see http://en.wikipedia.org/wiki/Byte
$quant = array(
// ========================= Origin ====
'TB' => 1099511627776, // pow( 1024, 4)
@ -144,7 +206,14 @@ function get_weekstartend( $mysqlstring, $start_of_week = '' ) {
return $week;
}
/**
* Unserialize value only if it was serialized.
*
* @since 2.0.0
*
* @param string $original Maybe unserialized original, if is needed.
* @return mixed Unserialized data can be any type.
*/
function maybe_unserialize( $original ) {
if ( is_serialized( $original ) ) // don't attempt to unserialize data that wasn't serialized going in
if ( false !== $gm = @unserialize( $original ) )
@ -152,7 +221,17 @@ function maybe_unserialize( $original ) {
return $original;
}
/**
* Check value to find if it was serialized.
*
* If $data is not an string, then returned value will always be false.
* Serialized data is always a string.
*
* @since 2.0.5
*
* @param mixed $data Value to check to see if was serialized.
* @return bool False if not serialized and true if it was.
*/
function is_serialized( $data ) {
// if it isn't a string, it isn't serialized
if ( !is_string( $data ) )
@ -179,7 +258,14 @@ function is_serialized( $data ) {
return false;
}
/**
* Check whether serialized data is of string type.
*
* @since 2.0.5
*
* @param mixed $data Serialized data
* @return bool False if not a serialized string, true if it is.
*/
function is_serialized_string( $data ) {
// if it isn't a string, it isn't a serialized string
if ( !is_string( $data ) )
@ -190,10 +276,20 @@ function is_serialized_string( $data ) {
return false;
}
/* Options functions */
// expects $setting to already be SQL-escaped
/**
* Retrieve option value based on setting name.
*
* {@internal Missing Long Description}}
*
* @since 1.5.0
* @package WordPress
* @subpackage Option
*
* @param string $setting Name of option to retrieve. Should already be SQL-escaped
* @return mixed Value set for the option.
*/
function get_option( $setting ) {
global $wpdb;
@ -243,13 +339,33 @@ function get_option( $setting ) {
return apply_filters( 'option_' . $setting, maybe_unserialize( $value ) );
}
/**
* Protect WordPress special option from being modified.
*
* Will die if $option is in protected list.
*
* @since 2.2.0
* @package WordPress
* @subpackage Option
*
* @param string $option Option name.
*/
function wp_protect_special_option( $option ) {
$protected = array( 'alloptions', 'notoptions' );
if ( in_array( $option, $protected ) )
die( sprintf( __( '%s is a protected WP option and may not be modified' ), wp_specialchars( $option ) ) );
}
/**
* Print option value after sanitizing for forms.
*
* @uses attribute_escape Sanitizes value.
* @since 1.5.0
* @package WordPress
* @subpackage Option
*
* @param string $option Option name.
*/
function form_option( $option ) {
echo attribute_escape (get_option( $option ) );
}
@ -536,9 +652,19 @@ function do_enclose( $content, $post_ID ) {
}
}
// perform a HTTP HEAD or GET request
// if $file_path is a writable filename, this will do a GET request and write the file to that path
// returns a list of HTTP headers
/**
* Perform a HTTP HEAD or GET request.
*
* If $file_path is a writable filename, this will do a GET request and write
* the file to that path.
*
* @since unknown
*
* @param string $url
* @param string|bool $file_path Optional. File path to write request to.
* @param int $red Optional. Number of Redirects. Stops at 5 redirects.
* @return bool|string False on failure and string of headers if HEAD request.
*/
function wp_get_http( $url, $file_path = false, $red = 1 ) {
global $wp_version;
@set_time_limit( 60 );
@ -610,11 +736,30 @@ function wp_get_http( $url, $file_path = false, $red = 1 ) {
return $headers;
}
/**
* Retrieve HTTP Headers from URL.
*
* @since 1.5.1
*
* @param string $url
* @param int $red Optional. Number of redirects.
* @return bool|string False on failure, headers on success.
*/
function wp_get_http_headers( $url, $red = 1 ) {
return wp_get_http( $url, false, $red );
}
/**
* Whether today is a new day.
*
* {@internal Need to find out how this function is used.}}
*
* @since 0.71
* @uses $day Today
* @uses $previousday Previous day
*
* @return int 1 when new day, 0 if not a new day.
*/
function is_new_day() {
global $day, $previousday;
if ( $day != $previousday )
@ -628,17 +773,22 @@ function build_query( $data ) {
return _http_build_query( $data, NULL, '&', '', false );
}
/*
add_query_arg: Returns a modified querystring by adding
a single key & value or an associative array.
Setting a key value to emptystring removes the key.
Omitting oldquery_or_uri uses the $_SERVER value.
Parameters:
add_query_arg(newkey, newvalue, oldquery_or_uri) or
add_query_arg(associative_array, oldquery_or_uri)
*/
/**
* Retrieve a modified query string.
*
* {@internal Missing Long Description}}
*
* Adding a single key & value or an associative array.
* Setting a key value to emptystring removes the key.
* Omitting oldquery_or_uri uses the $_SERVER value.
*
* @since 1.5.0
*
* @param mixed $param1 Either newkey or an associative_array
* @param mixed $param2 Either newvalue or oldquery or uri
* @param mixed $param3 Optional. Old query or uri
* @return unknown
*/
function add_query_arg() {
$ret = '';
if ( is_array( func_get_arg(0) ) ) {
@ -704,27 +854,32 @@ function add_query_arg() {
return $ret;
}
/*
remove_query_arg: Returns a modified querystring by removing
a single key or an array of keys.
Omitting oldquery_or_uri uses the $_SERVER value.
Parameters:
remove_query_arg(removekey, [oldquery_or_uri]) or
remove_query_arg(removekeyarray, [oldquery_or_uri])
*/
function remove_query_arg( $key, $query=FALSE ) {
/**
* Removes an item or list from the query string.
*
* @since 1.5.0
*
* @param string|array $key Query key or keys to remove.
* @param bool $query When false uses the $_SERVER value.
* @return unknown
*/
function remove_query_arg( $key, $query=false ) {
if ( is_array( $key ) ) { // removing multiple keys
foreach ( (array) $key as $k )
$query = add_query_arg( $k, FALSE, $query );
$query = add_query_arg( $k, false, $query );
return $query;
}
return add_query_arg( $key, FALSE, $query );
return add_query_arg( $key, false, $query );
}
/**
* Walks the array while sanitizing the contents.
*
* @uses $wpdb Used to sanitize values
*
* @param array $array Array to used to walk while sanitizing contents.
* @return array Sanitized $array.
*/
function add_magic_quotes( $array ) {
global $wpdb;
@ -782,7 +937,14 @@ function wp( $query_vars = '' ) {
$wp_the_query = $wp_query;
}
/**
* Retrieve the description for the HTTP status.
*
* @since 2.3.0
*
* @param int $code HTTP status code.
* @return string Empty string if not found, or description if found.
*/
function get_status_header_desc( $code ) {
global $wp_header_to_desc;
@ -862,7 +1024,14 @@ function status_header( $header ) {
return @header( $status_header );
}
/**
* Sets the headers to prevent caching for the different browsers.
*
* Different browsers support different nocache headers, so several headers must
* be sent so that all of them get the point that no caching should occur.
*
* @since 2.0.0
*/
function nocache_headers() {
// why are these @-silenced when other header calls aren't?
@header( 'Expires: Wed, 11 Jan 1984 05:00:00 GMT' );
@ -871,7 +1040,11 @@ function nocache_headers() {
@header( 'Pragma: no-cache' );
}
/**
* Set the headers for caching for 10 days with JavaScript content type.
*
* @since 2.1.0
*/
function cache_javascript_headers() {
$expiresOffset = 864000; // 10 days
header( "Content-Type: text/javascript; charset=" . get_bloginfo( 'charset' ) );
@ -879,13 +1052,26 @@ function cache_javascript_headers() {
header( "Expires: " . gmdate( "D, d M Y H:i:s", time() + $expiresOffset ) . " GMT" );
}
/**
* Retrieve the number of database queries during the WordPress execution.
*
* @since 2.0.0
*
* @return int Number of database queries
*/
function get_num_queries() {
global $wpdb;
return $wpdb->num_queries;
}
/**
* Whether input is yes or no. Must be 'y' to be true.
*
* @since 1.0.0
*
* @param string $yn Character string containing either 'y' or 'n'
* @return bool True if yes, false on anything else
*/
function bool_from_yn( $yn ) {
return ( strtolower( $yn ) == 'y' );
}
@ -911,17 +1097,31 @@ function do_feed() {
do_action( $hook, $wp_query->is_comment_feed );
}
/**
* Load the RDF RSS 0.91 Feed template.
*
* @since 2.1.0
*/
function do_feed_rdf() {
load_template( ABSPATH . WPINC . '/feed-rdf.php' );
}
/**
* Load the RSS 1.0 Feed Template
*
* @since 2.1.0
*/
function do_feed_rss() {
load_template( ABSPATH . WPINC . '/feed-rss.php' );
}
/**
* Load either the RSS2 comment feed or the RSS2 posts feed.
*
* @since 2.1.0
*
* @param bool $for_comments True for the comment feed, false for normal feed.
*/
function do_feed_rss2( $for_comments ) {
if ( $for_comments )
load_template( ABSPATH . WPINC . '/feed-rss2-comments.php' );
@ -929,7 +1129,13 @@ function do_feed_rss2( $for_comments ) {
load_template( ABSPATH . WPINC . '/feed-rss2.php' );
}
/**
* Load either Atom comment feed or Atom posts feed.
*
* @since 2.1.0
*
* @param bool $for_comments True for the comment feed, false for normal feed.
*/
function do_feed_atom( $for_comments ) {
if ($for_comments)
load_template( ABSPATH . WPINC . '/feed-atom-comments.php');
@ -937,6 +1143,15 @@ function do_feed_atom( $for_comments ) {
load_template( ABSPATH . WPINC . '/feed-atom.php' );
}
/**
* Display the robot.txt file content.
*
* The echo content should be with usage of the permalinks or for creating the
* robot.txt file.
*
* @since 2.1.0
* @uses do_action() Calls 'do_robotstxt' hook for displaying robot.txt rules.
*/
function do_robots() {
header( 'Content-Type: text/plain; charset=utf-8' );
@ -1511,7 +1726,18 @@ function smilies_init() {
}
}
/**
* Merge user defined arguments into defaults array.
*
* This function is used throughout WordPress to allow for both string or array
* to be merged into another array.
*
* @since 2.2.0
*
* @param string|array $args Value to merge with $defaults
* @param array $defaults Array that serves as the defaults.
* @return array Merged user defined values with defaults.
*/
function wp_parse_args( $args, $defaults = '' ) {
if ( is_object( $args ) )
$r = get_object_vars( $args );
@ -1525,7 +1751,15 @@ function wp_parse_args( $args, $defaults = '' ) {
return $r;
}
/**
* Determines if Widgets library should be loaded.
*
* Checks to make sure that the widgets library hasn't already been loaded. If
* it hasn't, then it will load the widgets library and run an action hook.
*
* @since 2.2.0
* @uses add_action() Calls '_admin_menu' hook with 'wp_widgets_add_menu' value.
*/
function wp_maybe_load_widgets() {
if ( !function_exists( 'dynamic_sidebar' ) ) {
require_once( ABSPATH . WPINC . '/widgets.php' );
@ -1533,28 +1767,39 @@ function wp_maybe_load_widgets() {
}
}
/**
* Append the Widgets menu to the themes main menu.
*
* @since 2.2.0
* @uses $submenu The administration submenu list.
*/
function wp_widgets_add_menu() {
global $submenu;
$submenu['themes.php'][7] = array( __( 'Widgets' ), 'switch_themes', 'widgets.php' );
ksort( $submenu['themes.php'], SORT_NUMERIC );
}
// For PHP 5.2, make sure all output buffers are flushed
// before our singletons our destroyed.
/**
* Flush all output buffers for PHP 5.2.
*
* Make sure all output buffers are flushed before our singletons our destroyed.
*
* @since 2.2.0
/
function wp_ob_end_flush_all() {
while ( @ob_end_flush() );
}
/*
* require_wp_db() - require_once the correct database class file.
/**
* Load the correct database class file.
*
* This function is used to load the database class file either at runtime or by wp-admin/setup-config.php
* We must globalise $wpdb to ensure that it is defined globally by the inline code in wp-db.php
* This function is used to load the database class file either at runtime or by
* wp-admin/setup-config.php We must globalise $wpdb to ensure that it is
* defined globally by the inline code in wp-db.php.
*
* @global $wpdb
* @since 2.5
* @global $wpdb WordPress Database Object
*/
function require_wp_db() {
global $wpdb;
@ -1564,6 +1809,21 @@ function require_wp_db() {
require_once( ABSPATH . WPINC . '/wp-db.php' );
}
/**
* Load custom DB error or display WordPress DB error.
*
* If a file exists in the wp-content directory named db-error.php, then it will
* be loaded instead of displaying the WordPress DB error. If it is not found,
* then the WordPress DB error will be displayed instead.
*
* The WordPress DB error sets the HTTP status header to 500 to try to prevent
* search engines from caching the message. Custom DB messages should do the
* same.
*
* @since 2.5
* @uses $wpdb
*/
function dead_db() {
global $wpdb;
@ -1597,8 +1857,12 @@ function dead_db() {
die();
}
/**
* Converts input to an absolute integer
* Converts value to positive integer.
*
* @since 2.5
*
* @param mixed $maybeint data you wish to have convered to an absolute integer
* @return int an absolute integer
*/
@ -1606,9 +1870,16 @@ function absint( $maybeint ) {
return abs( intval( $maybeint ) );
}
/**
* Determines if the blog can be accessed over SSL
* @return bool whether of not SSL access is available
* Determines if the blog can be accessed over SSL.
*
* Determines if blog can be accessed over SSL by using cURL to access the site
* using the https in the siteurl. Requires cURL extension to work correctly.
*
* @since 2.5
*
* @return bool Whether or not SSL access is available
*/
function url_is_accessable_via_ssl($url)
{
@ -1633,21 +1904,33 @@ function url_is_accessable_via_ssl($url)
return false;
}
/**
* Secure URL, if available or the given URL.
*
* @since 2.5
*
* @param string $url Complete URL path with transport.
* @return string Secure or regular URL path.
*/
function atom_service_url_filter($url)
{
if ( url_is_accessable_via_ssl($url) )
return preg_replace( '/^http:\/\//', 'https://', $url );
return preg_replace( '/^http:\/\//', 'https://', $url );
else
return $url;
}
/**
* _deprecated_function() - Marks a function as deprecated and informs when it has been used.
* Marks a function as deprecated and informs when it has been used.
*
* There is a hook deprecated_function_run that will be called that can be used to get the backtrace
* up to what file and function called the deprecated function.
* There is a hook deprecated_function_run that will be called that can be used
* to get the backtrace up to what file and function called the deprecated
* function.
*
* The current behavior is to trigger an user error if WP_DEBUG is defined and is true.
* The current behavior is to trigger an user error if WP_DEBUG is defined and
* is true.
*
* This function is to be used in every function in depreceated.php
*
@ -1676,13 +1959,16 @@ function _deprecated_function($function, $version, $replacement=null) {
}
}
/**
* _deprecated_file() - Marks a file as deprecated and informs when it has been used.
* Marks a file as deprecated and informs when it has been used.
*
* There is a hook deprecated_file_included that will be called that can be used to get the backtrace
* up to what file and function included the deprecated file.
* There is a hook deprecated_file_included that will be called that can be used
* to get the backtrace up to what file and function included the deprecated
* file.
*
* The current behavior is to trigger an user error if WP_DEBUG is defined and is true.
* The current behavior is to trigger an user error if WP_DEBUG is defined and
* is true.
*
* This function is to be used in every file that is depreceated
*
@ -1711,8 +1997,11 @@ function _deprecated_file($file, $version, $replacement=null) {
}
}
/**
* is_lighttpd_before_150() - Is the server running earlier than 1.5.0 version of lighttpd
* Is the server running earlier than 1.5.0 version of lighttpd
*
* @since unknown
*
* @return bool Whether the server is running lighttpd < 1.5.0
*/
@ -1722,8 +2011,11 @@ function is_lighttpd_before_150() {
return 'lighttpd' == $server_parts[0] && -1 == version_compare( $server_parts[1], '1.5.0' );
}
/**
* apache_mod_loaded() - Does the specified module exist in the apache config?
* Does the specified module exist in the apache config?
*
* @since unknown
*
* @param string $mod e.g. mod_rewrite
* @param bool $default The default return value if the module is not found
@ -1749,6 +2041,21 @@ function apache_mod_loaded($mod, $default = false) {
return $default;
}
/**
* File validates against allowed set of defined rules.
*
* A return value of '1' means that the $file contains either '..' or './'. A
* return value of '2' means that the $file contains ':' after the first
* character. A return value of '3' means that the file is not in the allowed
* files list.
*
* @since 2.6
*
* @param string $file File path.
* @param array $allowed_files List of allowed files.
* @return int 0 means nothing is wrong, greater than 0 means something was wrong.
*/
function validate_file( $file, $allowed_files = '' ) {
if ( false !== strpos( $file, '..' ))
return 1;
@ -1765,10 +2072,27 @@ function validate_file( $file, $allowed_files = '' ) {
return 0;
}
/**
* Determine if SSL is used.
*
* @since 2.6
*
* @return bool True if SSL, false if not used.
*/
function is_ssl() {
return ( 'on' == strtolower($_SERVER['HTTPS']) ) ? true : false;
}
/**
* Whether SSL login should be forced.
*
* @since 2.6
*
* @param string|bool $force Optional.
* @return bool True if forced, false if not forced.
*/
function force_ssl_login($force = '') {
static $forced;
@ -1781,6 +2105,15 @@ function force_ssl_login($force = '') {
return $forced;
}
/**
* Whether to force SSL used for the Administration Panels.
*
* @since 2.6
*
* @param string|bool $force
* @return bool True if forced, false if not forced.
*/
function force_ssl_admin($force = '') {
static $forced;