diff options
author | Dries Buytaert <dries@buytaert.net> | 2009-09-28 22:22:54 +0000 |
---|---|---|
committer | Dries Buytaert <dries@buytaert.net> | 2009-09-28 22:22:54 +0000 |
commit | 67f2c101c1a415afdf40ab02b716e242b57fd5e1 (patch) | |
tree | 9e9a181a58c81698a4314dc281a7651f8e785a49 /includes | |
parent | 009724f220a46e06ffbdc28d105c4fdb16c028c4 (diff) | |
download | brdo-67f2c101c1a415afdf40ab02b716e242b57fd5e1.tar.gz brdo-67f2c101c1a415afdf40ab02b716e242b57fd5e1.tar.bz2 |
- Patch #584966 by mr.baileys, sun: add doxygen group for PHP function wrappers in Drupal.
Diffstat (limited to 'includes')
-rw-r--r-- | includes/common.inc | 43 | ||||
-rw-r--r-- | includes/file.inc | 8 | ||||
-rw-r--r-- | includes/session.inc | 4 | ||||
-rw-r--r-- | includes/unicode.inc | 16 |
4 files changed, 62 insertions, 9 deletions
diff --git a/includes/common.inc b/includes/common.inc index 0c09f7087..47542e937 100644 --- a/includes/common.inc +++ b/includes/common.inc @@ -10,6 +10,37 @@ */ /** + * @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. */ define('ERROR_REPORTING_HIDE', 0); @@ -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; } diff --git a/includes/file.inc b/includes/file.inc index 366bbc959..894f90bc3 100644 --- a/includes/file.inc +++ b/includes/file.inc @@ -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); diff --git a/includes/session.inc b/includes/session.inc index 677963ae1..60d5d54a4 100644 --- a/includes/session.inc +++ b/includes/session.inc @@ -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; diff --git a/includes/unicode.inc b/includes/unicode.inc index da4a37377..4aa363c28 100644 --- a/includes/unicode.inc +++ b/includes/unicode.inc @@ -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)); } } - - |