file.inc 63.7 KB
Newer Older
Dries's avatar
 
Dries committed
1
<?php
2
// $Id$
Kjartan's avatar
Kjartan committed
3

Dries's avatar
 
Dries committed
4 5 6 7 8
/**
 * @file
 * API for handling file uploads and server file management.
 */

Kjartan's avatar
Kjartan committed
9
/**
Kjartan's avatar
Kjartan committed
10
 * @defgroup file File interface
Kjartan's avatar
Kjartan committed
11
 * @{
Dries's avatar
 
Dries committed
12
 * Common file handling functions.
13 14 15 16
 *
 * Fields on the file object:
 * - fid - File ID
 * - uid - The {users}.uid of the user who is associated with the file.
17 18 19
 * - filename - Name of the file with no path components. This may differ from
 *   the basename of the filepath if the file is renamed to avoid overwriting
 *   an existing file.
20 21 22 23 24 25 26
 * - filepath - Path of the file relative to Drupal root.
 * - filemime - The file's MIME type.
 * - filesize - The size of the file in bytes.
 * - status - A bitmapped field indicating the status of the file the least
 *   sigifigant bit indicates temporary (1) or permanent (0). Temporary files
 *   older than DRUPAL_MAXIMUM_TEMP_FILE_AGE will be removed during a cron run.
 * - timestamp - UNIX timestamp for the date the file was added to the database.
Dries's avatar
 
Dries committed
27 28
 */

29 30 31 32 33 34
/**
 * Flag to indicate that the 'public' file download method is enabled.
 *
 * When using this method, files are available from a regular HTTP request,
 * which provides no additional access restrictions.
 */
Dries's avatar
 
Dries committed
35
define('FILE_DOWNLOADS_PUBLIC', 1);
36 37 38 39 40 41 42

/**
 * Flag to indicate that the 'private' file download method is enabled.
 *
 * When using this method, all file requests are served by Drupal, during which
 * access-control checking can be performed.
 */
Dries's avatar
 
Dries committed
43
define('FILE_DOWNLOADS_PRIVATE', 2);
44 45

/**
46
 * Flag used by file_check_directory() -- create directory if not present.
47
 */
Dries's avatar
 
Dries committed
48
define('FILE_CREATE_DIRECTORY', 1);
49 50

/**
51
 * Flag used by file_check_directory() -- file permissions may be changed.
52
 */
Dries's avatar
 
Dries committed
53
define('FILE_MODIFY_PERMISSIONS', 2);
54 55

/**
56
 * Flag for dealing with existing files: Appends number until name is unique.
57
 */
Dries's avatar
 
Dries committed
58
define('FILE_EXISTS_RENAME', 0);
59 60 61 62

/**
 * Flag for dealing with existing files: Replace the existing file.
 */
Dries's avatar
 
Dries committed
63
define('FILE_EXISTS_REPLACE', 1);
64 65 66 67

/**
 * Flag for dealing with existing files: Do nothing and return FALSE.
 */
Dries's avatar
 
Dries committed
68
define('FILE_EXISTS_ERROR', 2);
Dries's avatar
 
Dries committed
69

70
/**
71
 * File status -- File has been temporarily saved to the {files} tables.
72
 *
73 74
 * Drupal's file garbage collection will delete the file and remove it from the
 * files table after a set period of time.
75 76
 */
define('FILE_STATUS_TEMPORARY', 0);
77 78 79 80 81 82 83 84

/**
 * File status -- File has been permanently saved to the {files} tables.
 *
 * If you wish to add custom statuses for use by contrib modules please expand
 * as binary flags and consider the first 8 bits reserved.
 * (0,1,2,4,8,16,32,64,128).
 */
85 86
define('FILE_STATUS_PERMANENT', 1);

Dries's avatar
 
Dries committed
87 88
/**
 * Create the download path to a file.
Dries's avatar
 
Dries committed
89
 *
90 91
 * @param $path A string containing the path of the file to generate URL for.
 * @return A string containing a URL that can be used to download the file.
Dries's avatar
 
Dries committed
92 93
 */
function file_create_url($path) {
94 95
  // Strip file_directory_path from $path. We only include relative paths in
  // URLs.
96
  if (strpos($path, file_directory_path() . '/') === 0) {
97
    $path = trim(substr($path, strlen(file_directory_path())), '\\/');
Kjartan's avatar
Kjartan committed
98
  }
99
  switch (variable_get('file_downloads', FILE_DOWNLOADS_PUBLIC)) {
Dries's avatar
 
Dries committed
100
    case FILE_DOWNLOADS_PUBLIC:
101
      return $GLOBALS['base_url'] . '/' . file_directory_path() . '/' . str_replace('\\', '/', $path);
Dries's avatar
 
Dries committed
102
    case FILE_DOWNLOADS_PRIVATE:
103
      return url('system/files/' . $path, array('absolute' => TRUE));
Dries's avatar
 
Dries committed
104 105 106 107
  }
}

/**
108 109
 * Make sure the destination is a complete path and resides in the file system
 * directory, if it is not prepend the file system directory.
Dries's avatar
 
Dries committed
110
 *
111 112 113 114 115 116 117
 * @param $destination
 *   A string containing the path to verify. If this value is omitted, Drupal's
 *   'files' directory will be used.
 * @return
 *   A string containing the path to file, with file system directory appended
 *   if necessary, or FALSE if the path is invalid (i.e. outside the configured
 *   'files' or temp directories).
Dries's avatar
 
Dries committed
118
 */
119
function file_create_path($destination = NULL) {
120
  $file_path = file_directory_path();
121
  if (is_null($destination)) {
122
    return $file_path;
Dries's avatar
 
Dries committed
123
  }
124 125 126 127
  // file_check_location() checks whether the destination is inside the Drupal
  // files directory.
  if (file_check_location($destination, $file_path)) {
    return $destination;
Dries's avatar
 
Dries committed
128
  }
129 130
  // Check if the destination is instead inside the Drupal temporary files
  // directory.
131
  elseif (file_check_location($destination, file_directory_temp())) {
132
    return $destination;
133
  }
134
  // Not found, try again with prefixed directory path.
135
  elseif (file_check_location($file_path . '/' . $destination, $file_path)) {
136
    return $file_path . '/' . $destination;
137 138 139
  }
  // File not found.
  return FALSE;
Dries's avatar
 
Dries committed
140 141 142
}

/**
143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159
 * Check that the directory exists and is writable.
 *
 * Directories need to have execute permissions to be considered a directory by
 * FTP servers, etc.
 *
 * @param $directory
 *   A string containing the name of a directory path.
 * @param $mode
 *   A Boolean value to indicate if the directory should be created if it does
 *   not exist or made writable if it is read-only.
 * @param $form_item
 *   An optional string containing the name of a form item that any errors will
 *   be attached to. This is useful for settings forms that require the user to
 *   specify a writable directory. If it can't be made to work, a form error
 *   will be set preventing them from saving the settings.
 * @return
 *   FALSE when directory not found, or TRUE when directory exists.
Dries's avatar
 
Dries committed
160
 */
161
function file_check_directory(&$directory, $mode = FALSE, $form_item = NULL) {
Dries's avatar
 
Dries committed
162
  $directory = rtrim($directory, '/\\');
Dries's avatar
 
Dries committed
163 164 165

  // Check if directory exists.
  if (!is_dir($directory)) {
166 167
    if (($mode & FILE_CREATE_DIRECTORY) && @mkdir($directory)) {
      @chmod($directory, 0775); // Necessary for non-webserver users.
Dries's avatar
 
Dries committed
168 169 170
    }
    else {
      if ($form_item) {
171
        form_set_error($form_item, t('The directory %directory does not exist.', array('%directory' => $directory)));
172
        watchdog('file system', 'The directory %directory does not exist.', array('%directory' => $directory), WATCHDOG_ERROR);
Dries's avatar
 
Dries committed
173
      }
174
      return FALSE;
Dries's avatar
 
Dries committed
175 176 177 178 179
    }
  }

  // Check to see if the directory is writable.
  if (!is_writable($directory)) {
180 181 182 183 184 185 186
    // If not able to modify permissions, or if able to, but chmod
    // fails, return false.
    if (!$mode || (($mode & FILE_MODIFY_PERMISSIONS) && !@chmod($directory, 0775))) {
      if ($form_item) {
        form_set_error($form_item, t('The directory %directory is not writable', array('%directory' => $directory)));
        watchdog('file system', 'The directory %directory is not writable, because it does not have the correct permissions set.', array('%directory' => $directory), WATCHDOG_ERROR);
      }
187
      return FALSE;
Dries's avatar
 
Dries committed
188 189 190
    }
  }

191
  if ((file_directory_path() == $directory || file_directory_temp() == $directory) && !is_file("$directory/.htaccess")) {
192
    $htaccess_lines = "SetHandler Drupal_Security_Do_Not_Remove_See_SA_2006_006\nOptions None\nOptions +FollowSymLinks";
Gerhard Killesreiter's avatar
Gerhard Killesreiter committed
193
    if (($fp = fopen("$directory/.htaccess", 'w')) && fputs($fp, $htaccess_lines)) {
194
      fclose($fp);
195
      chmod($directory . '/.htaccess', 0664);
196 197
    }
    else {
198
      $variables = array('%directory' => $directory, '!htaccess' => '<br />' . nl2br(check_plain($htaccess_lines)));
199 200
      form_set_error($form_item, t("Security warning: Couldn't write .htaccess file. Please create a .htaccess file in your %directory directory which contains the following lines: <code>!htaccess</code>", $variables));
      watchdog('security', "Security warning: Couldn't write .htaccess file. Please create a .htaccess file in your %directory directory which contains the following lines: <code>!htaccess</code>", $variables, WATCHDOG_ERROR);
201 202 203
    }
  }

204
  return TRUE;
Dries's avatar
 
Dries committed
205 206 207
}

/**
208
 * Checks path to see if it is a directory, or a directory/file.
Dries's avatar
 
Dries committed
209
 *
210 211 212 213 214
 * @param $path
 *   A string containing a file path. This will be set to the directory's path.
 * @return
 *   If the directory is not in a Drupal writable directory, FALSE is returned.
 *   Otherwise, the base name of the path is returned.
Dries's avatar
 
Dries committed
215 216 217 218 219 220 221 222 223 224 225 226 227 228
 */
function file_check_path(&$path) {
  // Check if path is a directory.
  if (file_check_directory($path)) {
    return '';
  }

  // Check if path is a possible dir/file.
  $filename = basename($path);
  $path = dirname($path);
  if (file_check_directory($path)) {
    return $filename;
  }

229
  return FALSE;
Dries's avatar
 
Dries committed
230 231 232
}

/**
233 234 235 236 237
 * Check if a file is really located inside $directory.
 *
 * This should be used to make sure a file specified is really located within
 * the directory to prevent exploits. Note that the file or path being checked
 * does not actually need to exist yet.
Dries's avatar
 
Dries committed
238 239
 *
 * @code
240
 *   // Returns FALSE:
Dries's avatar
 
Dries committed
241 242 243
 *   file_check_location('/www/example.com/files/../../../etc/passwd', '/www/example.com/files');
 * @endcode
 *
244 245 246 247 248 249 250
 * @param $source
 *   A string set to the file to check.
 * @param $directory
 *   A string where the file should be located.
 * @return
 *   FALSE if the path does not exist in the directory; otherwise, the real
 *   path of the source.
Dries's avatar
 
Dries committed
251
 */
252
function file_check_location($source, $directory = '') {
253 254 255 256 257
  $check = realpath($source);
  if ($check) {
    $source = $check;
  }
  else {
258
    // This file does not yet exist.
259
    $source = realpath(dirname($source)) . '/' . basename($source);
260
  }
261
  $directory = realpath($directory);
Dries's avatar
 
Dries committed
262
  if ($directory && strpos($source, $directory) !== 0) {
263
    return FALSE;
Dries's avatar
 
Dries committed
264 265 266 267 268
  }
  return $source;
}

/**
269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329
 * Load a file object from the database.
 *
 * @param $param
 *   Either the id of a file or an array of conditions to match against in the
 *   database query.
 * @param $reset
 *   Whether to reset the internal file_load cache.
 * @return
 *   A file object.
 *
 * @see hook_file_load()
 */
function file_load($param, $reset = NULL) {
  static $files = array();

  if ($reset) {
    $files = array();
  }

  if (is_numeric($param)) {
    if (isset($files[(string) $param])) {
      return is_object($files[$param]) ? clone $files[$param] : $files[$param];
    }
    $result = db_query('SELECT f.* FROM {files} f WHERE f.fid = :fid', array(':fid' => $param));
  }
  elseif (is_array($param)) {
    // Turn the conditions into a query.
    $cond = array();
    $arguments = array();
    foreach ($param as $key => $value) {
      $cond[] = 'f.' . db_escape_table($key) . " = '%s'";
      $arguments[] = $value;
    }
    $result = db_query('SELECT f.* FROM {files} f WHERE ' . implode(' AND ', $cond), $arguments);
  }
  else {
    return FALSE;
  }
  $file = $result->fetch(PDO::FETCH_OBJ);

  if ($file && $file->fid) {
    // Allow modules to add or change the file object.
    module_invoke_all('file_load', $file);

    // Cache the fully loaded value.
    $files[(string) $file->fid] = clone $file;
  }

  return $file;
}

/**
 * Save a file object to the database.
 *
 * If the $file->fid is not set a new record will be added. Re-saving an
 * existing file will not change its status.
 *
 * @param $file
 *   A file object returned by file_load().
 * @return
 *   The updated file object.
330
 *
331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380
 * @see hook_file_insert()
 * @see hook_file_update()
 */
function file_save($file) {
  $file = (object)$file;
  $file->timestamp = REQUEST_TIME;
  $file->filesize = filesize($file->filepath);

  if (empty($file->fid)) {
    drupal_write_record('files', $file);
    // Inform modules about the newly added file.
    module_invoke_all('file_insert', $file);
  }
  else {
    drupal_write_record('files', $file, 'fid');
    // Inform modules that the file has been updated.
    module_invoke_all('file_update', $file);
  }

  return $file;
}

/**
 * Copy a file to a new location and adds a file record to the database.
 *
 * This function should be used when manipulating files that have records
 * stored in the database. This is a powerful function that in many ways
 * performs like an advanced version of copy().
 * - Checks if $source and $destination are valid and readable/writable.
 * - Checks that $source is not equal to $destination; if they are an error
 *   is reported.
 * - If file already exists in $destination either the call will error out,
 *   replace the file or rename the file based on the $replace parameter.
 * - Adds the new file to the files database. If the source file is a
 *   temporary file, the resulting file will also be a temporary file.
 *   @see file_save_upload about temporary files.
 *
 * @param $source
 *   A file object.
 * @param $destination
 *   A string containing the directory $source should be copied to. If this
 *   value is omitted, Drupal's 'files' directory will be used.
 * @param $replace
 *   Replace behavior when the destination file already exists:
 *   - FILE_EXISTS_REPLACE - Replace the existing file.
 *   - FILE_EXISTS_RENAME - Append _{incrementing number} until the filename is
 *                          unique.
 *   - FILE_EXISTS_ERROR - Do nothing and return FALSE.
 * @return
 *   File object if the copy is successful, or FALSE in the event of an error.
381
 *
382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404
 * @see file_unmanaged_copy()
 * @see hook_file_copy()
 */
function file_copy($source, $destination = NULL, $replace = FILE_EXISTS_RENAME) {
  $source = (object)$source;

  if ($filepath = file_unmanaged_copy($source->filepath, $destination, $replace)) {
    $file = clone $source;
    $file->fid      = NULL;
    $file->filename = basename($filepath);
    $file->filepath = $filepath;
    if ($file = file_save($file)) {
      // Inform modules that the file has been copied.
      module_invoke_all('file_copy', $file, $source);
      return $file;
    }
  }
  return FALSE;
}

/**
 * Copy a file to a new location without calling any hooks or making any
 * changes to the database.
Dries's avatar
 
Dries committed
405
 *
406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423
 * This is a powerful function that in many ways performs like an advanced
 * version of copy().
 * - Checks if $source and $destination are valid and readable/writable.
 * - Checks that $source is not equal to $destination; if they are an error
 *   is reported.
 * - If file already exists in $destination either the call will error out,
 *   replace the file or rename the file based on the $replace parameter.
 *
 * @param $source
 *   A string specifying the file location of the original file.
 * @param $destination
 *   A string containing the directory $source should be copied to. If this
 *   value is omitted, Drupal's 'files' directory will be used.
 * @param $replace
 *   Replace behavior when the destination file already exists:
 *   - FILE_EXISTS_REPLACE - Replace the existing file.
 *   - FILE_EXISTS_RENAME - Append _{incrementing number} until the filename is
 *                          unique.
424
 *   - FILE_EXISTS_ERROR - Do nothing and return FALSE.
425 426
 * @return
 *   The path to the new file, or FALSE in the event of an error.
427
 *
428
 * @see file_copy()
Dries's avatar
 
Dries committed
429
 */
430
function file_unmanaged_copy($source, $destination = NULL, $replace = FILE_EXISTS_RENAME) {
431 432 433 434 435
  $source = realpath($source);
  if (!file_exists($source)) {
    drupal_set_message(t('The specified file %file could not be copied, because no file by that name exists. Please check that you supplied the correct filename.', array('%file' => $source)), 'error');
    return FALSE;
  }
Dries's avatar
 
Dries committed
436

437 438
  $destination = file_create_path($destination);
  $directory = $destination;
Dries's avatar
 
Dries committed
439 440 441
  $basename = file_check_path($directory);

  // Make sure we at least have a valid directory.
442
  if ($basename === FALSE) {
443
    drupal_set_message(t('The specified file %file could not be copied, because the destination %directory is not properly configured.', array('%file' => $source, '%directory' => $destination)), 'error');
444
    return FALSE;
Dries's avatar
 
Dries committed
445 446
  }

447 448
  // If the destination file is not specified then use the filename of the
  // source file.
Dries's avatar
 
Dries committed
449
  $basename = $basename ? $basename : basename($source);
450
  $destination = file_destination($directory . '/' . $basename, $replace);
451

452 453 454
  if ($destination === FALSE) {
    drupal_set_message(t('The specified file %file could not be copied because a file by that name already exists in the destination.', array('%file' => $source)), 'error');
    return FALSE;
Dries's avatar
 
Dries committed
455
  }
456 457 458 459 460 461
  // Make sure source and destination filenames are not the same, makes no
  // sense to copy it if they are. In fact copying the file will most likely
  // result in a 0 byte file. Which is bad. Real bad.
  if ($source == realpath($destination)) {
    drupal_set_message(t('The specified file %file was not copied because it would overwrite itself.', array('%file' => $source)), 'error');
    return FALSE;
Dries's avatar
 
Dries committed
462
  }
463 464 465
  if (!@copy($source, $destination)) {
    drupal_set_message(t('The specified file %file could not be copied.', array('%file' => $source)), 'error');
    return FALSE;
Dries's avatar
 
Dries committed
466
  }
Dries's avatar
 
Dries committed
467

468 469 470 471 472 473 474
  // Give everyone read access so that FTP'd users or
  // non-webserver users can see/read these files,
  // and give group write permissions so group members
  // can alter files uploaded by the webserver.
  @chmod($destination, 0664);

  return $destination;
Dries's avatar
 
Dries committed
475 476
}

477 478 479 480
/**
 * Determines the destination path for a file depending on how replacement of
 * existing files should be handled.
 *
481 482 483 484
 * @param $destination
 *   A string specifying the desired path.
 * @param $replace
 *   Replace behavior when the destination file already exists.
485
 *   - FILE_EXISTS_REPLACE - Replace the existing file.
486
 *   - FILE_EXISTS_RENAME - Append _{incrementing number} until the filename is
487
 *                          unique.
488
 *   - FILE_EXISTS_ERROR - Do nothing and return FALSE.
489 490
 * @return
 *   The destination file path or FALSE if the file already exists and
491 492 493 494 495
 *   FILE_EXISTS_ERROR was specified.
 */
function file_destination($destination, $replace) {
  if (file_exists($destination)) {
    switch ($replace) {
496 497 498 499
      case FILE_EXISTS_REPLACE:
        // Do nothing here, we want to overwrite the existing file.
        break;

500 501 502 503 504 505 506
      case FILE_EXISTS_RENAME:
        $basename = basename($destination);
        $directory = dirname($destination);
        $destination = file_create_filename($basename, $directory);
        break;

      case FILE_EXISTS_ERROR:
507
        drupal_set_message(t('The specified file %file could not be copied, because a file by that name already exists in the destination.', array('%file' => $destination)), 'error');
508 509 510 511 512 513
        return FALSE;
    }
  }
  return $destination;
}

Dries's avatar
 
Dries committed
514
/**
515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537
 * Move a file to a new location and update the file's database entry.
 *
 * Moving a file is performed by copying the file to the new location and then
 * deleting the original.
 * - Checks if $source and $destination are valid and readable/writable.
 * - Performs a file move if $source is not equal to $destination.
 * - If file already exists in $destination either the call will error out,
 *   replace the file or rename the file based on the $replace parameter.
 * - Adds the new file to the files database.
 *
 * @param $source
 *   A file object.
 * @param $destination
 *   A string containing the directory $source should be copied to. If this
 *   value is omitted, Drupal's 'files' directory will be used.
 * @param $replace
 *   Replace behavior when the destination file already exists:
 *   - FILE_EXISTS_REPLACE - Replace the existing file.
 *   - FILE_EXISTS_RENAME - Append _{incrementing number} until the filename is
 *                          unique.
 *   - FILE_EXISTS_ERROR - Do nothing and return FALSE.
 * @return
 *   Resulting file object for success, or FALSE in the event of an error.
538
 *
539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561
 * @see file_unmanaged_move()
 * @see hook_file_move()
 */
function file_move($source, $destination = NULL, $replace = FILE_EXISTS_RENAME) {
  $source = (object)$source;

  if ($filepath = file_unmanaged_move($source->filepath, $destination, $replace)) {
    $file = clone $source;
    $file->filename = basename($filepath);
    $file->filepath = $filepath;
    if ($file = file_save($file)) {
      // Inform modules that the file has been moved.
      module_invoke_all('file_move', $file, $source);
      return $file;
    }
    drupal_set_message(t('The removal of the original file %file has failed.', array('%file' => $source->filepath)), 'error');
  }
  return FALSE;
}

/**
 * Move a file to a new location without calling any hooks or making any
 * changes to the database.
Dries's avatar
 
Dries committed
562
 *
563 564 565 566 567 568 569 570 571 572
 * @param $source
 *   A string specifying the file location of the original file.
 * @param $destination
 *   A string containing the directory $source should be copied to. If this
 *   value is omitted, Drupal's 'files' directory will be used.
 * @param $replace
 *   Replace behavior when the destination file already exists:
 *   - FILE_EXISTS_REPLACE - Replace the existing file.
 *   - FILE_EXISTS_RENAME - Append _{incrementing number} until the filename is
 *                          unique.
573
 *   - FILE_EXISTS_ERROR - Do nothing and return FALSE.
574 575
 * @return
 *   The filepath of the moved file, or FALSE in the event of an error.
576
 *
577
 * @see file_move()
Dries's avatar
 
Dries committed
578
 */
579 580 581
function file_unmanaged_move($source, $destination = NULL, $replace = FILE_EXISTS_RENAME) {
  $filepath = file_unmanaged_copy($source, $destination, $replace);
  if ($filepath == FALSE || file_unmanaged_delete($source) == FALSE) {
582
    return FALSE;
Dries's avatar
 
Dries committed
583
  }
584
  return $filepath;
Dries's avatar
 
Dries committed
585 586
}

587
/**
588 589 590 591 592 593 594 595 596 597 598 599
 * Munge the filename as needed for security purposes.
 *
 * For instance the file name "exploit.php.pps" would become "exploit.php_.pps".
 *
 * @param $filename
 *   The name of a file to modify.
 * @param $extensions
 *   A space separated list of extensions that should not be altered.
 * @param $alerts
 *   Whether alerts (watchdog, drupal_set_message()) should be displayed.
 * @return
 *   $filename The potentially modified $filename.
600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617
 */
function file_munge_filename($filename, $extensions, $alerts = TRUE) {
  $original = $filename;

  // Allow potentially insecure uploads for very savvy users and admin
  if (!variable_get('allow_insecure_uploads', 0)) {
    $whitelist = array_unique(explode(' ', trim($extensions)));

    // Split the filename up by periods. The first part becomes the basename
    // the last part the final extension.
    $filename_parts = explode('.', $filename);
    $new_filename = array_shift($filename_parts); // Remove file basename.
    $final_extension = array_pop($filename_parts); // Remove final extension.

    // Loop through the middle parts of the name and add an underscore to the
    // end of each section that could be a file extension but isn't in the list
    // of allowed extensions.
    foreach ($filename_parts as $filename_part) {
618
      $new_filename .= '.' . $filename_part;
619 620 621 622
      if (!in_array($filename_part, $whitelist) && preg_match("/^[a-zA-Z]{2,5}\d?$/", $filename_part)) {
        $new_filename .= '_';
      }
    }
623
    $filename = $new_filename . '.' . $final_extension;
624 625 626 627 628 629 630 631 632 633 634 635

    if ($alerts && $original != $filename) {
      drupal_set_message(t('For security reasons, your upload has been renamed to %filename.', array('%filename' => $filename)));
    }
  }

  return $filename;
}

/**
 * Undo the effect of upload_munge_filename().
 *
636 637 638 639
 * @param $filename
 *   String with the filename to be unmunged.
 * @return
 *   An unmunged filename string.
640 641 642 643 644
 */
function file_unmunge_filename($filename) {
  return str_replace('_.', '.', $filename);
}

645
/**
646 647 648 649
 * Create a full file path from a directory and filename.
 *
 * If a file with the specified name already exists, an alternative will be
 * used.
650
 *
651 652 653 654
 * @param $basename
 *   String filename
 * @param $directory
 *   String directory
655
 * @return
656 657
 *   File path consisting of $directory and a unique filename based off
 *   of $basename.
658
 */
Dries's avatar
 
Dries committed
659
function file_create_filename($basename, $directory) {
660
  $destination = $directory . '/' . $basename;
Dries's avatar
 
Dries committed
661

662
  if (file_exists($destination)) {
Dries's avatar
 
Dries committed
663
    // Destination file already exists, generate an alternative.
664 665
    $pos = strrpos($basename, '.');
    if ($pos !== FALSE) {
Dries's avatar
 
Dries committed
666 667 668 669 670
      $name = substr($basename, 0, $pos);
      $ext = substr($basename, $pos);
    }
    else {
      $name = $basename;
671
      $ext = '';
Dries's avatar
 
Dries committed
672 673 674 675
    }

    $counter = 0;
    do {
676 677
      $destination = $directory . '/' . $name . '_' . $counter++ . $ext;
    } while (file_exists($destination));
Dries's avatar
 
Dries committed
678 679
  }

680
  return $destination;
Dries's avatar
 
Dries committed
681 682
}

683
/**
684 685 686 687 688 689 690 691 692 693 694 695 696 697 698
 * Delete a file and its database record.
 *
 * If the $force parameter is not TRUE hook_file_references() will be called
 * to determine if the file is being used by any modules. If the file is being
 * used is the delete will be canceled.
 *
 * @param $file
 *   A file object.
 * @param $force
 *   Boolean indicating that the file should be deleted even if
 *   hook_file_references() reports that the file is in use.
 * @return mixed
 *   TRUE for success, FALSE in the event of an error, or an array if the file
 *   is being used by another module. The array keys are the module's name and
 *   the values are the number of references.
699
 *
700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731
 * @see file_unmanaged_delete()
 * @see hook_file_references()
 * @see hook_file_delete()
 */
function file_delete($file, $force = FALSE) {
  $file = (object)$file;

  // If any module returns a value from the reference hook, the file will not
  // be deleted from Drupal, but file_delete will return a populated array that
  // tests as TRUE.
  if (!$force && ($references = module_invoke_all('file_references', $file))) {
    return $references;
  }

  // Let other modules clean up any references to the deleted file.
  module_invoke_all('file_delete', $file);

  // Make sure the file is deleted before removing its row from the
  // database, so UIs can still find the file in the database.
  if (file_unmanaged_delete($file->filepath)) {
    db_delete('files')->condition('fid', $file->fid)->execute();
    return TRUE;
  }
  return FALSE;
}

/**
 * Delete a file without calling any hooks or making any changes to the
 * database.
 *
 * This function should be used when the file to be deleted does not have an
 * entry recorded in the files table.
732
 *
733 734 735 736 737
 * @param $path
 *   A string containing a file path.
 * @return
 *   TRUE for success or path does not exist, or FALSE in the event of an
 *   error.
738
 *
739
 * @see file_delete()
740
 */
741
function file_unmanaged_delete($path) {
742
  if (is_dir($path)) {
743
    watchdog('file', '%path is a directory and cannot be removed using file_unmanaged_delete().', array('%path' => $path), WATCHDOG_ERROR);
744 745
    return FALSE;
  }
746
  if (is_file($path)) {
Dries's avatar
 
Dries committed
747
    return unlink($path);
748
  }
749 750 751
  // Return TRUE for non-existant file, but log that nothing was actually
  // deleted, as the current state is the indended result.
  if (!file_exists($path)) {
752
    watchdog('file', 'The file %path was not deleted, because it does not exist.', array('%path' => $path), WATCHDOG_NOTICE);
753 754 755 756
    return TRUE;
  }
  // Catch all for everything else: sockets, symbolic links, etc.
  return FALSE;
Dries's avatar
 
Dries committed
757 758
}

759
/**
760
 * Determine total disk space used by a single user or the whole filesystem.
761
 *
762
 * @param $uid
763 764 765 766 767 768 769
 *   Optional. A user id, specifying NULL returns the total space used by all
 *   non-temporary files.
 * @param $status
 *   Optional. File Status to return. Combine with a bitwise OR(|) to return
 *   multiple statuses. The default status is FILE_STATUS_PERMANENT.
 * @return
 *   An integer containing the number of bytes used.
770
 */
771 772
function file_space_used($uid = NULL, $status = FILE_STATUS_PERMANENT) {
  if (!is_null($uid)) {
773
    return db_query('SELECT SUM(filesize) FROM {files} WHERE uid = :uid AND status & :status', array(':uid' => $uid, ':status' => $status))->fetchField();
774
  }
775
  return db_query('SELECT SUM(filesize) FROM {files} WHERE status & :status', array(':status' => $status))->fetchField();
776 777
}

Dries's avatar
 
Dries committed
778
/**
779
 * Saves a file upload to a new location.
Dries's avatar
 
Dries committed
780
 *
781 782
 * The file will be added to the files table as a temporary file. Temporary
 * files are periodically cleaned. To make the file permanent file call
783
 * file_set_status() to change its status.
784 785 786 787 788
 *
 * @param $source
 *   A string specifying the name of the upload field to save.
 * @param $validators
 *   An optional, associative array of callback functions used to validate the
789
 *   file. See @file_validate for a full discussion of the array format.
790
 * @param $destination
791 792
 *   A string containing the directory $source should be copied to. If this is
 *   not provided or is not writable, the temporary directory will be used.
793 794 795 796 797
 * @param $replace
 *   A boolean indicating whether an existing file of the same name in the
 *   destination directory should overwritten. A false value will generate a
 *   new, unique filename in the destination directory.
 * @return
798 799
 *   An object containing the file information, or FALSE in the event of an
 *   error.
Dries's avatar
 
Dries committed
800
 */
801
function file_save_upload($source, $validators = array(), $destination = FALSE, $replace = FILE_EXISTS_RENAME) {
802 803 804 805 806 807 808 809 810
  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];
  }

811 812 813 814
  // Add in our check of the the file name length.
  $validators['file_validate_name_length'] = array();


815 816
  // If a file was uploaded, process it.
  if (isset($_FILES['files']) && $_FILES['files']['name'][$source] && is_uploaded_file($_FILES['files']['tmp_name'][$source])) {
817 818
    // Check for file upload errors and return FALSE if a lower level system
    // error occurred.
819 820 821 822 823 824 825 826
    switch ($_FILES['files']['error'][$source]) {
      // @see http://php.net/manual/en/features.file-upload.errors.php
      case UPLOAD_ERR_OK:
        break;

      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' => $source, '%maxsize' => format_size(file_upload_max_size()))), 'error');
827
        return FALSE;
828 829 830 831

      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' => $source)), 'error');
832
        return FALSE;
833 834 835 836

        // Unknown error
      default:
        drupal_set_message(t('The file %file could not be saved. An unknown error has occurred.', array('%file' => $source)), 'error');
837
        return FALSE;
838 839 840 841 842 843
    }

    // Build the list of non-munged extensions.
    // @todo: this should not be here. we need to figure out the right place.
    $extensions = '';
    foreach ($user->roles as $rid => $name) {
844
      $extensions .= ' ' . variable_get("upload_extensions_$rid",
845 846
      variable_get('upload_extensions_default', 'jpg jpeg gif png txt html doc xls pdf ppt pps odt ods odp'));
    }
847

848 849
    // Begin building file object.
    $file = new stdClass();
850 851
    $file->uid      = $user->uid;
    $file->status   = FILE_STATUS_TEMPORARY;
852 853
    $file->filename = file_munge_filename(trim(basename($_FILES['files']['name'][$source]), '.'), $extensions);
    $file->filepath = $_FILES['files']['tmp_name'][$source];
854
    $file->filemime = file_get_mimetype($file->filename);
855
    $file->filesize = $_FILES['files']['size'][$source];
856 857 858 859 860 861 862 863

    // Rename potentially executable files, to help prevent exploits.
    if (preg_match('/\.(php|pl|py|cgi|asp|js)$/i', $file->filename) && (substr($file->filename, -4) != '.txt')) {
      $file->filemime = 'text/plain';
      $file->filepath .= '.txt';
      $file->filename .= '.txt';
    }

864 865
    // If the destination is not provided, or is not writable, then use the
    // temporary directory.
866 867
    if (empty($destination) || file_check_path($destination) === FALSE) {
      $destination = file_directory_temp();
868
    }
869

870
    $file->source = $source;
871
    $file->destination = file_destination(file_create_path($destination . '/' . $file->filename), $replace);
872

873 874
    // Call the validation functions specified by this function's caller.
    $errors = file_validate($file, $validators);
Dries's avatar
 
Dries committed
875

876
    // Check for errors.
877
    if (!empty($errors)) {
878
      $message = t('The specified file %name could not be uploaded.', array('%name' => $file->filename));
879
      if (count($errors) > 1) {
880
        $message .= theme('item_list', $errors);
881 882
      }
      else {
883
        $message .= ' ' . array_pop($errors);
Dries's avatar
 
Dries committed
884
      }
885
      form_set_error($source, $message);
886
      return FALSE;
Dries's avatar
 
Dries committed
887
    }
888

889 890 891
    // Move uploaded files from PHP's upload_tmp_dir to Drupal's temporary
    // directory. This overcomes open_basedir restrictions for future file
    // operations.
892 893 894
    $file->filepath = $file->destination;
    if (!move_uploaded_file($_FILES['files']['tmp_name'][$source], $file->filepath)) {
      form_set_error($source, t('File upload error. Could not move uploaded file.'));
895
      watchdog('file', 'Upload error. Could not move uploaded file %file to destination %destination.', array('%file' => $file->filename, '%destination' => $file->filepath));
896
      return FALSE;
897 898 899
    }

    // If we made it this far it's safe to record this file in the database.
900 901 902 903 904
    if ($file = file_save($file)) {
      // Add file to the cache.
      $upload_cache[$source] = $file;
      return $file;
    }
Dries's avatar
 
Dries committed
905
  }
906
  return FALSE;
Dries's avatar
 
Dries committed
907 908
}

909 910 911 912

/**
 * Check that a file meets the criteria specified by the validators.
 *
913 914 915
 * After executing the validator callbacks specified hook_file_validate() will
 * also be called to allow other modules to report errors about the file.
 *
916 917 918 919 920 921 922 923 924 925 926
 * @param $file
 *   A Drupal file object.
 * @param $validators
 *   An optional, 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 user and file objects. 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.
 * @return
 *   An array contaning validation error messages.
927
 *
928
 * @see hook_file_validate()
929 930 931 932 933 934 935 936 937
 */
function file_validate(&$file, $validators = array()) {
  // Call the validation functions specified by this function's caller.
  $errors = array();
  foreach ($validators as $function => $args) {
    array_unshift($args, $file);
    $errors = array_merge($errors, call_user_func_array($function, $args));
  }

938 939
  // Let other modules perform validation on the new file.
  return array_merge($errors, module_invoke_all('file_validate', $file));
940 941
}

942 943 944 945 946 947 948 949 950 951 952
/**
 * Check for files with names longer than we can store in the database.
 *
 * @param $file
 *   A Drupal file object.
 * @return
 *   An array. If the file name is too long, it will contain an error message.
 */
function file_validate_name_length($file) {
  $errors = array();

953 954 955
  if (empty($file->filename)) {
    $errors[] = t("The file's name is empty. Please give a name to the file.");
  }
956
  if (strlen($file->filename) > 255) {
957
    $errors[] = t("The file's name exceeds the 255 characters limit. Please rename the file and try again.");
958 959 960 961 962
  }
  return $errors;
}

/**
963
 * Check that the filename ends with an allowed extension.
964 965 966 967 968 969
 *
 * @param $file
 *   A Drupal file object.
 * @param $extensions
 *   A string with a space separated
 * @return
970 971
 *   An array. If the file extension is not allowed, it will contain an error
 *   message.
972 973
 *
 * @see hook_file_validate()
974 975 976 977 978 979
 */
function file_validate_extensions($file, $extensions) {
  global $user;

  $errors = array();

980 981 982
  $regex = '/\.(' . preg_replace('/ +/', '|', preg_quote($extensions)) . ')$/i';
  if (!preg_match($regex, $file->filename)) {
    $errors[] = t('Only files with the following extensions are allowed: %files-allowed.', array('%files-allowed' => $extensions));
983 984 985 986 987
  }
  return $errors;
}

/**
988 989 990
 * Check that the file's size is below certain limits.
 *
 * This check is not enforced for the user #1.
991 992 993 994 995 996
 *
 * @param $file
 *   A Drupal file object.
 * @param $file_limit
 *   An integer specifying the maximum file size in bytes. Zero indicates that
 *   no limit should be enforced.
997
 * @param $user_limit
998 999
 *   An integer specifying the maximum number of bytes the user is allowed.
 *   Zero indicates that no limit should be enforced.
1000
 * @return
1001 1002
 *   An array. If the file size exceeds limits, it will contain an error
 *   message.
1003 1004
 *
 * @see hook_file_validate()
1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016
 */
function file_validate_size($file, $file_limit = 0, $user_limit = 0) {
  global $user;

  $errors = array();

  // Bypass validation for uid  = 1.
  if ($user->uid != 1) {
    if ($file_limit && $file->filesize > $file_limit) {
      $errors[] = t('The file is %filesize exceeding the maximum file size of %maxsize.', array('%filesize' => format_size($file->filesize), '%maxsize' => format_size($file_limit)));
    }

1017
    if ($user_limit && (file_space_used($user->uid) + $file->filesize) > $user_limit) {
1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030
      $errors[] = t('The file is %filesize which would exceed your disk quota of %quota.', array('%filesize' => format_size($file->filesize), '%quota' => format_size($user_limit)));
    }
  }
  return $errors;
}

/**
 * Check that the file is recognized by image_get_info() as an image.
 *
 * @param $file
 *   A Drupal file object.
 * @return
 *   An array. If the file is not an image, it will contain an error message.
1031 1032
 *
 * @see hook_file_validate()
1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046
 */
function file_validate_is_image(&$file) {
  $errors = array();

  $info = image_get_info($file->filepath);
  if (!$info || empty($info['extension'])) {
    $errors[] = t('Only JPEG, PNG and GIF images are allowed.');
  }

  return $errors;
}

/**
 * If the file is an image verify that its dimensions are within the specified
1047 1048 1049 1050
 * maximum and minimum dimensions.
 *
 * Non-image files will be ignored. If a image toolkit is available the image
 * will be scalled to fit within the desired maximum dimensions.
1051 1052
 *
 * @param $file
1053 1054
 *   A Drupal file object. This function may resize the file affecting its
 *   size.
1055 1056 1057 1058 1059 1060
 * @param $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 $minimum_dimensions
1061 1062
 *   An optional string in the form WIDTHxHEIGHT. This will check that the
 *   image meets a minimum size. A value of 0 indicates no restriction.
1063 1064 1065
 * @return
 *   An array. If the file is an image and did not meet the requirements, it
 *   will contain an error message.
1066 1067
 *
 * @see hook_file_validate()
1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089