diff --git a/includes/file.inc b/includes/file.inc
index 588bea0867adeef02157a421f2630c6568b9aae6..0eb97281f068e50a86d6a0661285d23a31ffb178 100644
--- a/includes/file.inc
+++ b/includes/file.inc
@@ -90,12 +90,37 @@
*
* 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(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
+ *
* @param $filter
- * Optionally filter out all types except these. Defaults to
- * STREAM_WRAPPERS_ALL, which returns all registered stream wrappers.
+ * (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
- * Returns the entire Drupal stream wrapper registry.
+ * 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()
@@ -122,11 +147,11 @@ function file_get_stream_wrappers($filter = STREAM_WRAPPERS_ALL) {
else {
$wrappers[$scheme]['override'] = FALSE;
}
- if (($info['type'] & STREAM_WRAPPERS_REMOTE) == STREAM_WRAPPERS_REMOTE) {
- stream_wrapper_register($scheme, $info['class'], STREAM_IS_URL);
+ if (($info['type'] & STREAM_WRAPPERS_LOCAL) == STREAM_WRAPPERS_LOCAL) {
+ stream_wrapper_register($scheme, $info['class']);
}
else {
- stream_wrapper_register($scheme, $info['class']);
+ stream_wrapper_register($scheme, $info['class'], STREAM_IS_URL);
}
}
// Pre-populate the static cache with the filters most typically used.
@@ -141,7 +166,7 @@ function file_get_stream_wrappers($filter = STREAM_WRAPPERS_ALL) {
$wrappers_storage[$filter] = array();
foreach ($wrappers_storage[STREAM_WRAPPERS_ALL] as $scheme => $info) {
// Bit-wise filter.
- if ($info['type'] & $filter == $filter) {
+ if (($info['type'] & $filter) == $filter) {
$wrappers_storage[$filter][$scheme] = $info;
}
}
diff --git a/includes/stream_wrappers.inc b/includes/stream_wrappers.inc
index f49d3bc294f387784d4cab3f59cc1c0c7510f479..23faf4fc9daf0d8ff3da55279475016eedc94299 100644
--- a/includes/stream_wrappers.inc
+++ b/includes/stream_wrappers.inc
@@ -22,6 +22,9 @@
/**
* Stream wrapper bit flags that are the basis for composite types.
+ *
+ * Note that 0x0002 is skipped, because it was the value of a constant that has
+ * since been removed.
*/
/**
@@ -34,11 +37,6 @@
*/
define('STREAM_WRAPPERS_LOCAL', 0x0001);
-/**
- * Stream wrapper bit flag -- refers to a remote filesystem location.
- */
-define('STREAM_WRAPPERS_REMOTE', 0x0002);
-
/**
* Stream wrapper bit flag -- wrapper is readable (almost always true).
*/
@@ -64,6 +62,11 @@
*/
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.
*/
@@ -74,10 +77,19 @@
*/
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.
*/
-define('STREAM_WRAPPERS_NORMAL', STREAM_WRAPPERS_LOCAL | STREAM_WRAPPERS_WRITE_VISIBLE);
+define('STREAM_WRAPPERS_LOCAL_NORMAL', STREAM_WRAPPERS_LOCAL | STREAM_WRAPPERS_NORMAL);
/**
* Generic PHP stream wrapper interface.
diff --git a/modules/system/system.api.php b/modules/system/system.api.php
index a5773c30047a593667083026d508ee746d269189..05c6d4241e2341af3bb8a5e85da37f8baa023cd1 100644
--- a/modules/system/system.api.php
+++ b/modules/system/system.api.php
@@ -2297,9 +2297,13 @@ function hook_modules_uninstalled($modules) {
* - 'class' A string specifying the PHP class that implements the
* DrupalStreamWrapperInterface interface.
* - 'description' A string with a short description of what the wrapper does.
- * - 'type' A bitmask of flags indicating what type of streams this wrapper
- * will access - local or remote, readable and/or writeable, etc. Many
- * shortcut constants are defined in stream_wrappers.inc.
+ * - 'type' (Optional) A bitmask of flags indicating what type of streams this
+ * wrapper will access - local or remote, readable and/or writeable, etc.
+ * Many shortcut constants are defined in stream_wrappers.inc. Defaults to
+ * STREAM_WRAPPERS_NORMAL which includes all of these bit flags:
+ * - STREAM_WRAPPERS_READ
+ * - STREAM_WRAPPERS_WRITE
+ * - STREAM_WRAPPERS_VISIBLE
*
* @see file_get_stream_wrappers()
* @see hook_stream_wrappers_alter()
@@ -2311,18 +2315,35 @@ function hook_stream_wrappers() {
'name' => t('Public files'),
'class' => 'DrupalPublicStreamWrapper',
'description' => t('Public local files served by the webserver.'),
+ 'type' => STREAM_WRAPPERS_LOCAL_NORMAL,
),
'private' => array(
'name' => t('Private files'),
'class' => 'DrupalPrivateStreamWrapper',
'description' => t('Private local files served by Drupal.'),
+ 'type' => STREAM_WRAPPERS_LOCAL_NORMAL,
),
'temp' => array(
'name' => t('Temporary files'),
'class' => 'DrupalTempStreamWrapper',
'description' => t('Temporary local files for upload and previews.'),
- 'type' => STREAM_WRAPPERS_HIDDEN,
- )
+ 'type' => STREAM_WRAPPERS_LOCAL_HIDDEN,
+ ),
+ 'cdn' => array(
+ 'name' => t('Content delivery network files'),
+ 'class' => 'MyModuleCDNStreamWrapper',
+ 'description' => t('Files served by a content delivery network.'),
+ // 'type' can be omitted to use the default of STREAM_WRAPPERS_NORMAL
+ ),
+ 'youtube' => array(
+ 'name' => t('YouTube video'),
+ 'class' => 'MyModuleYouTubeStreamWrapper',
+ 'description' => t('Video streamed from YouTube.'),
+ // A module implementing YouTube integration may decide to support using
+ // the YouTube API for uploading video, but here, we assume that this
+ // particular module only supports playing YouTube video.
+ 'type' => STREAM_WRAPPERS_READ_VISIBLE,
+ ),
);
}
diff --git a/modules/system/system.module b/modules/system/system.module
index 6de3a83298e6b8d33fb6a097544630273e2b30bb..d450eadc51143a4ba376004bbd07be4b94a5e7c2 100644
--- a/modules/system/system.module
+++ b/modules/system/system.module
@@ -1545,12 +1545,13 @@ function system_stream_wrappers() {
'name' => t('Public files'),
'class' => 'DrupalPublicStreamWrapper',
'description' => t('Public local files served by the webserver.'),
+ 'type' => STREAM_WRAPPERS_LOCAL_NORMAL,
),
'temporary' => array(
'name' => t('Temporary files'),
'class' => 'DrupalTemporaryStreamWrapper',
'description' => t('Temporary local files for upload and previews.'),
- 'type' => STREAM_WRAPPERS_HIDDEN,
+ 'type' => STREAM_WRAPPERS_LOCAL_HIDDEN,
),
);
@@ -1560,6 +1561,7 @@ function system_stream_wrappers() {
'name' => t('Private files'),
'class' => 'DrupalPrivateStreamWrapper',
'description' => t('Private local files served by Drupal.'),
+ 'type' => STREAM_WRAPPERS_LOCAL_NORMAL,
);
}