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

5 files changed, 64 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));
   }
 }
-
-
diff --git a/modules/php/php.module b/modules/php/php.module
index f9b7d5bcf..c4e2dfb92 100644
--- a/modules/php/php.module
+++ b/modules/php/php.module
@@ -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;