file.inc 89.1 KB
Newer Older
Dries's avatar
 
Dries committed
1
<?php
Kjartan's avatar
Kjartan committed
2

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

8 9 10
use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
use Symfony\Component\HttpFoundation\StreamedResponse;
webchick's avatar
webchick committed
11 12
use Drupal\Core\StreamWrapper\LocalStream;

13
/**
webchick's avatar
webchick committed
14
 * Stream wrapper bit flags that are the basis for composite types.
15
 *
webchick's avatar
webchick committed
16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80
 * Note that 0x0002 is skipped, because it was the value of a constant that has
 * since been removed.
 */

/**
 * Stream wrapper bit flag -- a filter that matches all wrappers.
 */
const STREAM_WRAPPERS_ALL = 0x0000;

/**
 * Stream wrapper bit flag -- refers to a local file system location.
 */
const STREAM_WRAPPERS_LOCAL = 0x0001;

/**
 * Stream wrapper bit flag -- wrapper is readable (almost always true).
 */
const STREAM_WRAPPERS_READ = 0x0004;

/**
 * Stream wrapper bit flag -- wrapper is writeable.
 */
const STREAM_WRAPPERS_WRITE = 0x0008;

/**
 * Stream wrapper bit flag -- exposed in the UI and potentially web accessible.
 */
const STREAM_WRAPPERS_VISIBLE = 0x0010;

/**
 * Composite stream wrapper bit flags that are usually used as the types.
 */

/**
 * Stream wrapper type flag -- not visible in the UI or accessible via web,
 * but readable and writable. E.g. the temporary directory for uploads.
 */
define('STREAM_WRAPPERS_HIDDEN', STREAM_WRAPPERS_READ | STREAM_WRAPPERS_WRITE);

/**
 * Stream wrapper type flag -- hidden, readable and writeable using local files.
 */
define('STREAM_WRAPPERS_LOCAL_HIDDEN', STREAM_WRAPPERS_LOCAL | STREAM_WRAPPERS_HIDDEN);

/**
 * Stream wrapper type flag -- visible, readable and writeable.
 */
define('STREAM_WRAPPERS_WRITE_VISIBLE', STREAM_WRAPPERS_READ | STREAM_WRAPPERS_WRITE | STREAM_WRAPPERS_VISIBLE);

/**
 * Stream wrapper type flag -- visible and read-only.
 */
define('STREAM_WRAPPERS_READ_VISIBLE', STREAM_WRAPPERS_READ | STREAM_WRAPPERS_VISIBLE);

/**
 * Stream wrapper type flag -- the default when 'type' is omitted from
 * hook_stream_wrappers(). This does not include STREAM_WRAPPERS_LOCAL,
 * because PHP grants a greater trust level to local files (for example, they
 * can be used in an "include" statement, regardless of the "allow_url_include"
 * setting), so stream wrappers need to explicitly opt-in to this.
 */
define('STREAM_WRAPPERS_NORMAL', STREAM_WRAPPERS_WRITE_VISIBLE);

/**
 * Stream wrapper type flag -- visible, readable and writeable using local files.
81
 */
webchick's avatar
webchick committed
82
define('STREAM_WRAPPERS_LOCAL_NORMAL', STREAM_WRAPPERS_LOCAL | STREAM_WRAPPERS_NORMAL);
83

Kjartan's avatar
Kjartan committed
84
/**
Kjartan's avatar
Kjartan committed
85
 * @defgroup file File interface
Kjartan's avatar
Kjartan committed
86
 * @{
Dries's avatar
 
Dries committed
87
 * Common file handling functions.
88 89
 *
 * Fields on the file object:
90 91 92
 * - fid: File ID
 * - uid: The {users}.uid of the user who is associated with the file.
 * - filename: Name of the file with no path components. This may differ from
93 94
 *   the basename of the filepath if the file is renamed to avoid overwriting
 *   an existing file.
95 96 97 98
 * - uri: URI of the file.
 * - 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 first 8
99
 *   bits are reserved for Drupal core. The least significant bit indicates
100 101
 *   temporary (0) or permanent (1). Temporary files older than
 *   DRUPAL_MAXIMUM_TEMP_FILE_AGE will be removed during cron runs.
102
 * - timestamp: UNIX timestamp for the date the file was added to the database.
Dries's avatar
 
Dries committed
103 104
 */

105
/**
106
 * Flag used by file_prepare_directory() -- create directory if not present.
107
 */
108
const FILE_CREATE_DIRECTORY = 1;
109 110

/**
111
 * Flag used by file_prepare_directory() -- file permissions may be changed.
112
 */
113
const FILE_MODIFY_PERMISSIONS = 2;
114 115

/**
116
 * Flag for dealing with existing files: Appends number until name is unique.
117
 */
118
const FILE_EXISTS_RENAME = 0;
119 120 121 122

/**
 * Flag for dealing with existing files: Replace the existing file.
 */
123
const FILE_EXISTS_REPLACE = 1;
124 125 126 127

/**
 * Flag for dealing with existing files: Do nothing and return FALSE.
 */
128
const FILE_EXISTS_ERROR = 2;
Dries's avatar
 
Dries committed
129

130
/**
131 132 133 134 135
 * Indicates that the file is permanent and should not be deleted.
 *
 * Temporary files older than DRUPAL_MAXIMUM_TEMP_FILE_AGE will be removed
 * during cron runs, but permanent files will not be removed during the file
 * garbage collection process.
136
 */
137
const FILE_STATUS_PERMANENT = 1;
138

139
/**
140
 * Provides Drupal stream wrapper registry.
141 142 143 144 145 146 147 148 149 150 151 152 153 154
 *
 * A stream wrapper is an abstraction of a file system that allows Drupal to
 * use the same set of methods to access both local files and remote resources.
 *
 * Provide a facility for managing and querying user-defined stream wrappers
 * in PHP. PHP's internal stream_get_wrappers() doesn't return the class
 * registered to handle a stream, which we need to be able to find the handler
 * for class instantiation.
 *
 * If a module registers a scheme that is already registered with PHP, the
 * existing scheme will be unregistered and replaced with the specified class.
 *
 * A stream is referenced as "scheme://target".
 *
155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171
 * The optional $filter parameter can be used to retrieve only the stream
 * wrappers that are appropriate for particular usage. For example, this returns
 * only stream wrappers that use local file storage:
 * @code
 *   $local_stream_wrappers = file_get_stream_wrappers(STEAM_WRAPPERS_LOCAL);
 * @endcode
 *
 * The $filter parameter can only filter to types containing a particular flag.
 * In some cases, you may want to filter to types that do not contain a
 * particular flag. For example, you may want to retrieve all stream wrappers
 * that are not writable, or all stream wrappers that are not local. PHP's
 * array_diff_key() function can be used to help with this. For example, this
 * returns only stream wrappers that do not use local file storage:
 * @code
 *   $remote_stream_wrappers = array_diff_key(file_get_stream_wrappers(STREAM_WRAPPERS_ALL), file_get_stream_wrappers(STEAM_WRAPPERS_LOCAL));
 * @endcode
 *
172
 * @param $filter
173 174 175 176 177 178
 *   (Optional) Filters out all types except those with an on bit for each on
 *   bit in $filter. For example, if $filter is STREAM_WRAPPERS_WRITE_VISIBLE,
 *   which is equal to (STREAM_WRAPPERS_READ | STREAM_WRAPPERS_WRITE |
 *   STREAM_WRAPPERS_VISIBLE), then only stream wrappers with all three of these
 *   bits set are returned. Defaults to STREAM_WRAPPERS_ALL, which returns all
 *   registered stream wrappers.
179
 *
180
 * @return
181 182 183 184 185
 *   An array keyed by scheme, with values containing an array of information
 *   about the stream wrapper, as returned by hook_stream_wrappers(). If $filter
 *   is omitted or set to STREAM_WRAPPERS_ALL, the entire Drupal stream wrapper
 *   registry is returned. Otherwise only the stream wrappers whose 'type'
 *   bitmask has an on bit for each bit specified in $filter are returned.
186
 *
187 188 189
 * @see hook_stream_wrappers()
 * @see hook_stream_wrappers_alter()
 */
190 191
function file_get_stream_wrappers($filter = STREAM_WRAPPERS_ALL) {
  $wrappers_storage = &drupal_static(__FUNCTION__);
192

193
  if (!isset($wrappers_storage)) {
194
    $wrappers = module_invoke_all('stream_wrappers');
195 196 197 198
    foreach ($wrappers as $scheme => $info) {
      // Add defaults.
      $wrappers[$scheme] += array('type' => STREAM_WRAPPERS_NORMAL);
    }
199 200 201 202
    drupal_alter('stream_wrappers', $wrappers);
    $existing = stream_get_wrappers();
    foreach ($wrappers as $scheme => $info) {
      // We only register classes that implement our interface.
webchick's avatar
webchick committed
203
      if (in_array('Drupal\Core\StreamWrapper\StreamWrapperInterface', class_implements($info['class']), TRUE)) {
204 205 206 207 208 209 210 211
        // Record whether we are overriding an existing scheme.
        if (in_array($scheme, $existing, TRUE)) {
          $wrappers[$scheme]['override'] = TRUE;
          stream_wrapper_unregister($scheme);
        }
        else {
          $wrappers[$scheme]['override'] = FALSE;
        }
212 213
        if (($info['type'] & STREAM_WRAPPERS_LOCAL) == STREAM_WRAPPERS_LOCAL) {
          stream_wrapper_register($scheme, $info['class']);
214 215
        }
        else {
216
          stream_wrapper_register($scheme, $info['class'], STREAM_IS_URL);
217
        }
218
      }
219 220 221 222 223
      // Pre-populate the static cache with the filters most typically used.
      $wrappers_storage[STREAM_WRAPPERS_ALL][$scheme] = $wrappers[$scheme];
      if (($info['type'] & STREAM_WRAPPERS_WRITE_VISIBLE) == STREAM_WRAPPERS_WRITE_VISIBLE) {
        $wrappers_storage[STREAM_WRAPPERS_WRITE_VISIBLE][$scheme] = $wrappers[$scheme];
      }
224 225
    }
  }
226 227 228 229 230

  if (!isset($wrappers_storage[$filter])) {
    $wrappers_storage[$filter] = array();
    foreach ($wrappers_storage[STREAM_WRAPPERS_ALL] as $scheme => $info) {
      // Bit-wise filter.
231
      if (($info['type'] & $filter) == $filter) {
232 233 234 235 236 237
        $wrappers_storage[$filter][$scheme] = $info;
      }
    }
  }

  return $wrappers_storage[$filter];
238 239 240 241 242 243 244
}

/**
 * Returns the stream wrapper class name for a given scheme.
 *
 * @param $scheme
 *   Stream scheme.
245
 *
246 247 248 249 250 251 252 253 254 255 256 257 258
 * @return
 *   Return string if a scheme has a registered handler, or FALSE.
 */
function file_stream_wrapper_get_class($scheme) {
  $wrappers = file_get_stream_wrappers();
  return empty($wrappers[$scheme]) ? FALSE : $wrappers[$scheme]['class'];
}

/**
 * Returns the scheme of a URI (e.g. a stream).
 *
 * @param $uri
 *   A stream, referenced as "scheme://target".
259
 *
260 261 262
 * @return
 *   A string containing the name of the scheme, or FALSE if none. For example,
 *   the URI "public://example.txt" would return "public".
263 264
 *
 * @see file_uri_target()
265 266
 */
function file_uri_scheme($uri) {
267 268
  $position = strpos($uri, '://');
  return $position ? substr($uri, 0, $position) : FALSE;
269 270 271
}

/**
272
 * Checks that the scheme of a stream URI is valid.
273 274 275 276 277 278 279
 *
 * Confirms that there is a registered stream handler for the provided scheme
 * and that it is callable. This is useful if you want to confirm a valid
 * scheme without creating a new instance of the registered handler.
 *
 * @param $scheme
 *   A URI scheme, a stream is referenced as "scheme://target".
280
 *
281 282 283 284 285 286 287 288 289 290 291 292 293 294 295
 * @return
 *   Returns TRUE if the string is the name of a validated stream,
 *   or FALSE if the scheme does not have a registered handler.
 */
function file_stream_wrapper_valid_scheme($scheme) {
  // Does the scheme have a registered handler that is callable?
  $class = file_stream_wrapper_get_class($scheme);
  if (class_exists($class)) {
    return TRUE;
  }
  else {
    return FALSE;
  }
}

296

297
/**
298
 * Returns the part of a URI after the schema.
299 300 301
 *
 * @param $uri
 *   A stream, referenced as "scheme://target".
302
 *
303 304 305 306
 * @return
 *   A string containing the target (path), or FALSE if none.
 *   For example, the URI "public://sample/test.txt" would return
 *   "sample/test.txt".
307 308
 *
 * @see file_uri_scheme()
309 310
 */
function file_uri_target($uri) {
311 312 313 314
  $data = explode('://', $uri, 2);

  // Remove erroneous leading or trailing, forward-slashes and backslashes.
  return count($data) == 2 ? trim($data[1], '\/') : FALSE;
315 316
}

317
/**
318
 * Gets the default file stream implementation.
319 320 321 322 323 324 325 326
 *
 * @return
 *   'public', 'private' or any other file scheme defined as the default.
 */
function file_default_scheme() {
  return variable_get('file_default_scheme', 'public');
}

327 328 329 330 331 332 333 334 335 336 337
/**
 * Normalizes a URI by making it syntactically correct.
 *
 * A stream is referenced as "scheme://target".
 *
 * The following actions are taken:
 * - Remove trailing slashes from target
 * - Trim erroneous leading slashes from target. e.g. ":///" becomes "://".
 *
 * @param $uri
 *   String reference containing the URI to normalize.
338
 *
339 340
 * @return
 *   The normalized URI.
341 342 343 344 345 346 347
 */
function file_stream_wrapper_uri_normalize($uri) {
  $scheme = file_uri_scheme($uri);

  if ($scheme && file_stream_wrapper_valid_scheme($scheme)) {
    $target = file_uri_target($uri);

348 349 350
    if ($target !== FALSE) {
      $uri = $scheme . '://' . $target;
    }
351
  }
352 353 354 355
  else {
    // The default scheme is file://
    $url = 'file://' . $uri;
  }
356 357 358 359
  return $uri;
}

/**
360
 * Returns a reference to the stream wrapper class responsible for a given URI.
361 362 363 364 365 366
 *
 * The scheme determines the stream wrapper class that should be
 * used by consulting the stream wrapper registry.
 *
 * @param $uri
 *   A stream, referenced as "scheme://target".
367
 *
368 369 370 371
 * @return
 *   Returns a new stream wrapper object appropriate for the given URI or FALSE
 *   if no registered handler could be found. For example, a URI of
 *   "private://example.txt" would return a new private stream wrapper object
webchick's avatar
webchick committed
372
 *   (Drupal\Core\StreamWrapper\PrivateStream).
373 374 375 376 377
 */
function file_stream_wrapper_get_instance_by_uri($uri) {
  $scheme = file_uri_scheme($uri);
  $class = file_stream_wrapper_get_class($scheme);
  if (class_exists($class)) {
378
    $instance = new $class();
379 380 381 382 383 384 385 386 387
    $instance->setUri($uri);
    return $instance;
  }
  else {
    return FALSE;
  }
}

/**
388
 * Returns a reference to the stream wrapper class responsible for a scheme.
389 390 391 392 393 394 395 396 397 398 399
 *
 * This helper method returns a stream instance using a scheme. That is, the
 * passed string does not contain a "://". For example, "public" is a scheme
 * but "public://" is a URI (stream). This is because the later contains both
 * a scheme and target despite target being empty.
 *
 * Note: the instance URI will be initialized to "scheme://" so that you can
 * make the customary method calls as if you had retrieved an instance by URI.
 *
 * @param $scheme
 *   If the stream was "public://target", "public" would be the scheme.
400
 *
401 402 403
 * @return
 *   Returns a new stream wrapper object appropriate for the given $scheme.
 *   For example, for the public scheme a stream wrapper object
webchick's avatar
webchick committed
404
 *   (Drupal\Core\StreamWrapper\PublicStream).
405 406 407 408 409
 *   FALSE is returned if no registered handler could be found.
 */
function file_stream_wrapper_get_instance_by_scheme($scheme) {
  $class = file_stream_wrapper_get_class($scheme);
  if (class_exists($class)) {
410
    $instance = new $class();
411 412 413 414 415 416 417 418
    $instance->setUri($scheme . '://');
    return $instance;
  }
  else {
    return FALSE;
  }
}

Dries's avatar
 
Dries committed
419
/**
420
 * Creates a web-accessible URL for a stream to an external or local file.
Dries's avatar
 
Dries committed
421
 *
422
 * Compatibility: normal paths and stream wrappers.
Dries's avatar
 
Dries committed
423
 *
424
 * There are two kinds of local files:
425 426 427
 * - "managed files", i.e. those stored by a Drupal-compatible stream wrapper.
 *   These are files that have either been uploaded by users or were generated
 *   automatically (for example through CSS aggregation).
428 429 430
 * - "shipped files", i.e. those outside of the files directory, which ship as
 *   part of Drupal core or contributed modules or themes.
 *
431
 * @param $uri
432 433
 *   The URI to a file for which we need an external URL, or the path to a
 *   shipped file.
434
 *
435
 * @return
436
 *   A string containing a URL that may be used to access the file.
437 438 439
 *   If the provided string already contains a preceding 'http', 'https', or
 *   '/', nothing is done and the same string is returned. If a stream wrapper
 *   could not be found to generate an external URL, then FALSE is returned.
440 441
 *
 * @see http://drupal.org/node/515192
Dries's avatar
 
Dries committed
442
 */
443
function file_create_url($uri) {
444 445 446
  // Allow the URI to be altered, e.g. to serve a file from a CDN or static
  // file server.
  drupal_alter('file_url', $uri);
447

448 449 450
  $scheme = file_uri_scheme($uri);

  if (!$scheme) {
451 452 453 454 455 456 457 458 459 460 461 462
    // Allow for:
    // - root-relative URIs (e.g. /foo.jpg in http://example.com/foo.jpg)
    // - protocol-relative URIs (e.g. //bar.jpg, which is expanded to
    //   http://example.com/bar.jpg by the browser when viewing a page over
    //   HTTP and to https://example.com/bar.jpg when viewing a HTTPS page)
    // Both types of relative URIs are characterized by a leading slash, hence
    // we can use a single check.
    if (drupal_substr($uri, 0, 1) == '/') {
      return $uri;
    }
    else {
      // If this is not a properly formatted stream, then it is a shipped file.
463 464
      // Therefore, return the urlencoded URI with the base URL prepended.
      return $GLOBALS['base_url'] . '/' . drupal_encode_path($uri);
465
    }
466 467 468 469 470 471 472 473 474 475 476 477 478 479 480
  }
  elseif ($scheme == 'http' || $scheme == 'https') {
    // Check for http so that we don't have to implement getExternalUrl() for
    // the http wrapper.
    return $uri;
  }
  else {
    // Attempt to return an external URL using the appropriate wrapper.
    if ($wrapper = file_stream_wrapper_get_instance_by_uri($uri)) {
      return $wrapper->getExternalUrl();
    }
    else {
      return FALSE;
    }
  }
Dries's avatar
 
Dries committed
481 482 483
}

/**
484
 * Checks that the directory exists and is writable.
485 486 487 488
 *
 * Directories need to have execute permissions to be considered a directory by
 * FTP servers, etc.
 *
489
 * @param $directory
490 491 492
 *   A string reference containing the name of a directory path or URI. A
 *   trailing slash will be trimmed from a path.
 * @param $options
493 494 495
 *   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).
496
 *
497
 * @return
498 499
 *   TRUE if the directory exists (or was created) and is writable. FALSE
 *   otherwise.
Dries's avatar
 
Dries committed
500
 */
501 502 503 504 505
function file_prepare_directory(&$directory, $options = FILE_MODIFY_PERMISSIONS) {
  if (!file_stream_wrapper_valid_scheme(file_uri_scheme($directory))) {
    // Only trim if we're not dealing with a stream.
    $directory = rtrim($directory, '/\\');
  }
Dries's avatar
 
Dries committed
506 507 508

  // Check if directory exists.
  if (!is_dir($directory)) {
509 510
    // Let mkdir() recursively create directories and use the default directory
    // permissions.
511 512
    if (($options & FILE_CREATE_DIRECTORY) && @drupal_mkdir($directory, NULL, TRUE)) {
      return drupal_chmod($directory);
Dries's avatar
 
Dries committed
513
    }
514
    return FALSE;
Dries's avatar
 
Dries committed
515
  }
516 517 518 519
  // The directory exists, so check to see if it is writable.
  $writable = is_writable($directory);
  if (!$writable && ($options & FILE_MODIFY_PERMISSIONS)) {
    return drupal_chmod($directory);
Dries's avatar
 
Dries committed
520 521
  }

522
  return $writable;
Dries's avatar
 
Dries committed
523 524 525
}

/**
526
 * Creates a .htaccess file in each Drupal files directory if it is missing.
Dries's avatar
 
Dries committed
527
 */
528
function file_ensure_htaccess() {
529
  file_save_htaccess('public://', FALSE);
530
  if (variable_get('file_private_path', FALSE)) {
531
    file_save_htaccess('private://', TRUE);
532
  }
533
  file_save_htaccess('temporary://', TRUE);
534
  file_save_htaccess(config_get_config_directory(), TRUE);
Dries's avatar
 
Dries committed
535 536 537
}

/**
538
 * Creates a .htaccess file in the given directory.
Dries's avatar
 
Dries committed
539
 *
540
 * @param $directory
541 542 543 544
 *   The directory.
 * @param $private
 *   FALSE indicates that $directory should be an open and public directory.
 *   The default is TRUE which indicates a private and protected directory.
Dries's avatar
 
Dries committed
545
 */
546
function file_save_htaccess($directory, $private = TRUE) {
547 548
  if (file_uri_scheme($directory)) {
    $directory = file_stream_wrapper_uri_normalize($directory);
549 550
  }
  else {
551
    $directory = rtrim($directory, '/\\');
552
  }
553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574
  $htaccess_path =  $directory . '/.htaccess';

  if (file_exists($htaccess_path)) {
    // Short circuit if the .htaccess file already exists.
    return;
  }

  if ($private) {
    // Private .htaccess file.
    $htaccess_lines = "SetHandler Drupal_Security_Do_Not_Remove_See_SA_2006_006\nDeny from all\nOptions None\nOptions +FollowSymLinks";
  }
  else {
    // Public .htaccess file.
    $htaccess_lines = "SetHandler Drupal_Security_Do_Not_Remove_See_SA_2006_006\nOptions None\nOptions +FollowSymLinks";
  }

  // Write the .htaccess file.
  if (file_put_contents($htaccess_path, $htaccess_lines)) {
    drupal_chmod($htaccess_path, 0444);
  }
  else {
    $variables = array('%directory' => $directory, '!htaccess' => '<br />' . nl2br(check_plain($htaccess_lines)));
575
    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);
Dries's avatar
 
Dries committed
576 577 578 579
  }
}

/**
580
 * Loads file objects from the database.
581
 *
582 583 584
 * @param $fids
 *   An array of file IDs.
 * @param $conditions
585 586 587 588 589
 *   (deprecated) An associative array of conditions on the {file_managed}
 *   table, where the keys are the database fields and the values are the
 *   values those fields must have. Instead, it is preferable to use
 *   EntityFieldQuery to retrieve a list of entity IDs loadable by
 *   this function.
590
 *
591
 * @return
592
 *   An array of file objects, indexed by fid.
593
 *
594 595
 * @todo Remove $conditions in Drupal 8.
 *
596
 * @see hook_file_load()
597
 * @see file_load()
598 599
 * @see entity_load()
 * @see EntityFieldQuery
600
 */
601
function file_load_multiple($fids = array(), $conditions = array()) {
602
  return entity_load('file', $fids, $conditions);
603
}
604

605
/**
606
 * Loads a single file object from the database.
607 608
 *
 * @param $fid
609
 *   A file ID.
610
 *
611 612 613 614 615 616 617 618 619
 * @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);
620 621 622
}

/**
623
 * Saves a file object to the database.
624
 *
625
 * If the $file->fid is not set a new record will be added.
626 627 628
 *
 * @param $file
 *   A file object returned by file_load().
629
 *
630 631
 * @return
 *   The updated file object.
632
 *
633 634 635
 * @see hook_file_insert()
 * @see hook_file_update()
 */
636
function file_save(stdClass $file) {
637
  $file->timestamp = REQUEST_TIME;
638
  $file->filesize = filesize($file->uri);
639 640 641 642 643
  if (!isset($file->langcode)) {
    // Default the file's language code to none, because files are language
    // neutral more often than language dependent. Until we have better flexible
    // settings.
    // @todo See http://drupal.org/node/258785 and followups.
644
    $file->langcode = LANGUAGE_NOT_SPECIFIED;
645
  }
646

647 648 649 650 651
  // Load the stored entity, if any.
  if (!empty($file->fid) && !isset($file->original)) {
    $file->original = entity_load_unchanged('file', $file->fid);
  }

652 653 654
  module_invoke_all('file_presave', $file);
  module_invoke_all('entity_presave', $file, 'file');

655
  if (empty($file->fid)) {
656
    drupal_write_record('file_managed', $file);
657 658
    // Inform modules about the newly added file.
    module_invoke_all('file_insert', $file);
659
    module_invoke_all('entity_insert', $file, 'file');
660 661
  }
  else {
662
    drupal_write_record('file_managed', $file, 'fid');
663 664
    // Inform modules that the file has been updated.
    module_invoke_all('file_update', $file);
665
    module_invoke_all('entity_update', $file, 'file');
666 667
  }

668
  unset($file->original);
669 670 671 672
  return $file;
}

/**
673 674 675 676 677 678 679
 * Determines where a file is used.
 *
 * @param $file
 *   A file object.
 *
 * @return
 *   A nested array with usage data. The first level is keyed by module name,
680 681
 *   the second by object type and the third by the object id. The value
 *   of the third level contains the usage count.
682 683 684 685 686 687 688 689 690 691 692 693
 *
 * @see file_usage_add()
 * @see file_usage_delete()
 */
function file_usage_list(stdClass $file) {
  $result = db_select('file_usage', 'f')
    ->fields('f', array('module', 'type', 'id', 'count'))
    ->condition('fid', $file->fid)
    ->condition('count', 0, '>')
    ->execute();
  $references = array();
  foreach ($result as $usage) {
694
    $references[$usage->module][$usage->type][$usage->id] = $usage->count;
695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716
  }
  return $references;
}

/**
 * Records that a module is using a file.
 *
 * This usage information will be queried during file_delete() to ensure that
 * a file is not in use before it is physically removed from disk.
 *
 * Examples:
 * - A module that associates files with nodes, so $type would be
 *   'node' and $id would be the node's nid. Files for all revisions are stored
 *   within a single nid.
 * - The User module associates an image with a user, so $type would be 'user'
 *   and the $id would be the user's uid.
 *
 * @param $file
 *   A file object.
 * @param $module
 *   The name of the module using the file.
 * @param $type
717
 *   The type of the object that contains the referenced file.
718
 * @param $id
719
 *   The unique, numeric ID of the object containing the referenced file.
720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779
 * @param $count
 *   (optional) The number of references to add to the object. Defaults to 1.
 *
 * @see file_usage_list()
 * @see file_usage_delete()
 */
function file_usage_add(stdClass $file, $module, $type, $id, $count = 1) {
  db_merge('file_usage')
    ->key(array(
      'fid' => $file->fid,
      'module' => $module,
      'type' => $type,
      'id' => $id,
    ))
    ->fields(array('count' => $count))
    ->expression('count', 'count + :count', array(':count' => $count))
    ->execute();
}

/**
 * Removes a record to indicate that a module is no longer using a file.
 *
 * The file_delete() function is typically called after removing a file usage
 * to remove the record from the file_managed table and delete the file itself.
 *
 * @param $file
 *   A file object.
 * @param $module
 *   The name of the module using the file.
 * @param $type
 *   (optional) The type of the object that contains the referenced file. May
 *   be omitted if all module references to a file are being deleted.
 * @param $id
 *   (optional) The unique, numeric ID of the object containing the referenced
 *   file. May be omitted if all module references to a file are being deleted.
 * @param $count
 *   (optional) The number of references to delete from the object. Defaults to
 *   1. 0 may be specified to delete all references to the file within a
 *   specific object.
 *
 * @see file_usage_add()
 * @see file_usage_list()
 * @see file_delete()
 */
function file_usage_delete(stdClass $file, $module, $type = NULL, $id = NULL, $count = 1) {
  // Delete rows that have a exact or less value to prevent empty rows.
  $query = db_delete('file_usage')
    ->condition('module', $module)
    ->condition('fid', $file->fid);
  if ($type && $id) {
    $query
      ->condition('type', $type)
      ->condition('id', $id);
  }
  if ($count) {
    $query->condition('count', $count, '<=');
  }
  $result = $query->execute();

  // If the row has more than the specified count decrement it by that number.
780
  if (!$result && $count > 0) {
781 782 783 784 785 786 787 788
    $query = db_update('file_usage')
      ->condition('module', $module)
      ->condition('fid', $file->fid);
    if ($type && $id) {
      $query
        ->condition('type', $type)
        ->condition('id', $id);
    }
789
    $query->expression('count', 'count - :count', array(':count' => $count));
790 791 792 793 794 795
    $query->execute();
  }
}

/**
 * Copies a file to a new location and adds a file record to the database.
796 797 798 799 800 801 802 803 804 805
 *
 * 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
806 807
 *   temporary file, the resulting file will also be a temporary file. See
 *   file_save_upload() for details on temporary files.
808 809 810 811
 *
 * @param $source
 *   A file object.
 * @param $destination
812
 *   A string containing the destination that $source should be copied to.
813
 *   This must be a stream wrapper URI.
814 815
 * @param $replace
 *   Replace behavior when the destination file already exists:
816 817 818
 *   - 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.
819
 *   - FILE_EXISTS_RENAME - Append _{incrementing number} until the filename is
820
 *       unique.
821
 *   - FILE_EXISTS_ERROR - Do nothing and return FALSE.
822
 *
823 824
 * @return
 *   File object if the copy is successful, or FALSE in the event of an error.
825
 *
826 827 828
 * @see file_unmanaged_copy()
 * @see hook_file_copy()
 */
829
function file_copy(stdClass $source, $destination = NULL, $replace = FILE_EXISTS_RENAME) {
830
  if (!file_valid_uri($destination)) {
831
    if (($realpath = drupal_realpath($source->uri)) !== FALSE) {
832
      watchdog('file', 'File %file (%realpath) could not be copied because the destination %destination is invalid. This is often caused by improper use of file_copy() or a missing stream wrapper.', array('%file' => $source->uri, '%realpath' => $realpath, '%destination' => $destination));
833 834
    }
    else {
835
      watchdog('file', 'File %file could not be copied because the destination %destination is invalid. This is often caused by improper use of file_copy() or a missing stream wrapper.', array('%file' => $source->uri, '%destination' => $destination));
836
    }
837
    drupal_set_message(t('The specified file %file could not be copied because the destination is invalid. More information is available in the system log.', array('%file' => $source->uri)), 'error');
838 839 840
    return FALSE;
  }

841
  if ($uri = file_unmanaged_copy($source->uri, $destination, $replace)) {
842
    $file = clone $source;
843
    $file->fid = NULL;
844
    $file->uri = $uri;
845
    $file->filename = drupal_basename($uri);
846 847
    // If we are replacing an existing file re-use its database record.
    if ($replace == FILE_EXISTS_REPLACE) {
848
      $existing_files = file_load_multiple(array(), array('uri' => $uri));
849 850 851 852 853
      if (count($existing_files)) {
        $existing = reset($existing_files);
        $file->fid = $existing->fid;
        $file->filename = $existing->filename;
      }
854
    }
855 856
    // If we are renaming around an existing file (rather than a directory),
    // use its basename for the filename.
857
    elseif ($replace == FILE_EXISTS_RENAME && is_file($destination)) {
858
      $file->filename = drupal_basename($destination);
859 860 861 862 863 864 865 866
    }

    $file = file_save($file);

    // Inform modules that the file has been copied.
    module_invoke_all('file_copy', $file, $source);

    return $file;
867 868 869 870
  }
  return FALSE;
}

871
/**
872
 * Determines whether the URI has a valid scheme for file API operations.
873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892
 *
 * There must be a scheme and it must be a Drupal-provided scheme like
 * 'public', 'private', 'temporary', or an extension provided with
 * hook_stream_wrappers().
 *
 * @param $uri
 *   The URI to be tested.
 *
 * @return
 *   TRUE if the URI is allowed.
 */
function file_valid_uri($uri) {
  // Assert that the URI has an allowed scheme. Barepaths are not allowed.
  $uri_scheme = file_uri_scheme($uri);
  if (empty($uri_scheme) || !file_stream_wrapper_valid_scheme($uri_scheme)) {
    return FALSE;
  }
  return TRUE;
}

893
/**
894
 * Copies a file to a new location without invoking the file API.
Dries's avatar
 
Dries committed
895
 *
896 897 898 899 900 901 902
 * 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.
903 904 905 906
 * - Provides a fallback using realpaths if the move fails using stream
 *   wrappers. This can occur because PHP's copy() function does not properly
 *   support streams if safe_mode or open_basedir are enabled. See
 *   https://bugs.php.net/bug.php?id=60456
907 908
 *
 * @param $source
909
 *   A string specifying the filepath or URI of the source file.
910
 * @param $destination
911 912 913 914
 *   A URI containing the destination that $source should be copied to. The
 *   URI may be a bare filepath (without a scheme) and in that case the default
 *   scheme (file://) will be used. If this value is omitted, Drupal's default
 *   files scheme will be used, usually "public://".
915 916 917 918
 * @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
919
 *       unique.
920
 *   - FILE_EXISTS_ERROR - Do nothing and return FALSE.
921
 *
922 923
 * @return
 *   The path to the new file, or FALSE in the event of an error.
924
 *
925
 * @see file_copy()
Dries's avatar
 
Dries committed
926
 */
927
function file_unmanaged_copy($source, $destination = NULL, $replace = FILE_EXISTS_RENAME) {
928 929 930
  $original_source = $source;
  $original_destination = $destination;

931
  // Assert that the source file actually exists.
932
  if (!file_exists($source)) {
933
    // @todo Replace drupal_set_message() calls with exceptions instead.
934
    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' => $original_source)), 'error');
935 936 937 938 939 940
    if (($realpath = drupal_realpath($original_source)) !== FALSE) {
      watchdog('file', 'File %file (%realpath) could not be copied because it does not exist.', array('%file' => $original_source, '%realpath' => $realpath));
    }
    else {
      watchdog('file', 'File %file could not be copied because it does not exist.', array('%file' => $original_source));
    }
941 942
    return FALSE;
  }
Dries's avatar
 
Dries committed
943

944 945
  // Build a destination URI if necessary.
  if (!isset($destination)) {
946
    $destination = file_build_uri(drupal_basename($source));
947
  }
Dries's avatar
 
Dries committed
948 949


950 951 952
  // Prepare the destination directory.
  if (file_prepare_directory($destination)) {
    // The destination is already a directory, so append the source basename.
953
    $destination = file_stream_wrapper_uri_normalize($destination . '/' . drupal_basename($source));
954 955 956 957 958 959
  }
  else {
    // Perhaps $destination is a dir/file?
    $dirname = drupal_dirname($destination);
    if (!file_prepare_directory($dirname)) {
      // The destination is not valid.
960 961
      watchdog('file', 'File %file could not be copied because the destination directory %destination is not configured correctly.', array('%file' => $original_source, '%destination' => $dirname));
      drupal_set_message(t('The specified file %file could not be copied because the destination directory is not properly configured. This may be caused by a problem with file or directory permissions. More information is available in the system log.', array('%file' => $original_source)), 'error');
962 963 964
      return FALSE;
    }
  }
965

966 967
  // Determine whether we can perform this operation based on overwrite rules.
  $destination = file_destination($destination, $replace);
968
  if ($destination === FALSE) {
969
    drupal_set_message(t('The file %file could not be copied because a file by that name already exists in the destination directory.', array('%file' => $original_source)), 'error');
970
    watchdog('file', 'File %file could not be copied because a file by that name already exists in the destination directory (%directory)', array('%file' => $original_source, '%destination' => $destination));
971
    return FALSE;
Dries's avatar
 
Dries committed
972
  }
973 974

  // Assert that the source and destination filenames are not the same.
975 976 977
  $real_source = drupal_realpath($source);
  $real_destination = drupal_realpath($destination);
  if ($source == $destination || ($real_source !== FALSE) && ($real_source == $real_destination)) {
978
    drupal_set_message(t('The specified file %file was not copied because it would overwrite itself.', array('%file' => $source)), 'error');
979
    watchdog('file', 'File %file could not be copied because it would overwrite itself.', array('%file' => $source));
980
    return FALSE;
Dries's avatar
 
Dries committed
981
  }
982 983 984
  // Make sure the .htaccess files are present.
  file_ensure_htaccess();
  // Perform the copy operation.
985
  if (!@copy($source, $destination)) {
986 987 988 989 990 991
    // If the copy failed and realpaths exist, retry the operation using them
    // instead.
    if ($real_source === FALSE || $real_destination === FALSE || !@copy($real_source, $real_destination)) {
      watchdog('file', 'The specified file %file could not be copied to %destination.', array('%file' => $source, '%destination' => $destination), WATCHDOG_ERROR);
      return FALSE;
    }
Dries's avatar
 
Dries committed
992
  }
Dries's avatar
 
Dries committed
993

994 995
  // Set the permissions on the new file.
  drupal_chmod($destination);
996 997

  return $destination;
Dries's avatar
 
Dries committed
998 999
}

1000
/**
1001
 * Constructs a URI to Drupal's default files location given a relative path.
1002 1003
 */
function file_build_uri($path) {
1004
  $uri = file_default_scheme() . '://' . $path;
1005 1006 1007
  return file_stream_wrapper_uri_normalize($uri);
}

1008
/**
1009
 * Determines the destination path for a file.
1010
 *
1011
 * @param $destination
1012
 *   A string specifying the desired final URI or filepath.
1013 1014
 * @param $replace
 *   Replace behavior when the destination file already exists.
1015
 *   - FILE_EXISTS_REPLACE - Replace the existing file.
1016
 *   - FILE_EXISTS_RENAME - Append _{incrementing number} until the filename is
1017
 *       unique.
1018
 *   - FILE_EXISTS_ERROR - Do nothing and return FALSE.
1019
 *
1020
 * @return
1021 1022
 *   The destination filepath, or FALSE if the file already exists
 *   and FILE_EXISTS_ERROR is specified.
1023 1024 1025 1026
 */
function file_destination($destination, $replace) {
  if (file_exists($destination)) {
    switch ($replace) {
1027 1028 1029 1030
      case FILE_EXISTS_REPLACE:
        // Do nothing here, we want to overwrite the existing file.
        break;

1031
      case FILE_EXISTS_RENAME:
1032
        $basename = drupal_basename($destination);
1033
        $directory = drupal_dirname($destination);
1034 1035 1036 1037
        $destination = file_create_filename($basename, $directory);
        break;

      case FILE_EXISTS_ERROR:
1038
        // Error reporting handled by calling function.
1039 1040 1041 1042 1043 1044
        return FALSE;
    }
  }
  return $destination;
}

Dries's avatar
 
Dries committed
1045
/**
1046
 * Moves a file to a new location and update the file's database entry.
1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058
 *
 * 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
1059
 *   A string containing the destination that $source should be moved to.
1060
 *   This must be a stream wrapper URI.
1061 1062
 * @param $replace
 *   Replace behavior when the destination file already exists:
1063 1064 1065 1066 1067
 *   - FILE_EXISTS_REPLACE - Replace the existing file. If a managed file with
 *       the destination name exists then its database entry will be updated and
 *       file_delete() called on the source file after hook_file_move is called.
 *       If no database entry is found then the source files record will be
 *       updated.
1068
 *   - FILE_EXISTS_RENAME - Append _{incrementing number} until the filename is
1069
 *       unique.
1070
 *   - FILE_EXISTS_ERROR - Do nothing and return FALSE.
1071
 *
1072 1073
 * @return
 *   Resulting file object for success, or FALSE in the event of an error.
1074
 *
1075 1076 1077
 * @see file_unmanaged_move()
 * @see hook_file_move()
 */
1078
function file_move(stdClass $source, $destination = NULL, $replace = FILE_EXISTS_RENAME) {
1079
  if (!file_valid_uri($destination)) {
1080
    if (($realpath = drupal_realpath($source->uri)) !== FALSE) {
1081