diff options
Diffstat (limited to 'includes')
| -rw-r--r-- | includes/bootstrap.inc | 2 | ||||
| -rw-r--r-- | includes/common.inc | 22 | ||||
| -rw-r--r-- | includes/database/database.inc | 11 | ||||
| -rw-r--r-- | includes/file.inc | 47 | ||||
| -rw-r--r-- | includes/form.inc | 30 | ||||
| -rw-r--r-- | includes/menu.inc | 2 | ||||
| -rw-r--r-- | includes/registry.inc | 9 |
7 files changed, 68 insertions, 55 deletions
diff --git a/includes/bootstrap.inc b/includes/bootstrap.inc index 4cc39142e..0ac932d6a 100644 --- a/includes/bootstrap.inc +++ b/includes/bootstrap.inc @@ -8,7 +8,7 @@ /** * The current system version. */ -define('VERSION', '7.27'); +define('VERSION', '7.28-dev'); /** * Core API compatibility. diff --git a/includes/common.inc b/includes/common.inc index 3b4bf580c..34828e8ca 100644 --- a/includes/common.inc +++ b/includes/common.inc @@ -1426,7 +1426,6 @@ function filter_xss_admin($string) { * valid UTF-8. * * @see drupal_validate_utf8() - * @ingroup sanitization */ function filter_xss($string, $allowed_tags = array('a', 'em', 'strong', 'cite', 'blockquote', 'code', 'ul', 'ol', 'li', 'dl', 'dt', 'dd')) { // Only operate on valid UTF-8 strings. This is necessary to prevent cross @@ -5067,6 +5066,11 @@ function drupal_get_private_key() { * @param $value * An additional value to base the token on. * + * The generated token is based on the session ID of the current user. Normally, + * anonymous users do not have a session, so the generated token will be + * different on every page request. To generate a token for users without a + * session, manually start a session prior to calling this function. + * * @return string * A 43-character URL-safe token for validation, based on the user session ID, * the hash salt provided from drupal_get_hash_salt(), and the @@ -5946,14 +5950,16 @@ function drupal_render(&$elements) { /** * Renders children of an element and concatenates them. * - * This renders all children of an element using drupal_render() and then - * joins them together into a single string. - * - * @param $element + * @param array $element * The structured array whose children shall be rendered. - * @param $children_keys - * If the keys of the element's children are already known, they can be passed - * in to save another run of element_children(). + * @param array $children_keys + * (optional) If the keys of the element's children are already known, they + * can be passed in to save another run of element_children(). + * + * @return string + * The rendered HTML of all children of the element. + + * @see drupal_render() */ function drupal_render_children(&$element, $children_keys = NULL) { if ($children_keys === NULL) { diff --git a/includes/database/database.inc b/includes/database/database.inc index 604dd4c7a..1bfb3f7d2 100644 --- a/includes/database/database.inc +++ b/includes/database/database.inc @@ -28,18 +28,21 @@ * Most Drupal database SELECT queries are performed by a call to db_query() or * db_query_range(). Module authors should also consider using the PagerDefault * Extender for queries that return results that need to be presented on - * multiple pages, and the Tablesort Extender for generating appropriate queries - * for sortable tables. + * multiple pages (see https://drupal.org/node/508796), and the TableSort + * Extender for generating appropriate queries for sortable tables + * (see https://drupal.org/node/1848372). * * For example, one might wish to return a list of the most recent 10 nodes * authored by a given user. Instead of directly issuing the SQL query * @code - * SELECT n.nid, n.title, n.created FROM node n WHERE n.uid = $uid LIMIT 0, 10; + * SELECT n.nid, n.title, n.created FROM node n WHERE n.uid = $uid + * ORDER BY n.created DESC LIMIT 0, 10; * @endcode * one would instead call the Drupal functions: * @code * $result = db_query_range('SELECT n.nid, n.title, n.created - * FROM {node} n WHERE n.uid = :uid', 0, 10, array(':uid' => $uid)); + * FROM {node} n WHERE n.uid = :uid + * ORDER BY n.created DESC', 0, 10, array(':uid' => $uid)); * foreach ($result as $record) { * // Perform operations on $record->title, etc. here. * } diff --git a/includes/file.inc b/includes/file.inc index 0ec69b701..ee6ce5181 100644 --- a/includes/file.inc +++ b/includes/file.inc @@ -1402,8 +1402,9 @@ function file_space_used($uid = NULL, $status = FILE_STATUS_PERMANENT) { * Temporary files are periodically cleaned. To make the file a permanent file, * assign the status and use file_save() to save the changes. * - * @param $source - * A string specifying the filepath or URI of the uploaded file to save. + * @param $form_field_name + * A string that is the associative array key of the upload form element in + * the form array. * @param $validators * An optional, associative array of callback functions used to validate the * file. See file_validate() for a full discussion of the array format. @@ -1414,9 +1415,9 @@ function file_space_used($uid = NULL, $status = FILE_STATUS_PERMANENT) { * (Beware: this is not safe and should only be allowed for trusted users, if * at all). * @param $destination - * A string containing the URI $source should be copied to. - * This must be a stream wrapper URI. If this value is omitted, Drupal's - * temporary files scheme will be used ("temporary://"). + * A string containing the URI that the file should be copied to. This must + * be a stream wrapper URI. If this value is omitted, Drupal's temporary + * files scheme will be used ("temporary://"). * @param $replace * Replace behavior when the destination file already exists: * - FILE_EXISTS_REPLACE: Replace the existing file. @@ -1434,45 +1435,45 @@ function file_space_used($uid = NULL, $status = FILE_STATUS_PERMANENT) { * - source: Path to the file before it is moved. * - destination: Path to the file after it is moved (same as 'uri'). */ -function file_save_upload($source, $validators = array(), $destination = FALSE, $replace = FILE_EXISTS_RENAME) { +function file_save_upload($form_field_name, $validators = array(), $destination = FALSE, $replace = FILE_EXISTS_RENAME) { global $user; static $upload_cache; // Return cached objects without processing since the file will have // already been processed and the paths in _FILES will be invalid. - if (isset($upload_cache[$source])) { - return $upload_cache[$source]; + if (isset($upload_cache[$form_field_name])) { + return $upload_cache[$form_field_name]; } // Make sure there's an upload to process. - if (empty($_FILES['files']['name'][$source])) { + if (empty($_FILES['files']['name'][$form_field_name])) { return NULL; } // Check for file upload errors and return FALSE if a lower level system // error occurred. For a complete list of errors: // See http://php.net/manual/features.file-upload.errors.php. - switch ($_FILES['files']['error'][$source]) { + switch ($_FILES['files']['error'][$form_field_name]) { case UPLOAD_ERR_INI_SIZE: case UPLOAD_ERR_FORM_SIZE: - drupal_set_message(t('The file %file could not be saved, because it exceeds %maxsize, the maximum allowed size for uploads.', array('%file' => $_FILES['files']['name'][$source], '%maxsize' => format_size(file_upload_max_size()))), 'error'); + drupal_set_message(t('The file %file could not be saved, because it exceeds %maxsize, the maximum allowed size for uploads.', array('%file' => $_FILES['files']['name'][$form_field_name], '%maxsize' => format_size(file_upload_max_size()))), 'error'); return FALSE; case UPLOAD_ERR_PARTIAL: case UPLOAD_ERR_NO_FILE: - drupal_set_message(t('The file %file could not be saved, because the upload did not complete.', array('%file' => $_FILES['files']['name'][$source])), 'error'); + drupal_set_message(t('The file %file could not be saved, because the upload did not complete.', array('%file' => $_FILES['files']['name'][$form_field_name])), 'error'); return FALSE; case UPLOAD_ERR_OK: // Final check that this is a valid upload, if it isn't, use the // default error handler. - if (is_uploaded_file($_FILES['files']['tmp_name'][$source])) { + if (is_uploaded_file($_FILES['files']['tmp_name'][$form_field_name])) { break; } // Unknown error default: - drupal_set_message(t('The file %file could not be saved. An unknown error has occurred.', array('%file' => $_FILES['files']['name'][$source])), 'error'); + drupal_set_message(t('The file %file could not be saved. An unknown error has occurred.', array('%file' => $_FILES['files']['name'][$form_field_name])), 'error'); return FALSE; } @@ -1480,10 +1481,10 @@ function file_save_upload($source, $validators = array(), $destination = FALSE, $file = new stdClass(); $file->uid = $user->uid; $file->status = 0; - $file->filename = trim(drupal_basename($_FILES['files']['name'][$source]), '.'); - $file->uri = $_FILES['files']['tmp_name'][$source]; + $file->filename = trim(drupal_basename($_FILES['files']['name'][$form_field_name]), '.'); + $file->uri = $_FILES['files']['tmp_name'][$form_field_name]; $file->filemime = file_get_mimetype($file->filename); - $file->filesize = $_FILES['files']['size'][$source]; + $file->filesize = $_FILES['files']['size'][$form_field_name]; $extensions = ''; if (isset($validators['file_validate_extensions'])) { @@ -1540,7 +1541,7 @@ function file_save_upload($source, $validators = array(), $destination = FALSE, return FALSE; } - $file->source = $source; + $file->source = $form_field_name; // A URI may already have a trailing slash or look like "public://". if (substr($destination, -1) != '/') { $destination .= '/'; @@ -1549,7 +1550,7 @@ function file_save_upload($source, $validators = array(), $destination = FALSE, // If file_destination() returns FALSE then $replace == FILE_EXISTS_ERROR and // there's an existing file so we need to bail. if ($file->destination === FALSE) { - drupal_set_message(t('The file %source could not be uploaded because a file by that name already exists in the destination %directory.', array('%source' => $source, '%directory' => $destination)), 'error'); + drupal_set_message(t('The file %source could not be uploaded because a file by that name already exists in the destination %directory.', array('%source' => $form_field_name, '%directory' => $destination)), 'error'); return FALSE; } @@ -1568,7 +1569,7 @@ function file_save_upload($source, $validators = array(), $destination = FALSE, else { $message .= ' ' . array_pop($errors); } - form_set_error($source, $message); + form_set_error($form_field_name, $message); return FALSE; } @@ -1576,8 +1577,8 @@ function file_save_upload($source, $validators = array(), $destination = FALSE, // directory. This overcomes open_basedir restrictions for future file // operations. $file->uri = $file->destination; - if (!drupal_move_uploaded_file($_FILES['files']['tmp_name'][$source], $file->uri)) { - form_set_error($source, t('File upload error. Could not move uploaded file.')); + if (!drupal_move_uploaded_file($_FILES['files']['tmp_name'][$form_field_name], $file->uri)) { + form_set_error($form_field_name, t('File upload error. Could not move uploaded file.')); watchdog('file', 'Upload error. Could not move uploaded file %file to destination %destination.', array('%file' => $file->filename, '%destination' => $file->uri)); return FALSE; } @@ -1597,7 +1598,7 @@ function file_save_upload($source, $validators = array(), $destination = FALSE, // If we made it this far it's safe to record this file in the database. if ($file = file_save($file)) { // Add file to the cache. - $upload_cache[$source] = $file; + $upload_cache[$form_field_name] = $file; return $file; } return FALSE; diff --git a/includes/form.inc b/includes/form.inc index fd80e09bb..846bcb51f 100644 --- a/includes/form.inc +++ b/includes/form.inc @@ -15,10 +15,9 @@ * reference the form builder function using \@see. For examples, of this see * system_modules_uninstall() or user_pass(), the latter of which has the * following in its doxygen documentation: - * - * \@ingroup forms - * \@see user_pass_validate(). - * \@see user_pass_submit(). + * - \@ingroup forms + * - \@see user_pass_validate() + * - \@see user_pass_submit() * * @} */ @@ -3101,8 +3100,7 @@ function form_process_radios($element) { * @param $variables * An associative array containing: * - element: An associative array containing the properties of the element. - * Properties used: #title, #value, #return_value, #description, #required, - * #attributes, #checked. + * Properties used: #id, #name, #attributes, #checked, #return_value. * * @ingroup themeable */ @@ -4294,7 +4292,7 @@ function element_validate_number($element, &$form_state) { * returns any user input in the 'results' or 'message' keys of $context, * it must also sanitize them first. * - * Sample batch operations: + * Sample callback_batch_operation(): * @code * // Simple and artificial: load a node of a given type for a given user * function my_function_1($uid, $type, &$context) { @@ -4346,7 +4344,7 @@ function element_validate_number($element, &$form_state) { * } * @endcode * - * Sample 'finished' callback: + * Sample callback_batch_finished(): * @code * function batch_test_finished($success, $results, $operations) { * // The 'success' parameter means no fatal PHP errors were detected. All @@ -4385,12 +4383,14 @@ function element_validate_number($element, &$form_state) { * @param $batch_definition * An associative array defining the batch, with the following elements (all * are optional except as noted): - * - operations: (required) Array of function calls to be performed. + * - operations: (required) Array of operations to be performed, where each + * item is an array consisting of the name of an implementation of + * callback_batch_operation() and an array of parameter. * Example: * @code * array( - * array('my_function_1', array($arg1)), - * array('my_function_2', array($arg2_1, $arg2_2)), + * array('callback_batch_operation_1', array($arg1)), + * array('callback_batch_operation_2', array($arg2_1, $arg2_2)), * ) * @endcode * - title: A safe, translated string to use as the title for the progress @@ -4402,10 +4402,10 @@ function element_validate_number($element, &$form_state) { * @elapsed. Defaults to t('Completed @current of @total.'). * - error_message: Message displayed if an error occurred while processing * the batch. Defaults to t('An error has occurred.'). - * - finished: Name of a function to be executed after the batch has - * completed. This should be used to perform any result massaging that may - * be needed, and possibly save data in $_SESSION for display after final - * page redirection. + * - finished: Name of an implementation of callback_batch_finished(). This is + * executed after the batch has completed. This should be used to perform + * any result massaging that may be needed, and possibly save data in + * $_SESSION for display after final page redirection. * - file: Path to the file containing the definitions of the 'operations' and * 'finished' functions, for instance if they don't reside in the main * .module file. The path should be relative to base_path(), and thus should diff --git a/includes/menu.inc b/includes/menu.inc index aef557a24..fa5a71e73 100644 --- a/includes/menu.inc +++ b/includes/menu.inc @@ -1000,7 +1000,7 @@ function menu_tree($menu_name) { } /** - * Returns a rendered menu tree. + * Returns an output structure for rendering a menu tree. * * The menu item's LI element is given one of the following classes: * - expanded: The menu item is showing its submenu. diff --git a/includes/registry.inc b/includes/registry.inc index f6c81eb1a..5fc767487 100644 --- a/includes/registry.inc +++ b/includes/registry.inc @@ -10,7 +10,7 @@ * @{ * The code registry engine. * - * Drupal maintains an internal registry of all functions or classes in the + * Drupal maintains an internal registry of all interfaces or classes in the * system, allowing it to lazy-load code files as needed (reducing the amount * of code that must be parsed on each request). */ @@ -120,7 +120,10 @@ function registry_get_parsed_files() { } /** - * Parse all files that have changed since the registry was last built, and save their function and class listings. + * Parse all changed files and save their interface and class listings. + * + * Parse all files that have changed since the registry was last built, and save + * their interface and class listings. * * @param $files * The list of files to check and parse. @@ -149,7 +152,7 @@ function _registry_parse_files($files) { } /** - * Parse a file and save its function and class listings. + * Parse a file and save its interface and class listings. * * @param $filename * Name of the file we are going to parse. |