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 @@
* 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.
*/
......@@ -2466,6 +2497,8 @@ function drupal_map_assoc($array, $function = NULL) {
* @param $time_limit
* An integer specifying the new time limit, in seconds. A value of 0
* indicates unlimited execution time.
*
* @ingroup php_wrappers
*/
function drupal_set_time_limit($time_limit) {
if (function_exists('set_time_limit')) {
......@@ -3249,7 +3282,7 @@ function drupal_get_js($scope = 'header', $javascript = NULL) {
* @see drupal_render().
*/
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'])) {
return;
}
......@@ -3838,7 +3871,7 @@ function drupal_cron_run() {
// Fetch the cron semaphore
$semaphore = variable_get('cron_semaphore', FALSE);
$return = FALSE;
// Grab the defined cron queues.
$queues = module_invoke_all('cron_queue_info');
......@@ -3883,7 +3916,7 @@ function drupal_cron_run() {
// Return TRUE so other functions can check if it did run successfully
$return = TRUE;
}
foreach ($queues as $queue_name => $info) {
$function = $info['worker callback'];
$end = time() + (isset($info['time']) ? $info['time'] : 15);
......@@ -4311,7 +4344,7 @@ function show(&$element) {
*
* @see drupal_render()
* @see drupal_render_cache_set()
*
*
* @param $elements
* A renderable array.
* @return
......@@ -4348,7 +4381,7 @@ function drupal_render_cache_get($elements) {
* A renderable array.
*/
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)) {
return FALSE;
}
......
......@@ -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
// file server.
drupal_alter('file_url', $uri);
$scheme = file_uri_scheme($uri);
if (!$scheme) {
......@@ -1725,6 +1725,8 @@ function file_get_mimetype($uri, $mapping = NULL) {
* more information.
* @return
* TRUE for success, FALSE in the event of an error.
*
* @ingroup php_wrappers
*/
function drupal_chmod($uri, $mode = NULL) {
if (!isset($mode)) {
......@@ -1775,6 +1777,7 @@ function drupal_chmod($uri, $mode = NULL) {
* The absolute pathname, or FALSE on failure.
*
* @see realpath()
* @ingroup php_wrappers
*/
function drupal_realpath($uri) {
// If this URI is a stream, pass it off to the appropriate stream wrapper.
......@@ -1804,6 +1807,7 @@ function drupal_realpath($uri) {
* A string containing the directory name.
*
* @see dirname()
* @ingroup php_wrappers
*/
function drupal_dirname($uri) {
$scheme = file_uri_scheme($uri);
......@@ -1844,6 +1848,7 @@ function drupal_dirname($uri) {
* Boolean TRUE on success, or FALSE on failure.
*
* @see mkdir()
* @ingroup php_wrappers
*/
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.
*
* @see tempnam()
* @ingroup php_wrappers
*/
function drupal_tempnam($directory, $prefix) {
$scheme = file_uri_scheme($directory);
......
......@@ -204,6 +204,8 @@ function drupal_session_initialize() {
/**
* Forcefully start a session, preserving already set session data.
*
* @ingroup php_wrappers
*/
function drupal_session_start() {
if (!drupal_session_started()) {
......@@ -264,6 +266,8 @@ function drupal_session_started($set = NULL) {
/**
* Called when an anonymous user becomes authenticated or vice-versa.
*
* @ingroup php_wrappers
*/
function drupal_session_regenerate() {
global $user, $is_https;
......
......@@ -116,6 +116,8 @@ function unicode_requirements() {
* The XML data which will be parsed later.
* @return
* An XML parser object or FALSE on error.
*
* @ingroup php_wrappers
*/
function drupal_xml_parser_create(&$data) {
// Default XML encoding is UTF-8
......@@ -207,7 +209,7 @@ function drupal_truncate_bytes($string, $len) {
if ((ord($string[$len]) < 0x80) || (ord($string[$len]) >= 0xC0)) {
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);
return substr($string, 0, $len);
......@@ -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
* equal to the byte count.
*
* @ingroup php_wrappers
*/
function drupal_strlen($text) {
global $multibyte;
......@@ -407,6 +411,8 @@ function drupal_strlen($text) {
/**
* Uppercase a UTF-8 string.
*
* @ingroup php_wrappers
*/
function drupal_strtoupper($text) {
global $multibyte;
......@@ -424,6 +430,8 @@ function drupal_strtoupper($text) {
/**
* Lowercase a UTF-8 string.
*
* @ingroup php_wrappers
*/
function drupal_strtolower($text) {
global $multibyte;
......@@ -449,6 +457,8 @@ function _unicode_caseflip($matches) {
/**
* Capitalize the first letter of a UTF-8 string.
*
* @ingroup php_wrappers
*/
function drupal_ucfirst($text) {
// Note: no mbstring equivalent!
......@@ -462,6 +472,8 @@ function drupal_ucfirst($text) {
* Note that for cutting off a string at a known character/substring
* location, the usage of PHP's normal strpos/substr is safe and
* much faster.
*
* @ingroup php_wrappers
*/
function drupal_substr($text, $start, $length = NULL) {
global $multibyte;
......@@ -545,5 +557,3 @@ function drupal_substr($text, $start, $length = NULL) {
return substr($text, $istart, max(0, $iend - $istart + 1));
}
}
......@@ -48,6 +48,8 @@ function php_permission() {
* @return
* A string containing the printed output of the code, followed by the returned
* output of the code.
*
* @ingroup php_wrappers
*/
function php_eval($code) {
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