diff --git includes/file.inc includes/file.inc index 6c463e2..b23bfd0 100644 --- includes/file.inc +++ includes/file.inc @@ -7,6 +7,13 @@ */ /** + * 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. @@ -77,6 +84,227 @@ define('FILE_EXISTS_ERROR', 2); define('FILE_STATUS_PERMANENT', 1); /** + * Methods to manage a registry of stream wrappers. + */ + +/** + * Drupal stream wrapper registry. + * + * 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, it will + * be unregistered and replaced with the specified class. + * + * A stream is referenced as: scheme://target + * + * Returns the entire Drupal stream wrapper registry. + * @return array + * + * @see hook_stream_wrappers() + * @see hook_stream_wrappers_alter() + */ + +function file_get_stream_wrappers() { + $wrappers = &drupal_static(__FUNCTION__); + + if (!isset($wrappers)) { + $wrappers = module_invoke_all('stream_wrappers'); + 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; + } + stream_wrapper_register($scheme, $info['class']); + } + } + }file_put_contents('/tmp/log.txt', print_r($wrappers,1)); + return $wrappers; +} + +/** + * 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). + * + * A stream is referenced as scheme://target. + * + * @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. + */ +function file_uri_scheme($uri) { + $data = explode('://', $uri, 2); + + return count($data) == 2 ? $data[0] : FALSE; +} + +/** + * Check 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 usefule 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 a string containing the name of a validated stream, + * or FALSE if the URI does not contain a scheme or 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 $scheme; + } + else { + return FALSE; + } +} + +/** + * Returns the target of a URI (e.g. a stream). + * + * A stream is referenced as scheme://target. + * + * @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 + */ +function file_uri_target($uri) { + $data = explode('://', $uri, 2); + + if (count($data) != 2) { + return FALSE; + } + + // Remove erroneous beginning forward slash + $data[1] = ltrim($data[1], '\/'); + + return $data[1]; +} + +/** + * Normalizes a URI by making it syntactically correct. + * + * A stream is referenced as scheme://target. + * + * The following actions are taken: + * - Remove all occurrences of the wrapper's directory path + * - Remove trailing slashes from target + * - Trim erroneous leading slashes from target. e.g. ':///' becomes '://' + * + * @param $uri + * String reference containing the URI to normalize. + */ +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); + + // Remove all occurrences of the wrapper's directory path. + $directory_path = file_stream_wrapper_get_instance_by_scheme($scheme)->getDirectoryPath(); + $target = str_replace($directory_path, '', $target); + + // Trim trailing slashes from target + $target = rtrim($target, '/'); + + // Trim erroneous leading slashes from target. + $uri = $scheme . '://' . ltrim($target, '/'); + } + return $uri; +} + +/** + * Returns a reference to the stream wrapper class responsible for a given URI (stream). + * + * 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. + * For example, a URI of public://example.txt would return a new + * private stream wrapper object (DrupalPrivateStreamWrapper). + * FALSE is returned if no registered handler could be found. + */ +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 given scheme. + * + * This helper method returns a stream instance using a scheme. That is, the + * passed string does not container 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; + } +} + +/** * Create the download path to a file. * * @param $path A string containing the path of the file to generate URL for. diff --git includes/stream_wrappers.inc includes/stream_wrappers.inc new file mode 100644 index 0000000..40c482e --- /dev/null +++ includes/stream_wrappers.inc @@ -0,0 +1,649 @@ +uri = $uri; + } + + /** + * Base implementation of getInternalUri(). + */ + function getInternalUri() { + return $this->getDirectoryPath() . '/' . file_uri_target($this->uri); + } + + /** + * Base implementation of getExternalUrl(). + */ + function getExternalUrl() { + return $this->uri; + } + + /** + * Base implementation of getMimeType(). + */ + static function getMimeType($uri, $mapping = NULL) { + if (!isset($mapping)) { + $mapping = variable_get('mime_extension_mapping', NULL); + if (!isset($mapping) && drupal_function_exists('file_default_mimetype_mapping')) { + // The default file map, defined in file.mimetypes.inc is quite big. + // We only load it when necessary. + $mapping = file_default_mimetype_mapping(); + } + } + + $extension = ''; + $file_parts = explode('.', basename($uri)); + + // Remove the first part: a full filename should not match an extension. + array_shift($file_parts); + + // Iterate over the file parts, trying to find a match. + // For my.awesome.image.jpeg, we try: + // - jpeg + // - image.jpeg, and + // - awesome.image.jpeg + while ($additional_part = array_pop($file_parts)) { + $extension = strtolower($additional_part . ($extension ? '.' . $extension : '')); + if (isset($mapping['extensions'][$extension])) { + return $mapping['mimetypes'][$mapping['extensions'][$extension]]; + } + } + + return 'application/octet-stream'; + } + + /** + * Base implementation of chmod(). + */ + function chmod($mode) { + return @chmod($this->realpath(), $mode); + } + + /** + * Base implementaiton of realpath(). + */ + function realpath() { + return @realpath($this->getDirectoryPath() . '/' . file_uri_target($this->uri)); + } + + /** + * Support for fopen(), file_get_contents(), file_put_contents() etc. + * + * @param $path + * A string containing the path to the file to open. + * @param $mode + * The file mode ("r", "wb" etc.). + * @param $options + * A bit mask of STREAM_USE_PATH and STREAM_REPORT_ERRORS. + * @param &$opened_path + * A string containing the path actually opened. + * @return + * Returns TRUE if file was opened successfully. + * @see http://php.net/manual/en/streamwrapper.stream-open.php + */ + public function stream_open($uri, $mode, $options, &$opened_url) { + $this->uri = $uri; + $uri = $this->getInternalUri(); + $this->handle = ($options & STREAM_REPORT_ERRORS) ? fopen($uri, $mode) : @fopen($uri, $mode); + + if ((bool)$this->handle && $options & STREAM_USE_PATH) { + $opened_url = $uri; + } + + return (bool)$this->handle; + } + + /** + * Support for flock(). + * + * @param $operation + * @return + * Always returns TRUE at the present time. + * @see http://php.net/manual/en/streamwrapper.stream-lock.php + */ + public function stream_lock($operation) { + if (in_array($operation, array(LOCK_SH, LOCK_EX, LOCK_UN, LOCK_NB))) { + return flock($this->handle, $operation); + } + + return TRUE; + } + + /** + * Support for fread(), file_get_contents() etc. + * + * @param $count + * Maximum number of bytes to be read. + * @return + * The string that was read, or FALSE in case of an error. + * @see http://php.net/manual/en/streamwrapper.stream-read.php + */ + public function stream_read($count) { + return fread($this->handle, $count); + } + + /** + * Support for fwrite(), file_put_contents() etc. + * + * @param $data + * The string to be written. + * @return + * The number of bytes written (integer). + * @see http://php.net/manual/en/streamwrapper.stream-write.php + */ + public function stream_write($data) { + return fwrite($this->handle, $data); + } + + /** + * Support for feof(). + * + * @return + * TRUE if end-of-file has been reached. + * @see http://php.net/manual/en/streamwrapper.stream-eof.php + */ + public function stream_eof() { + return feof($this->handle); + } + + /** + * Support for fseek(). + * + * @param $offset + * The byte offset to got to. + * @param $whence + * SEEK_SET, SEEK_CUR, or SEEK_END. + * @return + * TRUE on success. + * @see http://php.net/manual/en/streamwrapper.stream-seek.php + */ + public function stream_seek($offset, $whence) { + return fseek($this->handle, $offset, $whence); + } + + /** + * Support for fflush(). + * + * @return + * TRUE if data was successfully stored (or there was no data to store). + * @see http://php.net/manual/en/streamwrapper.stream-flush.php + */ + public function stream_flush() { + return fflush($this->handle); + } + + /** + * Support for ftell(). + * + * @return + * The current offset in bytes from the beginning of file. + * @see http://php.net/manual/en/streamwrapper.stream-tell.php + */ + public function stream_tell() { + return ftell($this->handle); + } + + /** + * Support for fstat(). + * + * @return + * An array with file status, or FALSE in case of an error - see fstat() + * for a description of this array. + * @see http://php.net/manual/en/streamwrapper.stream-stat.php + */ + public function stream_stat() { + return fstat($this->handle); + } + + /** + * Support for fclose(). + * + * @return + * TRUE if stream was successfully closed. + * @see http://php.net/manual/en/streamwrapper.stream-close.php + */ + public function stream_close() { + return fclose($this->handle); + } + + /** + * Support for unlink(). + * + * @param $uri + * A string containing the uri to the resource to delete. + * @return + * TRUE if resource was successfully deleted. + * @see http://php.net/manual/en/streamwrapper.unlink.php + */ + public function unlink($uri) { + $this->uri = $uri; + return unlink($this->getInternalUri()); + } + + /** + * Support for rename(). + * + * @param $from_uri, + * The uri to the file to rename. + * @param $to_uri + * The new uri for file. + * @return + * TRUE if file was successfully renamed. + * @see http://php.net/manual/en/streamwrapper.rename.php + */ + public function rename($from_uri, $to_uri) { + return rename($this->getInternalUri($from_uri), $this->getInternalUri($to_uri)); + } + + /** + * Support for mkdir(). + * + * @param $uri + * A string containing the url to the directory to create. + * @param $mode + * Permission flags - see mkdir(). + * @param $options + * A bit mask of STREAM_REPORT_ERRORS and STREAM_MKDIR_RECURSIVE. + * @return + * TRUE if directory was successfully created. + * @see http://php.net/manual/en/streamwrapper.mkdir.php + */ + public function mkdir($uri, $mode, $options) { + $this->uri = $uri; + $recursive = (bool)($options & STREAM_MKDIR_RECURSIVE); + if ($options & STREAM_REPORT_ERRORS) { + return mkdir($this->getInternalUri(), $mode, $recursive); + } + else { + return @mkdir($this->getInternalUri(), $mode, $recursive); + } + } + + /** + * Support for rmdir(). + * + * @param $uri + * A string containing the url to the directory to delete. + * @param $options + * A bit mask of STREAM_REPORT_ERRORS. + * @return + * TRUE if directory was successfully removed. + * @see http://php.net/manual/en/streamwrapper.rmdir.php + */ + public function rmdir($uri, $options) { + $this->uri = $uri; + if ($options & STREAM_REPORT_ERRORS) { + return rmdir($this->getInternalUri()); + } + else { + return @rmdir($this->getInternalUri()); + } + } + + /** + * Support for stat(). + * + * @param $uri + * A string containing the url to get information about. + * @param $flags + * A bit mask of STREAM_URL_STAT_LINK and STREAM_URL_STAT_QUIET. + * @return + * An array with file status, or FALSE in case of an error - see fstat() + * for a description of this array. + * @see http://php.net/manual/en/streamwrapper.url-stat.php + */ + public function url_stat($uri, $flags) { + $this->uri = $uri; + if ($flags & STREAM_URL_STAT_QUIET) { + return @stat($this->getInternalUri()); + } + else { + return stat($this->getInternalUri()); + } + } + + /** + * Support for opendir(). + * + * @param $uri + * A string containing the url to the directory to open. + * @param $options + * Unknown (parameter is not documented in PHP Manual). + * @return + * TRUE on success. + * @see http://php.net/manual/en/streamwrapper.dir-opendir.php + */ + public function dir_opendir($uri, $options) { + $this->uri = $uri; + $this->handle = opendir($this->getInternalUri()); + + return (bool)$this->handle; + } + + /** + * Support for readdir(). + * + * @return + * The next filename, or FALSE if there are no more files in the directory. + * @see http://php.net/manual/en/streamwrapper.dir-readdir.php + */ + public function dir_readdir() { + return readdir($this->handle); + } + + /** + * Support for rewinddir(). + * + * @return + * TRUE on success. + * @see http://php.net/manual/en/streamwrapper.dir-rewinddir.php + */ + public function dir_rewinddir() { + return rewinddir($this->handle); + } + + /** + * Support for closedir(). + * + * @return + * TRUE on success. + * @see http://php.net/manual/en/streamwrapper.dir-closedir.php + */ + public function dir_closedir() { + return closedir($this->handle); + } +} + + +/** + * Drupal public (public://) stream wrapper class. + * + * Provides support for storing publicly accessible + * files with the Drupal file interface. + */ +class DrupalPublicStreamWrapper extends DrupalLocalStreamWrapper { + + /** + * Implements abstract public function getDirectoryPath() + */ + public function getDirectoryPath() { + return variable_get('stream_public_path', 'sites/default/files'); + } + + /** + * Overrides getExternalUrl(). + * + * Return the HTML URI of a public file. + */ + function getExternalUrl() { + $path = str_replace('\\', '/', file_uri_target($this->uri)); + return $GLOBALS['base_url'] . '/' . self::getDirectoryPath() . '/' . $path; + } +} + + +/** + * Drupal private (private://) stream wrapper class. + * + * Provides support for storing privately accessible + * files with the Drupal file interface. + * + * Extends DrupalPublicStreamWrapper. + */ +class DrupalPrivateStreamWrapper extends DrupalLocalStreamWrapper { + + /** + * Implements abstract public function getDirectoryPath() + */ + public function getDirectoryPath() { + return variable_get('stream_private_path', 'sites/default/files-private'); + } + + /** + * Overrides getExternalUrl(). + * + * Return the HTML URI of a private file. + */ + function getExternalUrl() { + $path = str_replace('\\', '/', file_uri_target($this->uri)); + return url('system/files/' . $path, array('absolute' => TRUE)); + } +} + + +/** + * Drupal temp (temp://) stream wrapper class. + * + * Provides support for storing temporarily accessible + * files with the Drupal file interface. + * + * Extends DrupalPublicStreamWrapper. + */ +class DrupalTempStreamWrapper extends DrupalLocalStreamWrapper { + + /** + * Implements abstract public function getDirectoryPath() + */ + public function getDirectoryPath() { + $temporary_directory = variable_get('stream_temp_path'); + + if (is_null($temporary_directory)) { + $directories = array(); + + // Has PHP been set with an upload_tmp_dir? + if (ini_get('upload_tmp_dir')) { + $directories[] = ini_get('upload_tmp_dir'); + } + + // Operating system specific dirs. + if (substr(PHP_OS, 0, 3) == 'WIN') { + $directories[] = 'c:/windows/temp'; + $directories[] = 'c:/winnt/temp'; + } + else { + $directories[] = '/tmp'; + } + + foreach ($directories as $directory) { + if (!$temporary_directory && is_dir($directory)) { + $temporary_directory = $directory; + } + } + + // If a directory has been found, use it, otherwise default to 'files/tmp' + $temporary_directory = $temporary_directory ? $temporary_directory : file_directory_path('public') . '/tmp'; + variable_set('stream_temp_path', $temporary_directory); + return $temporary_directory; + } + + return variable_get('stream_temp_path', '/tmp'); + } +} diff --git modules/simpletest/tests/file.test modules/simpletest/tests/file.test index d70d30d..ede2ce4 100644 --- modules/simpletest/tests/file.test +++ modules/simpletest/tests/file.test @@ -44,6 +44,35 @@ function file_test_file_scan_callback_reset() { } /** + * Helper class for testing the stream wrapper registry. + * + * Dummy stream wrapper implementation (dummy://). + */ +class DrupalDummyStreamWrapper extends DrupalLocalStreamWrapper { + function getDirectoryPath() { + return variable_get('stream_public_path', 'sites/default/files'); + } + + /** + * Override getInternalUri(). + * + * Return a dummy path for testing. + */ + function getInternalUri() { + return '/dummy/example.txt'; + } + + /** + * Override getExternalUrl(). + * + * Return the HTML URI of a public file. + */ + function getExternalUrl() { + return '/dummy/example.txt'; + } +} + +/** * Base class for file tests that adds some additional file specific * assertions and helper functions. */ @@ -2077,3 +2106,81 @@ class FileMimeTypeTest extends DrupalWebTestCase { } } } + +/** + * Tests stream wrapper registry. + */ +class StreamWrapperRegistryTest extends DrupalWebTestCase { + + protected $scheme = 'dummy'; + protected $classname = 'DrupalDummyStreamWrapper'; + + public static function getInfo() { + return array( + 'name' => t('Stream Wrapper Registry'), + 'description' => t('Tests stream wrapper registry.'), + 'group' => t('File'), + ); + } + + function setUp() { + drupal_static_reset('file_get_stream_wrappers'); + parent::setUp('file_test'); + } + + function tearDown() { + parent::tearDown(); + // Unregister the test handler. + stream_wrapper_unregister($this->scheme); + } + + /** + * Test the getClassName() function. + */ + function testGetClassName() { + // Check the dummy scheme. + $this->assertEqual($this->classname, file_stream_wrapper_get_class($this->scheme), t('Got correct class name for dummy scheme.')); + // Check core's scheme. + $this->assertEqual('DrupalPublicStreamWrapper', file_stream_wrapper_get_class('public'), t('Got correct class name for public scheme.')); + } + + /** + * Test the file_stream_wrapper_get_instance_by_scheme() function. + */ + function testGetInstanceByScheme() { + $instance = file_stream_wrapper_get_instance_by_scheme($this->scheme); + $this->assertEqual($this->classname, get_class($instance), t('Got correct class type for dummy scheme.')); + + $instance = file_stream_wrapper_get_instance_by_scheme('public'); + $this->assertEqual('DrupalPublicStreamWrapper', get_class($instance), t('Got correct class type for public scheme.')); + } + + /** + * Test the uri and target functions. + */ + function testGetInstanceByUri() { + $instance = file_stream_wrapper_get_instance_by_uri($this->scheme . '://foo'); + $this->assertEqual($this->classname, get_class($instance), t('Got correct class type for dummy URI.')); + + $instance = file_stream_wrapper_get_instance_by_uri('public://foo'); + $this->assertEqual('DrupalPublicStreamWrapper', get_class($instance), t('Got correct class type for public URI.')); + + // Test file_stream_wrapper_uri_normalize. + $uri = 'public:///' . $this->originalFileDirectory . '/foo/bar/'; + $uri = file_stream_wrapper_uri_normalize($uri); + $this->assertEqual('public://foo/bar', $uri, t('Got a properly normalized URI')); + + // Test file_uri_taget(). + $this->assertEqual('foo/bar.txt', file_uri_target('public://foo/bar.txt'), t('Got a valid stream target from public://foo/bar.txt')); + $this->assertFalse(file_uri_target('foo/bar.txt'), t('foo/bar.txt is not a valid stream.')); + } + + /** + * Test the scheme functions. + */ + function testGetValidStreamScheme() { + $this->assertEqual('foo', file_uri_scheme('foo://pork//chops'), t('Got the correct scheme from foo://asdf')); + $this->assertTrue(file_stream_wrapper_valid_scheme(file_uri_scheme('public://asdf')), t('Got a valid stream scheme from public://asdf')); + $this->assertFalse(file_stream_wrapper_valid_scheme(file_uri_scheme('foo://asdf')), t('Did not get a valid stream scheme from foo://asdf')); + } +} diff --git modules/simpletest/tests/file_test.module modules/simpletest/tests/file_test.module index 06aa4ad..f06116e 100644 --- modules/simpletest/tests/file_test.module +++ modules/simpletest/tests/file_test.module @@ -24,6 +24,19 @@ function file_test_menu() { } /** + * Implementation of hook_stream_wrappers(). + */ +function file_test_stream_wrappers() { + return array( + 'dummy' => array( + 'name' => t('Dummy files'), + 'class' => 'DrupalDummyStreamWrapper', + 'description' => t('Dummy wrapper for simpletest.'), + ), + ); +} + +/** * Form to test file uploads. */ function _file_test_form(&$form_state) { diff --git modules/system/system.module modules/system/system.module index 8b7cff7..e26a49c 100644 --- modules/system/system.module +++ modules/system/system.module @@ -1158,6 +1158,29 @@ function system_library() { } /** + * Implementation of hook_stream_wrappers(). + */ +function system_stream_wrappers() { + return array( + 'public' => array( + 'name' => t('Public files'), + 'class' => 'DrupalPublicStreamWrapper', + 'description' => t('Public local files served by the webserver.'), + ), + 'private' => array( + 'name' => t('Private files'), + 'class' => 'DrupalPrivateStreamWrapper', + 'description' => t('Private local files served by Drupal.'), + ), + 'temp' => array( + 'name' => t('Temporary files'), + 'class' => 'DrupalTempStreamWrapper', + 'description' => t('Temporary local files for upload and previews.'), + ) + ); +} + +/** * Retrieve a blocked IP address from the database. * * @param $iid integer