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')) {
......@@ -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;
}
......
......@@ -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
......@@ -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