diff --git a/core/modules/file/file.module b/core/modules/file/file.module index 08e9438..6d8217d 100644 --- a/core/modules/file/file.module +++ b/core/modules/file/file.module @@ -51,10 +51,12 @@ function file_help($route_name, RouteMatchInterface $route_match) { /** * Loads file entities from the database. * - * @param array $fids - * (optional) An array of entity IDs. If omitted, all entities are loaded. + * @param array|null $fids + * (optional) An array of entity IDs. If omitted or NULL, all entities are + * loaded. * @param bool $reset - * Whether to reset the internal file_load_multiple() cache. + * (optional) Whether to reset the internal file_load_multiple() cache. + * Defaults to FALSE. * * @return array * An array of file entities, indexed by fid. @@ -80,9 +82,10 @@ function file_load_multiple(array $fids = NULL, $reset = FALSE) { * @param int $fid * A file ID. * @param bool $reset - * Whether to reset the internal file_load_multiple() cache. + * (optional) Whether to reset the internal file_load_multiple() cache. + * Defaults to FALSE. * - * @return \Drupal\file\FileInterface + * @return \Drupal\file\FileInterface|null * A file entity or NULL if the file was not found. * * @deprecated in Drupal 8.x, will be removed before Drupal 9.0. @@ -116,19 +119,20 @@ function file_load($fid, $reset = FALSE) { * * @param \Drupal\file\FileInterface $source * A file entity. - * @param string $destination - * A string containing the destination that $source should be copied to. - * This must be a stream wrapper URI. + * @param string|null $destination + * (optional) A string containing the destination that $source should be + * copied to. This must be a stream wrapper URI. Defaults to NULL. * @param int $replace - * Replace behavior when the destination file already exists: - * - FILE_EXISTS_REPLACE - Replace the existing file. If a managed file with - * the destination name exists then its database entry will be updated. If - * no database entry is found then a new one will be created. - * - FILE_EXISTS_RENAME - Append _{incrementing number} until the filename is - * unique. - * - FILE_EXISTS_ERROR - Do nothing and return FALSE. + * (optional) Replace behavior when the destination file already exists. + * Possible values include: + * - FILE_EXISTS_REPLACE: Replace the existing file. If a managed file with + * the destination name exists, then its database entry will be updated. If + * no database entry is found, then a new one will be created. + * - FILE_EXISTS_RENAME: (default) Append _{incrementing number} until the + * filename is unique. + * - FILE_EXISTS_ERROR: Do nothing and return FALSE. * - * @return \Drupal\file\FileInterface|FALSE + * @return \Drupal\file\FileInterface|false * File object if the copy is successful, or FALSE in the event of an error. * * @see file_unmanaged_copy() @@ -191,21 +195,21 @@ function file_copy(FileInterface $source, $destination = NULL, $replace = FILE_E * * @param \Drupal\file\FileInterface $source * A file entity. - * @param string $destination - * A string containing the destination that $source should be moved to. - * This must be a stream wrapper URI. + * @param string|null $destination + * (optional) A string containing the destination that $source should be moved + * to. This must be a stream wrapper URI. Defaults to NULL. * @param int $replace - * Replace behavior when the destination file already exists: - * - FILE_EXISTS_REPLACE - Replace the existing file. If a managed file with - * the destination name exists then its database entry will be updated and - * $source->delete() called after invoking hook_file_move(). - * If no database entry is found then the source files record will be - * updated. - * - FILE_EXISTS_RENAME - Append _{incrementing number} until the filename is - * unique. - * - FILE_EXISTS_ERROR - Do nothing and return FALSE. + * (optional) The replace behavior when the destination file already exists. + * Possible values include: + * - FILE_EXISTS_REPLACE: Replace the existing file. If a managed file with + * the destination name exists then its database entry will be updated and + * $source->delete() called after invoking hook_file_move(). If no database + * entry is found, then the source files record will be updated. + * - FILE_EXISTS_RENAME: (default) Append _{incrementing number} until the + * filename is unique. + * - FILE_EXISTS_ERROR: Do nothing and return FALSE. * - * @return \Drupal\file\FileInterface + * @return \Drupal\file\FileInterface|false * Resulting file entity for success, or FALSE in the event of an error. * * @see file_unmanaged_move() @@ -268,12 +272,15 @@ function file_move(FileInterface $source, $destination = NULL, $replace = FILE_E * @param \Drupal\file\FileInterface $file * A file entity. * @param array $validators - * An optional, associative array of callback functions used to validate the + * (optional) An associative array of callback functions used to validate the * file. The keys are function names and the values arrays of callback - * parameters which will be passed in after the file entity. The - * functions should return an array of error messages; an empty array + * parameters which will be passed in after the file entity. The functions + * should return an array of error messages; an empty array * indicates that the file passed validation. The functions will be called in * the order specified. + * The hook hook_file_validate() will nonetheless be called so other modules can + * validate the new file. The callback functions will be called in the order + * specified in the array. * * @return array * An array containing validation error messages. @@ -345,11 +352,11 @@ function file_validate_extensions(FileInterface $file, $extensions) { * @param \Drupal\file\FileInterface $file * A file entity. * @param int $file_limit - * An integer specifying the maximum file size in bytes. Zero indicates that - * no limit should be enforced. + * (optional) An integer specifying the maximum file size in bytes. Zero (the + * default) indicates that no limit should be enforced. * @param int $user_limit - * An integer specifying the maximum number of bytes the user is allowed. - * Zero indicates that no limit should be enforced. + * (optional) An integer specifying the maximum number of bytes the user is + * allowed. Zero (the default) indicates that no limit should be enforced. * * @return array * An array. If the file size exceeds limits, it will contain an error @@ -380,7 +387,7 @@ function file_validate_size(FileInterface $file, $file_limit = 0, $user_limit = * A file entity. * * @return array - * An array. If the file is not an image, it will contain an error message. + * An array with validation errors, empty array indicates no problems. * * @see hook_file_validate() */ @@ -405,16 +412,17 @@ function file_validate_is_image(FileInterface $file) { * * @param \Drupal\file\FileInterface $file * A file entity. This function may resize the file affecting its size. - * @param string $maximum_dimensions - * An optional string in the form WIDTHxHEIGHT e.g. '640x480' or '85x85'. If - * an image toolkit is installed the image will be resized down to these - * dimensions. A value of 0 indicates no restriction on size, so resizing - * will be attempted. - * @param string $minimum_dimensions - * An optional string in the form WIDTHxHEIGHT. This will check that the - * image meets a minimum size. A value of 0 indicates no restriction. + * @param string|int $maximum_dimensions + * (optional) A string in the form WIDTHxHEIGHT; for example, '640x480' or + * '85x85'. If an image toolkit is installed, the image will be resized down + * to these dimensions. A value of zero (the default) indicates no restriction + * on size, so no resizing will be attempted. + * @param string|int $minimum_dimensions + * (optional) A string in the form WIDTHxHEIGHT. This will check that the + * image meets a minimum size. A value of zero (the default) indicates that + * there is no restriction on size. * - * @return + * @return string[] * An array. If the file is an image and did not meet the requirements, it * will contain an error message. * @@ -460,20 +468,22 @@ function file_validate_image_resolution(FileInterface $file, $maximum_dimensions * * @param string $data * A string containing the contents of the file. - * @param string $destination - * A string containing the destination URI. This must be a stream wrapper URI. - * If no value is provided, a randomized name will be generated and the file - * will be saved using Drupal's default files scheme, usually "public://". + * @param string|null $destination + * (optional) A string containing the destination URI. This must be a stream + * wrapper URI. If no value or NULL is provided, a randomized name will be + * generated and the file will be saved using Drupal's default files scheme, + * usually "public://". * @param int $replace - * Replace behavior when the destination file already exists: - * - FILE_EXISTS_REPLACE - Replace the existing file. If a managed file with - * the destination name exists then its database entry will be updated. If - * no database entry is found then a new one will be created. - * - FILE_EXISTS_RENAME - Append _{incrementing number} until the filename is - * unique. - * - FILE_EXISTS_ERROR - Do nothing and return FALSE. + * (optional) The replace behavior when the destination file already exists. + * Possible values include: + * - FILE_EXISTS_REPLACE: Replace the existing file. If a managed file with + * the destination name exists, then its database entry will be updated. If + * no database entry is found, then a new one will be created. + * - FILE_EXISTS_RENAME: (default) Append _{incrementing number} until the + * filename is unique. + * - FILE_EXISTS_ERROR: Do nothing and return FALSE. * - * @return \Drupal\file\FileInterface + * @return \Drupal\file\FileInterface|false * A file entity, or FALSE on error. * * @see file_unmanaged_save_data() @@ -666,39 +676,34 @@ function file_cron() { * A string that is the associative array key of the upload form element in * the form array. * @param array $validators - * An optional, associative array of callback functions used to validate the + * (optional) An associative array of callback functions used to validate the * file. See file_validate() for a full discussion of the array format. - * If no extension validator is provided it will default to a limited safe - * list of extensions which is as follows: "jpg jpeg gif png txt - * doc xls pdf ppt pps odt ods odp". To allow all extensions you must - * explicitly set the 'file_validate_extensions' validator to an empty array - * (Beware: this is not safe and should only be allowed for trusted users, if - * at all). - * @param string $destination - * 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://"). + * If the array is empty, it will be set up to call file_validate_extensions() + * with a safe list of extensions, as follows: "jpg jpeg gif png txt doc + * xls pdf ppt pps odt ods odp". To allow all extensions, you must explicitly + * set this array to ['file_validate_extensions' => '']. (Beware: + * This is not safe and should only be allowed for trusted users, if at all.) + * @param string|false $destination + * (optional) A string containing the URI that the file should be copied to. + * This must be a stream wrapper URI. If this value is omitted or set to + * FALSE, Drupal's temporary files scheme will be used ("temporary://"). * @param int $delta - * Delta of the file to save or NULL to save all files. Defaults to NULL. + * (optional) The delta of the file to save or NULL to save all files. + * Defaults to NULL. * @param int $replace - * Replace behavior when the destination file already exists: + * (optional) The replace behavior when the destination file already exists. + * Possible values include: * - FILE_EXISTS_REPLACE: Replace the existing file. - * - FILE_EXISTS_RENAME: Append _{incrementing number} until the filename is - * unique. + * - FILE_EXISTS_RENAME: (default) Append _{incrementing number} until the + * filename is unique. * - FILE_EXISTS_ERROR: Do nothing and return FALSE. * - * @return array + * @return FileInterface[]|null|false * Function returns array of files or a single file object if $delta * != NULL. Each file object contains the file information if the * upload succeeded or FALSE in the event of an error. Function - * returns NULL if no file was uploaded. - * - * The documentation for the "File interface" group, which you can find under - * Related topics, or the header at the top of this file, documents the - * components of a file entity. In addition to the standard components, - * this function adds: - * - source: Path to the file before it is moved. - * - destination: Path to the file after it is moved (same as 'uri'). + * returns NULL if no file was uploaded. FALSE will be returned if there was + * an error. */ function file_save_upload($form_field_name, $validators = array(), $destination = FALSE, $delta = NULL, $replace = FILE_EXISTS_RENAME) { $user = \Drupal::currentUser(); @@ -903,7 +908,7 @@ function file_save_upload($form_field_name, $validators = array(), $destination /** * Determines the preferred upload progress implementation. * - * @return string|FALSE + * @return string|false * A string indicating which upload progress system is available. Either "apc" * or "uploadprogress". If neither are available, returns FALSE. */ @@ -928,7 +933,7 @@ function file_progress_implementation() { * Implements hook_ENTITY_TYPE_predelete() for file entities. */ function file_file_predelete(File $file) { - // TODO: Remove references to a file that is in-use. + // @todo Remove references to a file that is in-use. } /** @@ -1151,7 +1156,7 @@ function file_managed_file_submit($form, FormStateInterface $form_state) { * @param \Drupal\Core\Form\FormStateInterface $form_state * The current state of the form. * - * @return array + * @return array|false * An array of file entities for each file that was saved, keyed by its file * ID, or FALSE if no files were saved. */ @@ -1426,20 +1431,21 @@ function file_icon_map($mime_type) { * * @param \Drupal\file\FileInterface $file * A file entity. - * @param \Drupal\Core\Field\FieldDefinitionInterface $field + * @param \Drupal\Core\Field\FieldDefinitionInterface|null $field * (optional) A field definition to be used for this check. If given, limits the - * reference check to the given field. + * reference check to the given field. Defaults to NULL. * @param int $age * (optional) A constant that specifies which references to count. Use - * EntityStorageInterface::FIELD_LOAD_REVISION to retrieve all + * EntityStorageInterface::FIELD_LOAD_REVISION (the default) to retrieve all * references within all revisions or * EntityStorageInterface::FIELD_LOAD_CURRENT to retrieve references - * only in the current revisions. + * only in the current revisions of all entities that have references to this + * file. * @param string $field_type * (optional) The name of a field type. If given, limits the reference check - * to fields of the given type. If both $field and $field_type is given but + * to fields of the given type. If both $field and $field_type are given but * $field is not the same type as $field_type, an empty array will be - * returned. + * returned. Defaults to 'file'. * * @return array * A multidimensional array. The keys are field_name, entity_type, @@ -1516,9 +1522,10 @@ function file_get_file_references(FileInterface $file, FieldDefinitionInterface * Formats human-readable version of file status. * * @param int $choice - * integer Status code. + * (optional) An integer status code. Defaults to NULL. + * * @return string - * string Text-represented file status. + * The file status as a string. */ function _views_file_status($choice = NULL) { $status = array(