file.inc 62.9 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
 * 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
151 152 153
 *   A bitmask to indicate if the directory should be created if it does
 *   not exist (FILE_CREATE_DIRECTORY) or made writable if it is read-only
 *   (FILE_MODIFY_PERMISSIONS).
154 155 156 157 158 159 160
 * @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
161
 */
162
function file_check_directory(&$directory, $mode = 0, $form_item = NULL) {
Dries's avatar
 
Dries committed
163
  $directory = rtrim($directory, '/\\');
Dries's avatar
 
Dries committed
164 165 166

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

  // Check to see if the directory is writable.
  if (!is_writable($directory)) {
181 182 183 184 185 186 187
    // 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);
      }
188
      return FALSE;
Dries's avatar
 
Dries committed
189 190 191
    }
  }

192
  if ((file_directory_path() == $directory || file_directory_temp() == $directory) && !is_file("$directory/.htaccess")) {
193
    $htaccess_lines = "SetHandler Drupal_Security_Do_Not_Remove_See_SA_2006_006\nOptions None\nOptions +FollowSymLinks";
Gerhard Killesreiter's avatar
Gerhard Killesreiter committed
194
    if (($fp = fopen("$directory/.htaccess", 'w')) && fputs($fp, $htaccess_lines)) {
195
      fclose($fp);
196
      chmod($directory . '/.htaccess', 0664);
197 198
    }
    else {
199
      $variables = array('%directory' => $directory, '!htaccess' => '<br />' . nl2br(check_plain($htaccess_lines)));
200 201
      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);
202 203 204
    }
  }

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

/**
209
 * Checks path to see if it is a directory, or a directory/file.
Dries's avatar
 
Dries committed
210
 *
211 212 213 214 215
 * @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
216 217 218 219 220 221 222 223 224 225 226 227 228 229
 */
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;
  }

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

/**
234 235 236 237 238
 * 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
239 240
 *
 * @code
241
 *   // Returns FALSE:
Dries's avatar
 
Dries committed
242 243 244
 *   file_check_location('/www/example.com/files/../../../etc/passwd', '/www/example.com/files');
 * @endcode
 *
245 246 247 248 249 250 251
 * @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
252
 */
253
function file_check_location($source, $directory = '') {
254 255 256 257 258
  $check = realpath($source);
  if ($check) {
    $source = $check;
  }
  else {
259
    // This file does not yet exist.
260
    $source = realpath(dirname($source)) . '/' . basename($source);
261
  }
262
  $directory = realpath($directory);
Dries's avatar
 
Dries committed
263
  if ($directory && strpos($source, $directory) !== 0) {
264
    return FALSE;
Dries's avatar
 
Dries committed
265 266 267 268 269
  }
  return $source;
}

/**
270
 * Load file objects from the database.
271
 *
272 273 274 275 276
 * @param $fids
 *   An array of file IDs.
 * @param $conditions
 *   An array of conditions to match against the {files} table. These
 *   should be supplied in the form array('field_name' => 'field_value').
277
 * @return
278
 *  An array of file objects, indexed by fid.
279 280
 *
 * @see hook_file_load()
281
 * @see file_load()
282
 */
283 284
function file_load_multiple($fids = array(), $conditions = array()) {
  $query = db_select('files', 'f')->fields('f');
285

286 287 288
  // If the $fids array is populated, add those to the query.
  if ($fids) {
    $query->condition('f.fid', $fids, 'IN');
289 290
  }

291 292 293 294
  // If the conditions array is populated, add those to the query.
  if ($conditions) {
    foreach ($conditions as $field => $value) {
      $query->condition('f.' . $field, $value);
295 296
    }
  }
297
  $files = $query->execute()->fetchAllAssoc('fid');
298

299 300 301 302 303 304 305
  // Invoke hook_file_load() on the terms loaded from the database
  // and add them to the static cache.
  if (!empty($files)) {
    foreach (module_implements('file_load') as $module) {
      $function = $module . '_file_load';
      $function($files);
    }
306
  }
307 308
  return $files;
}
309

310 311 312 313 314 315 316 317 318 319 320 321 322 323
/**
 * Load a file object from the database.
 *
 * @param $fid
 *  A file ID.
 * @return
 *   A file object.
 *
 * @see hook_file_load()
 * @see file_load_multiple()
 */
function file_load($fid) {
  $files = file_load_multiple(array($fid), array());
  return reset($files);
324 325 326 327 328 329 330 331 332 333 334 335
}

/**
 * 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.
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 381 382 383 384 385 386
 * @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.
387
 *
388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410
 * @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
411
 *
412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429
 * 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.
430
 *   - FILE_EXISTS_ERROR - Do nothing and return FALSE.
431 432
 * @return
 *   The path to the new file, or FALSE in the event of an error.
433
 *
434
 * @see file_copy()
Dries's avatar
 
Dries committed
435
 */
436
function file_unmanaged_copy($source, $destination = NULL, $replace = FILE_EXISTS_RENAME) {
437 438 439 440 441
  $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
442

443 444
  $destination = file_create_path($destination);
  $directory = $destination;
Dries's avatar
 
Dries committed
445 446 447
  $basename = file_check_path($directory);

  // Make sure we at least have a valid directory.
448
  if ($basename === FALSE) {
449
    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');
450
    return FALSE;
Dries's avatar
 
Dries committed
451 452
  }

453 454
  // If the destination file is not specified then use the filename of the
  // source file.
Dries's avatar
 
Dries committed
455
  $basename = $basename ? $basename : basename($source);
456
  $destination = file_destination($directory . '/' . $basename, $replace);
457

458 459 460
  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
461
  }
462 463 464 465 466 467
  // 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
468
  }
469 470 471
  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
472
  }
Dries's avatar
 
Dries committed
473

474 475 476 477 478 479 480
  // 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
481 482
}

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

506 507 508 509 510 511 512
      case FILE_EXISTS_RENAME:
        $basename = basename($destination);
        $directory = dirname($destination);
        $destination = file_create_filename($basename, $directory);
        break;

      case FILE_EXISTS_ERROR:
513
        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');
514 515 516 517 518 519
        return FALSE;
    }
  }
  return $destination;
}

Dries's avatar
 
Dries committed
520
/**
521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543
 * 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.
544
 *
545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567
 * @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
568
 *
569 570 571 572 573 574 575 576 577 578
 * @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.
579
 *   - FILE_EXISTS_ERROR - Do nothing and return FALSE.
580 581
 * @return
 *   The filepath of the moved file, or FALSE in the event of an error.
582
 *
583
 * @see file_move()
Dries's avatar
 
Dries committed
584
 */
585 586 587
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) {
588
    return FALSE;
Dries's avatar
 
Dries committed
589
  }
590
  return $filepath;
Dries's avatar
 
Dries committed
591 592
}

593
/**
594 595 596 597 598 599 600 601 602 603 604 605
 * 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.
606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623
 */
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) {
624
      $new_filename .= '.' . $filename_part;
625 626 627 628
      if (!in_array($filename_part, $whitelist) && preg_match("/^[a-zA-Z]{2,5}\d?$/", $filename_part)) {
        $new_filename .= '_';
      }
    }
629
    $filename = $new_filename . '.' . $final_extension;
630 631 632 633 634 635 636 637 638 639 640 641

    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().
 *
642 643 644 645
 * @param $filename
 *   String with the filename to be unmunged.
 * @return
 *   An unmunged filename string.
646 647 648 649 650
 */
function file_unmunge_filename($filename) {
  return str_replace('_.', '.', $filename);
}

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

668
  if (file_exists($destination)) {
Dries's avatar
 
Dries committed
669
    // Destination file already exists, generate an alternative.
670 671
    $pos = strrpos($basename, '.');
    if ($pos !== FALSE) {
Dries's avatar
 
Dries committed
672 673 674 675 676
      $name = substr($basename, 0, $pos);
      $ext = substr($basename, $pos);
    }
    else {
      $name = $basename;
677
      $ext = '';
Dries's avatar
 
Dries committed
678 679 680 681
    }

    $counter = 0;
    do {
682 683
      $destination = $directory . '/' . $name . '_' . $counter++ . $ext;
    } while (file_exists($destination));
Dries's avatar
 
Dries committed
684 685
  }

686
  return $destination;
Dries's avatar
 
Dries committed
687 688
}

689
/**
690 691 692 693 694 695 696 697 698 699 700 701 702 703 704
 * 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.
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 732 733 734 735 736 737
 * @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.
738
 *
739 740 741 742 743
 * @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.
744
 *
745
 * @see file_delete()
746
 */
747
function file_unmanaged_delete($path) {
748
  if (is_dir($path)) {
749
    watchdog('file', '%path is a directory and cannot be removed using file_unmanaged_delete().', array('%path' => $path), WATCHDOG_ERROR);
750 751
    return FALSE;
  }
752
  if (is_file($path)) {
Dries's avatar
 
Dries committed
753
    return unlink($path);
754
  }
755
  // Return TRUE for non-existent file, but log that nothing was actually
756 757
  // deleted, as the current state is the indended result.
  if (!file_exists($path)) {
758
    watchdog('file', 'The file %path was not deleted, because it does not exist.', array('%path' => $path), WATCHDOG_NOTICE);
759 760 761 762
    return TRUE;
  }
  // Catch all for everything else: sockets, symbolic links, etc.
  return FALSE;
Dries's avatar
 
Dries committed
763 764
}

765
/**
766
 * Determine total disk space used by a single user or the whole filesystem.
767
 *
768
 * @param $uid
769 770 771 772 773 774 775
 *   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.
776
 */
777 778
function file_space_used($uid = NULL, $status = FILE_STATUS_PERMANENT) {
  if (!is_null($uid)) {
779
    return db_query('SELECT SUM(filesize) FROM {files} WHERE uid = :uid AND status = :status', array(':uid' => $uid, ':status' => $status))->fetchField();
780
  }
781
  return db_query('SELECT SUM(filesize) FROM {files} WHERE status = :status', array(':status' => $status))->fetchField();
782 783
}

Dries's avatar
 
Dries committed
784
/**
785
 * Saves a file upload to a new location.
Dries's avatar
 
Dries committed
786
 *
787
 * The file will be added to the files table as a temporary file. Temporary
788 789
 * files are periodically cleaned. To make the file a permanent file call
 * assign the status and use file_save() to save it.
790 791 792 793 794
 *
 * @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
795
 *   file. See @file_validate for a full discussion of the array format.
796
 * @param $destination
797 798
 *   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.
799 800 801 802 803
 * @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
804 805
 *   An object containing the file information, or FALSE in the event of an
 *   error.
Dries's avatar
 
Dries committed
806
 */
807
function file_save_upload($source, $validators = array(), $destination = FALSE, $replace = FILE_EXISTS_RENAME) {
808 809 810 811 812 813 814 815 816
  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];
  }

817 818 819 820
  // Add in our check of the the file name length.
  $validators['file_validate_name_length'] = array();


821
  // If a file was uploaded, process it.
822
  if (isset($_FILES['files']['name'][$source]) && is_uploaded_file($_FILES['files']['tmp_name'][$source])) {
823 824
    // Check for file upload errors and return FALSE if a lower level system
    // error occurred.
825 826 827 828 829 830 831 832
    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');
833
        return FALSE;
834 835 836 837

      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');
838
        return FALSE;
839 840 841 842

        // Unknown error
      default:
        drupal_set_message(t('The file %file could not be saved. An unknown error has occurred.', array('%file' => $source)), 'error');
843
        return FALSE;
844 845 846 847 848 849
    }

    // 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) {
850
      $extensions .= ' ' . variable_get("upload_extensions_$rid",
851 852
      variable_get('upload_extensions_default', 'jpg jpeg gif png txt html doc xls pdf ppt pps odt ods odp'));
    }
853

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

    // 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';
    }

870 871
    // If the destination is not provided, or is not writable, then use the
    // temporary directory.
872 873
    if (empty($destination) || file_check_path($destination) === FALSE) {
      $destination = file_directory_temp();
874
    }
875

876
    $file->source = $source;
877
    $file->destination = file_destination(file_create_path($destination . '/' . $file->filename), $replace);
878

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

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

895 896 897
    // Move uploaded files from PHP's upload_tmp_dir to Drupal's temporary
    // directory. This overcomes open_basedir restrictions for future file
    // operations.
898 899 900
    $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.'));
901
      watchdog('file', 'Upload error. Could not move uploaded file %file to destination %destination.', array('%file' => $file->filename, '%destination' => $file->filepath));
902
      return FALSE;
903 904 905
    }

    // If we made it this far it's safe to record this file in the database.
906 907 908 909 910
    if ($file = file_save($file)) {
      // Add file to the cache.
      $upload_cache[$source] = $file;
      return $file;
    }
Dries's avatar
 
Dries committed
911
  }
912
  return FALSE;
Dries's avatar
 
Dries committed
913 914
}

915 916 917 918

/**
 * Check that a file meets the criteria specified by the validators.
 *
919 920 921
 * After executing the validator callbacks specified hook_file_validate() will
 * also be called to allow other modules to report errors about the file.
 *
922 923 924 925 926 927 928 929 930 931 932
 * @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.
933
 *
934
 * @see hook_file_validate()
935 936 937 938 939 940 941 942 943
 */
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));
  }

944 945
  // Let other modules perform validation on the new file.
  return array_merge($errors, module_invoke_all('file_validate', $file));
946 947
}

948 949 950 951 952 953 954 955 956 957 958
/**
 * 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();

959 960 961
  if (empty($file->filename)) {
    $errors[] = t("The file's name is empty. Please give a name to the file.");
  }
962
  if (strlen($file->filename) > 255) {
963
    $errors[] = t("The file's name exceeds the 255 characters limit. Please rename the file and try again.");
964 965 966 967 968
  }
  return $errors;
}

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

  $errors = array();

986 987 988
  $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));
989 990 991 992 993
  }
  return $errors;
}

/**
994 995 996
 * Check that the file's size is below certain limits.
 *
 * This check is not enforced for the user #1.
997 998 999 1000 1001 1002
 *
 * @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.
1003
 * @param $user_limit
1004 1005
 *   An integer specifying the maximum number of bytes the user is allowed.
 *   Zero indicates that no limit should be enforced.
1006
 * @return
1007 1008
 *   An array. If the file size exceeds limits, it will contain an error
 *   message.
1009 1010
 *
 * @see hook_file_validate()
1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022
 */
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)));
    }

1023
    if ($user_limit && (file_space_used($user->uid) + $file->filesize) > $user_limit) {
1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034