<?php

/**

 * @file

 * API for handling file uploads and server file management.

 */

/**

 * Manually include stream wrapper code.

 *

 * Stream wrapper code is included here because there are cases where

 * File API is needed before a bootstrap, or in an alternate order (e.g.

 * maintenance theme).

 */

require_once DRUPAL_ROOT . '/includes/stream_wrappers.inc';

/**

 * @defgroup file File interface

 * @{

 * Common file handling functions.

 *

 * Fields on the file object:

 * - 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

 *   the basename of the filepath if the file is renamed to avoid overwriting

 *   an existing file.

 * - 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

 *   bits are reserved for Drupal core. The least significant bit indicates

 *   temporary (0) or permanent (1). Temporary files older than

 *   DRUPAL_MAXIMUM_TEMP_FILE_AGE will be removed during cron runs.

 * - timestamp: UNIX timestamp for the date the file was added to the database.

 */

/**

 * Flag used by file_prepare_directory() -- create directory if not present.

 */

define('FILE_CREATE_DIRECTORY', 1);

/**

 * Flag used by file_prepare_directory() -- file permissions may be changed.

 */

define('FILE_MODIFY_PERMISSIONS', 2);

/**

 * Flag for dealing with existing files: Appends number until name is unique.

 */

define('FILE_EXISTS_RENAME', 0);

/**

 * Flag for dealing with existing files: Replace the existing file.

 */

define('FILE_EXISTS_REPLACE', 1);

/**

 * Flag for dealing with existing files: Do nothing and return FALSE.

 */

define('FILE_EXISTS_ERROR', 2);

/**

 * 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.

 */

define('FILE_STATUS_PERMANENT', 1);

/**

 * Provides Drupal stream wrapper registry.

 *

 * 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".

 *

 * 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(STREAM_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(STREAM_WRAPPERS_LOCAL));

 * @endcode

 *

 * @param $filter

 *   (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.

 *

 * @return

 *   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.

 *

 * @see hook_stream_wrappers()

 * @see hook_stream_wrappers_alter()

 */

function file_get_stream_wrappers($filter = STREAM_WRAPPERS_ALL) {

  $wrappers_storage = &drupal_static(__FUNCTION__);

  if (!isset($wrappers_storage)) {

    $wrappers = module_invoke_all('stream_wrappers');

    foreach ($wrappers as $scheme => $info) {

      // Add defaults.

      $wrappers[$scheme] += array('type' => STREAM_WRAPPERS_NORMAL);

    }

    drupal_alter('stream_wrappers', $wrappers);

    $existing = stream_get_wrappers();

    foreach ($wrappers as $scheme => $info) {

      // We only register classes that implement our interface.

      if (in_array('DrupalStreamWrapperInterface', class_implements($info['class']), TRUE)) {

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

        }

        if (($info['type'] & STREAM_WRAPPERS_LOCAL) == STREAM_WRAPPERS_LOCAL) {

          stream_wrapper_register($scheme, $info['class']);

        }

        else {

          stream_wrapper_register($scheme, $info['class'], STREAM_IS_URL);

        }

      }

      // 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];

      }

    }

  }

  if (!isset($wrappers_storage[$filter])) {

    $wrappers_storage[$filter] = array();

    foreach ($wrappers_storage[STREAM_WRAPPERS_ALL] as $scheme => $info) {

      // Bit-wise filter.

      if (($info['type'] & $filter) == $filter) {

        $wrappers_storage[$filter][$scheme] = $info;

      }

    }

  }

  return $wrappers_storage[$filter];

}

/**

 * Returns the stream wrapper class name for a given scheme.

 *

 * @param $scheme

 *   Stream scheme.

 *

 * @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".

 *

 * @return

 *   A string containing the name of the scheme, or FALSE if none. For example,

 *   the URI "public://example.txt" would return "public".

 *

 * @see file_uri_target()

 */

function file_uri_scheme($uri) {

  $position = strpos($uri, '://');

  return $position ? substr($uri, 0, $position) : FALSE;

}

/**

 * Checks that the scheme of a stream URI is valid.

 *

 * 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".

 *

 * @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;

  }

}

/**

 * Returns the part of a URI after the schema.

 *

 * @param $uri

 *   A stream, referenced as "scheme://target".

 *

 * @return

 *   A string containing the target (path), or FALSE if none.

 *   For example, the URI "public://sample/test.txt" would return

 *   "sample/test.txt".

 *

 * @see file_uri_scheme()

 */

function file_uri_target($uri) {

  $data = explode('://', $uri, 2);

  // Remove erroneous leading or trailing, forward-slashes and backslashes.

  return count($data) == 2 ? trim($data[1], '\/') : FALSE;

}

/**

 * Gets the default file stream implementation.

 *

 * @return

 *   'public', 'private' or any other file scheme defined as the default.

 */

function file_default_scheme() {

  return variable_get('file_default_scheme', 'public');

}

/**

 * 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.

 *

 * @return

 *   The normalized URI.

 */

function file_stream_wrapper_uri_normalize($uri) {

  // Inline file_uri_scheme() function call for performance reasons.

  $position = strpos($uri, '://');

  $scheme = $position ? substr($uri, 0, $position) : FALSE;

  if ($scheme && file_stream_wrapper_valid_scheme($scheme)) {

    $target = file_uri_target($uri);

    if ($target !== FALSE) {

      $uri = $scheme . '://' . $target;

    }

  }

  return $uri;

}

/**

 * Returns a reference to the stream wrapper class responsible for a given URI.

 *

 * 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".

 *

 * @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

 *   (DrupalPrivateStreamWrapper).

 */

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)) {

    $instance = new $class();

    $instance->setUri($uri);

    return $instance;

  }

  else {

    return FALSE;

  }

}

/**

 * Returns a reference to the stream wrapper class responsible for a scheme.

 *

 * 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.

 *

 * @return

 *   Returns a new stream wrapper object appropriate for the given $scheme.

 *   For example, for the public scheme a stream wrapper object

 *   (DrupalPublicStreamWrapper).

 *   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)) {

    $instance = new $class();

    $instance->setUri($scheme . '://');

    return $instance;

  }

  else {

    return FALSE;

  }

}

/**

 * Creates a web-accessible URL for a stream to an external or local file.

 *

 * Compatibility: normal paths and stream wrappers.

 *

 * There are two kinds of local files:

 * - "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).

 * - "shipped files", i.e. those outside of the files directory, which ship as

 *   part of Drupal core or contributed modules or themes.

 *

 * @param $uri

 *   The URI to a file for which we need an external URL, or the path to a

 *   shipped file.

 *

 * @return

 *   A string containing a URL that may be used to access the file.

 *   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.

 *

 * @see http://drupal.org/node/515192

 */

function file_create_url($uri) {

  // Allow the URI to be altered, e.g. to serve a file from a CDN or static

  // file server.

  drupal_alter('file_url', $uri);

  $scheme = file_uri_scheme($uri);

  if (!$scheme) {

    // 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.

      // Therefore, return the urlencoded URI with the base URL prepended.

      return $GLOBALS['base_url'] . '/' . drupal_encode_path($uri);

    }

  }

  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;

    }

  }

}

/**

 * Checks 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 reference containing the name of a directory path or URI. A

 *   trailing slash will be trimmed from a path.

 * @param $options

 *   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).

 *

 * @return

 *   TRUE if the directory exists (or was created) and is writable. FALSE

 *   otherwise.

 */

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, '/\\');

  }

  // Check if directory exists.

  if (!is_dir($directory)) {

    // Let mkdir() recursively create directories and use the default directory

    // permissions.

    if (($options & FILE_CREATE_DIRECTORY) && @drupal_mkdir($directory, NULL, TRUE)) {

      return drupal_chmod($directory);

    }

    return FALSE;

  }

  // 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);

  }

  return $writable;

}

/**

 * Creates a .htaccess file in each Drupal files directory if it is missing.

 */