Commit 67f2c101 authored by Dries's avatar Dries

- Patch #584966 by mr.baileys, sun: add doxygen group for PHP function wrappers in Drupal.

parent 009724f2
...@@ -9,6 +9,37 @@ ...@@ -9,6 +9,37 @@
* a cached page are instead located in bootstrap.inc. * a cached page are instead located in bootstrap.inc.
*/ */
/**
* @defgroup php_wrappers PHP wrapper functions
* @{
* Functions that are wrappers or custom implementations of PHP functions.
*
* Certain PHP functions should not be used in Drupal. Instead, Drupal's
* replacement functions should be used.
*
* For example, for improved or more secure UTF8-handling, or RFC-compliant
* handling of URLs in Drupal.
*
* For ease of use and memorizing, all these wrapper functions use the same name
* as the original PHP function, but prefixed with "drupal_". Beware, however,
* that not all wrapper functions support the same arguments as the original
* functions.
*
* You should always use these wrapper functions in your code.
*
* Wrong:
* @code
* $my_substring = substr($original_string, 0, 5);
* @endcode
*
* Correct:
* @code
* $my_substring = drupal_substr($original_string, 0, 5);
* @endcode
*
* @} End of "defgroup php_wrappers".
*/
/** /**
* Error reporting level: display no errors. * Error reporting level: display no errors.
*/ */
...@@ -2466,6 +2497,8 @@ function drupal_map_assoc($array, $function = NULL) { ...@@ -2466,6 +2497,8 @@ function drupal_map_assoc($array, $function = NULL) {
* @param $time_limit * @param $time_limit
* An integer specifying the new time limit, in seconds. A value of 0 * An integer specifying the new time limit, in seconds. A value of 0
* indicates unlimited execution time. * indicates unlimited execution time.
*
* @ingroup php_wrappers
*/ */
function drupal_set_time_limit($time_limit) { function drupal_set_time_limit($time_limit) {
if (function_exists('set_time_limit')) { if (function_exists('set_time_limit')) {
...@@ -3249,7 +3282,7 @@ function drupal_get_js($scope = 'header', $javascript = NULL) { ...@@ -3249,7 +3282,7 @@ function drupal_get_js($scope = 'header', $javascript = NULL) {
* @see drupal_render(). * @see drupal_render().
*/ */
function drupal_process_attached($elements, $weight = JS_DEFAULT, $dependency_check = FALSE) { function drupal_process_attached($elements, $weight = JS_DEFAULT, $dependency_check = FALSE) {
// If there is nothing to process then return. // If there is nothing to process then return.
if (empty($elements['#attached'])) { if (empty($elements['#attached'])) {
return; return;
} }
...@@ -3838,7 +3871,7 @@ function drupal_cron_run() { ...@@ -3838,7 +3871,7 @@ function drupal_cron_run() {
// Fetch the cron semaphore // Fetch the cron semaphore
$semaphore = variable_get('cron_semaphore', FALSE); $semaphore = variable_get('cron_semaphore', FALSE);
$return = FALSE; $return = FALSE;
// Grab the defined cron queues. // Grab the defined cron queues.
$queues = module_invoke_all('cron_queue_info'); $queues = module_invoke_all('cron_queue_info');
...@@ -3883,7 +3916,7 @@ function drupal_cron_run() { ...@@ -3883,7 +3916,7 @@ function drupal_cron_run() {
// Return TRUE so other functions can check if it did run successfully // Return TRUE so other functions can check if it did run successfully
$return = TRUE; $return = TRUE;
} }
foreach ($queues as $queue_name => $info) { foreach ($queues as $queue_name => $info) {
$function = $info['worker callback']; $function = $info['worker callback'];
$end = time() + (isset($info['time']) ? $info['time'] : 15); $end = time() + (isset($info['time']) ? $info['time'] : 15);
...@@ -4311,7 +4344,7 @@ function show(&$element) { ...@@ -4311,7 +4344,7 @@ function show(&$element) {
* *
* @see drupal_render() * @see drupal_render()
* @see drupal_render_cache_set() * @see drupal_render_cache_set()
* *
* @param $elements * @param $elements
* A renderable array. * A renderable array.
* @return * @return
...@@ -4348,7 +4381,7 @@ function drupal_render_cache_get($elements) { ...@@ -4348,7 +4381,7 @@ function drupal_render_cache_get($elements) {
* A renderable array. * A renderable array.
*/ */
function drupal_render_cache_set($markup, $elements) { function drupal_render_cache_set($markup, $elements) {
// Create the cache ID for the element // Create the cache ID for the element.
if (!in_array($_SERVER['REQUEST_METHOD'], array('GET', 'HEAD')) || !$cid = drupal_render_cid_create($elements)) { if (!in_array($_SERVER['REQUEST_METHOD'], array('GET', 'HEAD')) || !$cid = drupal_render_cid_create($elements)) {
return FALSE; return FALSE;
} }
......
...@@ -312,7 +312,7 @@ function file_create_url($uri) { ...@@ -312,7 +312,7 @@ function file_create_url($uri) {
// Allow the URI to be altered, e.g. to serve a file from a CDN or static // Allow the URI to be altered, e.g. to serve a file from a CDN or static
// file server. // file server.
drupal_alter('file_url', $uri); drupal_alter('file_url', $uri);
$scheme = file_uri_scheme($uri); $scheme = file_uri_scheme($uri);
if (!$scheme) { if (!$scheme) {
...@@ -1725,6 +1725,8 @@ function file_get_mimetype($uri, $mapping = NULL) { ...@@ -1725,6 +1725,8 @@ function file_get_mimetype($uri, $mapping = NULL) {
* more information. * more information.
* @return * @return
* TRUE for success, FALSE in the event of an error. * TRUE for success, FALSE in the event of an error.
*
* @ingroup php_wrappers
*/ */
function drupal_chmod($uri, $mode = NULL) { function drupal_chmod($uri, $mode = NULL) {
if (!isset($mode)) { if (!isset($mode)) {
...@@ -1775,6 +1777,7 @@ function drupal_chmod($uri, $mode = NULL) { ...@@ -1775,6 +1777,7 @@ function drupal_chmod($uri, $mode = NULL) {
* The absolute pathname, or FALSE on failure. * The absolute pathname, or FALSE on failure.
* *
* @see realpath() * @see realpath()
* @ingroup php_wrappers
*/ */
function drupal_realpath($uri) { function drupal_realpath($uri) {
// If this URI is a stream, pass it off to the appropriate stream wrapper. // If this URI is a stream, pass it off to the appropriate stream wrapper.
...@@ -1804,6 +1807,7 @@ function drupal_realpath($uri) { ...@@ -1804,6 +1807,7 @@ function drupal_realpath($uri) {
* A string containing the directory name. * A string containing the directory name.
* *
* @see dirname() * @see dirname()
* @ingroup php_wrappers
*/ */
function drupal_dirname($uri) { function drupal_dirname($uri) {
$scheme = file_uri_scheme($uri); $scheme = file_uri_scheme($uri);
...@@ -1844,6 +1848,7 @@ function drupal_dirname($uri) { ...@@ -1844,6 +1848,7 @@ function drupal_dirname($uri) {
* Boolean TRUE on success, or FALSE on failure. * Boolean TRUE on success, or FALSE on failure.
* *
* @see mkdir() * @see mkdir()
* @ingroup php_wrappers
*/ */
function drupal_mkdir($uri, $mode = NULL, $recursive = FALSE, $context = NULL) { function drupal_mkdir($uri, $mode = NULL, $recursive = FALSE, $context = NULL) {
...@@ -1878,6 +1883,7 @@ function drupal_mkdir($uri, $mode = NULL, $recursive = FALSE, $context = NULL) { ...@@ -1878,6 +1883,7 @@ function drupal_mkdir($uri, $mode = NULL, $recursive = FALSE, $context = NULL) {
* The new temporary fillename, or FALSE on failure. * The new temporary fillename, or FALSE on failure.
* *
* @see tempnam() * @see tempnam()
* @ingroup php_wrappers
*/ */
function drupal_tempnam($directory, $prefix) { function drupal_tempnam($directory, $prefix) {
$scheme = file_uri_scheme($directory); $scheme = file_uri_scheme($directory);
......
...@@ -204,6 +204,8 @@ function drupal_session_initialize() { ...@@ -204,6 +204,8 @@ function drupal_session_initialize() {
/** /**
* Forcefully start a session, preserving already set session data. * Forcefully start a session, preserving already set session data.
*
* @ingroup php_wrappers
*/ */
function drupal_session_start() { function drupal_session_start() {
if (!drupal_session_started()) { if (!drupal_session_started()) {
...@@ -264,6 +266,8 @@ function drupal_session_started($set = NULL) { ...@@ -264,6 +266,8 @@ function drupal_session_started($set = NULL) {
/** /**
* Called when an anonymous user becomes authenticated or vice-versa. * Called when an anonymous user becomes authenticated or vice-versa.
*
* @ingroup php_wrappers
*/ */
function drupal_session_regenerate() { function drupal_session_regenerate() {
global $user, $is_https; global $user, $is_https;
......
...@@ -116,6 +116,8 @@ function unicode_requirements() { ...@@ -116,6 +116,8 @@ function unicode_requirements() {
* The XML data which will be parsed later. * The XML data which will be parsed later.
* @return * @return
* An XML parser object or FALSE on error. * An XML parser object or FALSE on error.
*
* @ingroup php_wrappers
*/ */
function drupal_xml_parser_create(&$data) { function drupal_xml_parser_create(&$data) {
// Default XML encoding is UTF-8 // Default XML encoding is UTF-8
...@@ -207,7 +209,7 @@ function drupal_truncate_bytes($string, $len) { ...@@ -207,7 +209,7 @@ function drupal_truncate_bytes($string, $len) {
if ((ord($string[$len]) < 0x80) || (ord($string[$len]) >= 0xC0)) { if ((ord($string[$len]) < 0x80) || (ord($string[$len]) >= 0xC0)) {
return substr($string, 0, $len); return substr($string, 0, $len);
} }
// Scan backwards to beginning of the byte sequence. // Scan backwards to beginning of the byte sequence.
while (--$len >= 0 && ord($string[$len]) >= 0x80 && ord($string[$len]) < 0xC0); while (--$len >= 0 && ord($string[$len]) >= 0x80 && ord($string[$len]) < 0xC0);
return substr($string, 0, $len); return substr($string, 0, $len);
...@@ -393,6 +395,8 @@ function _decode_entities($prefix, $codepoint, $original, &$html_entities, &$exc ...@@ -393,6 +395,8 @@ function _decode_entities($prefix, $codepoint, $original, &$html_entities, &$exc
/** /**
* Count the amount of characters in a UTF-8 string. This is less than or * Count the amount of characters in a UTF-8 string. This is less than or
* equal to the byte count. * equal to the byte count.
*
* @ingroup php_wrappers
*/ */
function drupal_strlen($text) { function drupal_strlen($text) {
global $multibyte; global $multibyte;
...@@ -407,6 +411,8 @@ function drupal_strlen($text) { ...@@ -407,6 +411,8 @@ function drupal_strlen($text) {
/** /**
* Uppercase a UTF-8 string. * Uppercase a UTF-8 string.
*
* @ingroup php_wrappers
*/ */
function drupal_strtoupper($text) { function drupal_strtoupper($text) {
global $multibyte; global $multibyte;
...@@ -424,6 +430,8 @@ function drupal_strtoupper($text) { ...@@ -424,6 +430,8 @@ function drupal_strtoupper($text) {
/** /**
* Lowercase a UTF-8 string. * Lowercase a UTF-8 string.
*
* @ingroup php_wrappers
*/ */
function drupal_strtolower($text) { function drupal_strtolower($text) {
global $multibyte; global $multibyte;
...@@ -449,6 +457,8 @@ function _unicode_caseflip($matches) { ...@@ -449,6 +457,8 @@ function _unicode_caseflip($matches) {
/** /**
* Capitalize the first letter of a UTF-8 string. * Capitalize the first letter of a UTF-8 string.
*
* @ingroup php_wrappers
*/ */
function drupal_ucfirst($text) { function drupal_ucfirst($text) {
// Note: no mbstring equivalent! // Note: no mbstring equivalent!
...@@ -462,6 +472,8 @@ function drupal_ucfirst($text) { ...@@ -462,6 +472,8 @@ function drupal_ucfirst($text) {
* Note that for cutting off a string at a known character/substring * Note that for cutting off a string at a known character/substring
* location, the usage of PHP's normal strpos/substr is safe and * location, the usage of PHP's normal strpos/substr is safe and
* much faster. * much faster.
*
* @ingroup php_wrappers
*/ */
function drupal_substr($text, $start, $length = NULL) { function drupal_substr($text, $start, $length = NULL) {
global $multibyte; global $multibyte;
...@@ -545,5 +557,3 @@ function drupal_substr($text, $start, $length = NULL) { ...@@ -545,5 +557,3 @@ function drupal_substr($text, $start, $length = NULL) {
return substr($text, $istart, max(0, $iend - $istart + 1)); return substr($text, $istart, max(0, $iend - $istart + 1));
} }
} }
...@@ -48,6 +48,8 @@ function php_permission() { ...@@ -48,6 +48,8 @@ function php_permission() {
* @return * @return
* A string containing the printed output of the code, followed by the returned * A string containing the printed output of the code, followed by the returned
* output of the code. * output of the code.
*
* @ingroup php_wrappers
*/ */
function php_eval($code) { function php_eval($code) {
global $theme_path, $theme_info, $conf; global $theme_path, $theme_info, $conf;
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment