1. interface
  2. Drupal
  3. \
  4. Core
  5. \
  6. StreamWrapper
  7. \
  8. StreamWrapperInterface

StreamWrapperInterface

interface StreamWrapperInterface implements PhpStreamWrapperInterface (View source)

Defines a Drupal stream wrapper extension.

Provides a Drupal interface and classes to implement PHP stream wrappers for public, private, and temporary files. Extends the PhpStreamWrapperInterface with methods expected by Drupal stream wrapper classes.

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.

Note that PHP 5.2 fopen() only supports URIs of the form "scheme://target" despite the fact that according to RFC 3986 a URI's scheme component delimiter is in general just ":", not "://". Because of this PHP limitation and for consistency Drupal will only accept URIs of form "scheme://target".

Constants

ALL

A filter that matches all wrappers.
LOCAL

Refers to a local file system location.
READ

Wrapper is readable (almost always true).
WRITE

Wrapper is writable.
VISIBLE

Exposed in the UI and potentially web accessible.
HIDDEN

Defines the stream wrapper bit flag for a hidden file.

This is not visible in the UI or accessible via web, but readable and writable; for instance, the temporary directory for file uploads.
LOCAL_HIDDEN

Hidden, readable and writable using local files.
WRITE_VISIBLE

Visible, readable and writable.
READ_VISIBLE

Visible and read-only.
NORMAL

This is the default 'type' flag. This does not include StreamWrapperInterface::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.
LOCAL_NORMAL

Visible, readable and writable using local files.

Methods

bool
dir_closedir()

Close directory handle.

from  PhpStreamWrapperInterface
bool
dir_opendir(string $path, int $options)

Open directory handle.

from  PhpStreamWrapperInterface
string|false
dir_readdir()

Read entry from directory handle.

from  PhpStreamWrapperInterface
bool
dir_rewinddir()

Rewind directory handle.

from  PhpStreamWrapperInterface
bool
mkdir(string $path, int $mode, int $options)

Create a directory.

from  PhpStreamWrapperInterface
bool
rename(string $path_from, string $path_to)

Renames a file or directory.

from  PhpStreamWrapperInterface
bool
rmdir(string $path, int $options)

Removes a directory.

from  PhpStreamWrapperInterface
resource|false
stream_cast(int $cast_as)

Retrieve the underlying stream resource.

from  PhpStreamWrapperInterface
stream_close()

Closes stream.

from  PhpStreamWrapperInterface
bool
stream_eof()

Tests for end-of-file on a file pointer.

from  PhpStreamWrapperInterface
bool
stream_flush()

Flushes the output.

from  PhpStreamWrapperInterface
bool
stream_lock(int $operation)

Advisory file locking.

from  PhpStreamWrapperInterface
bool
stream_metadata(string $path, int $option, mixed $value)

Sets metadata on the stream.

from  PhpStreamWrapperInterface
bool
stream_open(string $path, string $mode, int $options, string $opened_path)

Opens file or URL.

from  PhpStreamWrapperInterface
string|false
stream_read(int $count)

Read from stream.

from  PhpStreamWrapperInterface
bool
stream_seek(int $offset, int $whence = SEEK_SET)

Seeks to specific location in a stream.

from  PhpStreamWrapperInterface
bool
stream_set_option(int $option, int $arg1, int $arg2)

Change stream options.

from  PhpStreamWrapperInterface
array|false
stream_stat()

Retrieve information about a file resource.

from  PhpStreamWrapperInterface
int
stream_tell()

Retrieve the current position of a stream.

from  PhpStreamWrapperInterface
bool
stream_truncate(int $new_size)

Truncate stream.

from  PhpStreamWrapperInterface
int
stream_write(string $data)

Write to stream.

from  PhpStreamWrapperInterface
bool
unlink(string $path)

Delete a file.

from  PhpStreamWrapperInterface
array|false
url_stat(string $path, int $flags)

Retrieve information about a file.

from  PhpStreamWrapperInterface
static int
getType()

Returns the type of stream wrapper.

string
getName()

Returns the name of the stream wrapper for use in the UI.

string
getDescription()

Returns the description of the stream wrapper for use in the UI.

setUri(string $uri)

Sets the absolute stream resource URI.

string
getUri()

Returns the stream resource URI.

string
getExternalUrl()

Returns a web accessible URL for the resource.

string
realpath()

Returns canonical, absolute path of the resource.

string
dirname(string $uri = NULL)

Gets the name of the directory from a given path.

Details

in PhpStreamWrapperInterface at line 25
bool dir_closedir()

Close directory handle.

This method is called in response to closedir(). Any resources which were locked, or allocated, during opening and use of the directory stream should be released.

Return Value

bool

Returns TRUE on success or FALSE on failure.

See also

closedir()
http://php.net/manual/en/streamwrapper.dir-closedir.php

in PhpStreamWrapperInterface at line 43
bool dir_opendir(string $path, int $options)

Open directory handle.

This method is called in response to opendir().

Parameters

string $path

Specifies the URL that was passed to opendir().
int $options

Whether or not to enforce safe_mode (0x04).

Return Value

bool

Returns TRUE on success or FALSE on failure.

See also

opendir()
http://php.net/manual/en/streamwrapper.dir-opendir.php

in PhpStreamWrapperInterface at line 57
string|false dir_readdir()

Read entry from directory handle.

This method is called in response to readdir().

Return Value

string|false

Should return string representing the next filename, or FALSE if there is no next file. Note, the return value will be casted to string.

See also

readdir()
http://php.net/manual/en/streamwrapper.dir-readdir.php

in PhpStreamWrapperInterface at line 74
bool dir_rewinddir()

Rewind directory handle.

This method is called in response to rewinddir(). Should reset the output generated by PhpStreamWrapperInterface::dir_readdir. The next call to PhpStreamWrapperInterface::dir_readdir should return the first entry in the location returned by PhpStreamWrapperInterface::dir_opendir.

Return Value

bool

Returns TRUE on success or FALSE on failure.

See also

rewinddir()
PhpStreamWrapperInterface::dir_readdir
http://php.net/manual/en/streamwrapper.dir-rewinddir.php

in PhpStreamWrapperInterface at line 101
bool mkdir(string $path, int $mode, int $options)

Create a directory.

This method is called in response to mkdir()

Note, in order for the appropriate error message to be returned this method should not be defined if the wrapper does not support creating directories.

Note, the streamWrapper::$context property is updated if a valid context is passed to the caller function.

Parameters

string $path

Directory which should be created.
int $mode

The value passed to mkdir().
int $options

A bitwise mask of values, such as STREAM_MKDIR_RECURSIVE.

Return Value

bool

Returns TRUE on success or FALSE on failure.

See also

mkdir()
PhpStreamWrapperInterface::rmdir
http://php.net/manual/en/streamwrapper.mkdir.php

in PhpStreamWrapperInterface at line 126
bool rename(string $path_from, string $path_to)

Renames a file or directory.

This method is called in response to rename(). Should attempt to rename $path_from to $path_to.

Note, in order for the appropriate error message to be returned this method should not be defined if the wrapper does not support renaming files.

Note, the streamWrapper::$context property is updated if a valid context is passed to the caller function.

Parameters

string $path_from

The URL to the current file.
string $path_to

The URL which the $path_from should be renamed to.

Return Value

bool

Returns TRUE on success or FALSE on failure.

See also

rename()
http://php.net/manual/en/streamwrapper.rename.php

in PhpStreamWrapperInterface at line 152
bool rmdir(string $path, int $options)

Removes a directory.

This method is called in response to rmdir().

Note, in order for the appropriate error message to be returned this method should not be defined if the wrapper does not support removing directories.

Note, the streamWrapper::$context property is updated if a valid context is passed to the caller function.

Parameters

string $path

The directory URL which should be removed.
int $options

A bitwise mask of values, such as STREAM_MKDIR_RECURSIVE.

Return Value

bool

Returns TRUE on success or FALSE on failure.

See also

rmdir()
PhpStreamWrapperInterface::mkdir
PhpStreamWrapperInterface::unlink
http://php.net/manual/en/streamwrapper.rmdir.php

in PhpStreamWrapperInterface at line 171
resource|false stream_cast(int $cast_as)

Retrieve the underlying stream resource.

This method is called in response to stream_select().

Parameters

int $cast_as

Can be STREAM_CAST_FOR_SELECT when stream_select() is calling stream_cast() or STREAM_CAST_AS_STREAM when stream_cast() is called for other uses.

Return Value

resource|false

The underlying stream resource or FALSE if stream_select() is not supported.

See also

stream_select()
http://php.net/manual/streamwrapper.stream-cast.php

in PhpStreamWrapperInterface at line 183
stream_close()

Closes stream.

This method is called in response to fclose(). All resources that were locked, or allocated, by the wrapper should be released.

See also

fclose()
PhpStreamWrapperInterface::dir_closedir
http://php.net/manual/en/streamwrapper.stream-close.php

in PhpStreamWrapperInterface at line 204
bool stream_eof()

Tests for end-of-file on a file pointer.

This method is called in response to feof().

Warning, when reading the whole file (for example, with file_get_contents()), PHP will call PhpStreamWrapperInterface::stream_read() followed by PhpStreamWrapperInterface::stream_eof() in a loop but as long as PhpStreamWrapperInterface::stream_read() returns a non-empty string, the return value of PhpStreamWrapperInterface::stream_eof() is ignored.

Return Value

bool

Should return TRUE if the read/write position is at the end of the stream and if no more data is available to be read, or FALSE otherwise.

See also

feof()
http://php.net/manual/en/streamwrapper.stream-eof.php

in PhpStreamWrapperInterface at line 223
bool stream_flush()

Flushes the output.

This method is called in response to fflush() and when the stream is being closed while any un-flushed data has been written to it before. If you have cached data in your stream but not yet stored it into the underlying storage, you should do so now.

Note, if not implemented, FALSE is assumed as the return value.

Return Value

bool

Should return TRUE if the cached data was successfully stored (or if there was no data to store), or FALSE if the data could not be stored.

See also

fflush()
http://php.net/manual/en/streamwrapper.stream-flush.php

in PhpStreamWrapperInterface at line 247
bool stream_lock(int $operation)

Advisory file locking.

This method is called in response to flock(), when file_put_contents() (when flags contains LOCK_EX), stream_set_blocking() and when closing the stream (LOCK_UN).

Parameters

int $operation

One of:

  • LOCK_SH: To acquire a shared lock (reader).
  • LOCK_EX: To acquire an exclusive lock (writer).
  • LOCK_UN: To release a lock (shared or exclusive).
  • LOCK_NB: If you don't want flock() to block while locking. This operation is not supported on Windows.

Return Value

bool

Returns TRUE on success or FALSE on failure.

See also

flock()
stream_set_blocking()
http://php.net/manual/en/streamwrapper.stream-lock.php

in PhpStreamWrapperInterface at line 279
bool stream_metadata(string $path, int $option, mixed $value)

Sets metadata on the stream.

Parameters

string $path

A string containing the URI to the file to set metadata on.
int $option

One of:

  • STREAM_META_TOUCH: The method was called in response to touch().
  • STREAM_META_OWNER_NAME: The method was called in response to chown() with string parameter.
  • STREAM_META_OWNER: The method was called in response to chown().
  • STREAM_META_GROUP_NAME: The method was called in response to chgrp().
  • STREAM_META_GROUP: The method was called in response to chgrp().
  • STREAM_META_ACCESS: The method was called in response to chmod().
mixed $value

If option is:

  • STREAM_META_TOUCH: Array consisting of two arguments of the touch() function.
  • STREAM_META_OWNER_NAME or STREAM_META_GROUP_NAME: The name of the owner user/group as string.
  • STREAM_META_OWNER or STREAM_META_GROUP: The value of the owner user/group as integer.
  • STREAM_META_ACCESS: The argument of the chmod() as integer.

Return Value

bool

Returns TRUE on success or FALSE on failure. If $option is not implemented, FALSE should be returned.

See also

http://php.net/manual/streamwrapper.stream-metadata.php

in PhpStreamWrapperInterface at line 318
bool stream_open(string $path, string $mode, int $options, string $opened_path)

Opens file or URL.

This method is called immediately after the wrapper is initialized (e.g. by fopen() and file_get_contents()).

Note the streamWrapper::$context property is updated if a valid context is passed to the caller function.

Parameters

string $path

Specifies the URL that was passed to the original function. Note that the URL can be broken apart with parse_url(). Note that only URLs delimited by "://" are supported. ":" and ":/" while technically valid URLs, are not.
string $mode

The mode used to open the file, as detailed for fopen(). Note, remember to check if the mode is valid for the path requested.
int $options

Holds additional flags set by the streams API. It can hold one or more of the following values ORed together:

  • STREAM_USE_PATH: If path is relative, search for the resource using the include_path.
  • STREAM_REPORT_ERRORS: If this flag is set, you are responsible for raising errors using trigger_error() during opening of the stream. If this flag is not set, you should not raise any errors.
string $opened_path

If the path is opened successfully, and STREAM_USE_PATH is set in options, opened_path should be set to the full path of the file/resource that was actually opened.

Return Value

bool

Returns TRUE on success or FALSE on failure.

See also

fopen()
parse_url()
http://php.net/manual/en/streamwrapper.stream-open.php

in PhpStreamWrapperInterface at line 350
string|false stream_read(int $count)

Read from stream.

This method is called in response to fread() and fgets().

Note, remember to update the read/write position of the stream (by the number of bytes that were successfully read).

Note, PhpStreamWrapperInterface::stream_eof() is called directly after calling PhpStreamWrapperInterface::stream_read() to check if EOF has been reached. If not implemented, EOF is assumed.

Warning, when reading the whole file (e.g., with file_get_contents()), PHP will call PhpStreamWrapperInterface::stream_read() followed by PhpStreamWrapperInterface::stream_eof() in a loop but as long as PhpStreamWrapperInterface::stream_read() returns a non-empty string, the return value of PhpStreamWrapperInterface::stream_eof() is ignored.

Parameters

int $count

How many bytes of data from the current position should be returned.

Return Value

string|false

If there are less than $count bytes available, return as many as are available. If no more data is available, return either FALSE or an empty string.

See also

fread()
fgets()
http://php.net/manual/en/streamwrapper.stream-read.php

in PhpStreamWrapperInterface at line 374
bool stream_seek(int $offset, int $whence = SEEK_SET)

Seeks to specific location in a stream.

This method is called in response to fseek().

The read/write position of the stream should be updated according to the offset and whence.

Parameters

int $offset

The byte offset to seek to.
int $whence

Possible values:

  • SEEK_SET: Set position equal to offset bytes.
  • SEEK_CUR: Set position to current location plus offset.
  • SEEK_END: Set position to end-of-file plus offset. Defaults to SEEK_SET.

Return Value

bool

TRUE if the position was updated, FALSE otherwise.

See also

http://php.net/manual/streamwrapper.stream-seek.php

in PhpStreamWrapperInterface at line 407
bool stream_set_option(int $option, int $arg1, int $arg2)

Change stream options.

This method is called to set options on the stream.

Parameters

int $option

One of:

  • STREAM_OPTION_BLOCKING: The method was called in response to stream_set_blocking().
  • STREAM_OPTION_READ_TIMEOUT: The method was called in response to stream_set_timeout().
  • STREAM_OPTION_WRITE_BUFFER: The method was called in response to stream_set_write_buffer().
int $arg1

If option is:

  • STREAM_OPTION_BLOCKING: The requested blocking mode:
    • 1 means blocking.
    • 0 means not blocking.
  • STREAM_OPTION_READ_TIMEOUT: The timeout in seconds.
  • STREAM_OPTION_WRITE_BUFFER: The buffer mode, STREAM_BUFFER_NONE or STREAM_BUFFER_FULL.
int $arg2

If option is:

  • STREAM_OPTION_BLOCKING: This option is not set.
  • STREAM_OPTION_READ_TIMEOUT: The timeout in microseconds.
  • STREAM_OPTION_WRITE_BUFFER: The requested buffer size.

Return Value

bool

TRUE on success, FALSE otherwise. If $option is not implemented, FALSE should be returned.

in PhpStreamWrapperInterface at line 421
array|false stream_stat()

Retrieve information about a file resource.

This method is called in response to fstat().

Return Value

array|false

See stat().

See also

stat()
PhpStreamWrapperInterface::url_stat
http://php.net/manual/en/streamwrapper.stream-stat.php

in PhpStreamWrapperInterface at line 435
int stream_tell()

Retrieve the current position of a stream.

This method is called in response to fseek() to determine the current position.

Return Value

int

Should return the current position of the stream.

See also

PhpStreamWrapperInterface::stream_tell
http://php.net/manual/en/streamwrapper.stream-tell.php

in PhpStreamWrapperInterface at line 451
bool stream_truncate(int $new_size)

Truncate stream.

Will respond to truncation; e.g., through ftruncate().

Parameters

int $new_size

The new size.

Return Value

bool

TRUE on success, FALSE otherwise.

See also

ftruncate()
http://php.net/manual/en/streamwrapper.stream-truncate.php

in PhpStreamWrapperInterface at line 471
int stream_write(string $data)

Write to stream.

This method is called in response to fwrite(). Remember to update the current position of the stream by number of bytes that were successfully written.

Parameters

string $data

Should be stored into the underlying stream. If there is not enough room in the underlying stream, store as much as possible.

Return Value

int

Should return the number of bytes that were successfully stored, or 0 if none could be stored.

See also

fwrite()
http://php.net/manual/en/streamwrapper.stream-write.php

Delete a file.

This method is called in response to unlink().

Note, in order for the appropriate error message to be returned this method should not be defined if the wrapper does not support removing files.

Note, the streamWrapper::$context property is updated if a valid context is passed to the caller function.

Parameters

string $path

The file URL which should be deleted.

Return Value

bool

Returns TRUE on success or FALSE on failure.

See also

unlink()
PhpStreamWrapperInterface::rmdir
http://php.net/manual/en/streamwrapper.unlink.php

in PhpStreamWrapperInterface at line 528
array|false url_stat(string $path, int $flags)

Retrieve information about a file.

This method is called in response to all stat() related functions.

Note, the streamWrapper::$context property is updated if a valid context is passed to the caller function.

Parameters

string $path

The file path or URL to stat. Note that in the case of a URL, it must be a "://" delimited URL. Other URL forms are not supported.
int $flags

Holds additional flags set by the streams API. It can hold one or more of the following values ORed together:

  • STREAM_URL_STAT_LINK: For resources with the ability to link to other resource (such as an HTTP Location: forward, or a filesystem symlink). This flag specified that only information about the link itself should be returned, not the resource pointed to by the link. This flag is set in response to calls to lstat(), is_link(), or filetype().
  • STREAM_URL_STAT_QUIET: If this flag is set, your wrapper should not raise any errors. If this flag is not set, you are responsible for reporting errors using the trigger_error() function during stating of the path.

Return Value

array|false

Should return the same as stat() does. Unknown or unavailable values should be set to a rational value (usually 0).

See also

stat()
PhpStreamWrapperInterface::stream_stat
http://php.net/manual/en/streamwrapper.url-stat.php

at line 103
static int getType()

Returns the type of stream wrapper.

Return Value

int

at line 111
string getName()

Returns the name of the stream wrapper for use in the UI.

Return Value

string

The stream wrapper name.

at line 119
string getDescription()

Returns the description of the stream wrapper for use in the UI.

Return Value

string

The stream wrapper description.

at line 130
setUri(string $uri)

Sets the absolute stream resource URI.

This allows you to set the URI. Generally is only called by the factory method.

Parameters

string $uri

A string containing the URI that should be used for this instance.

at line 138
string getUri()

Returns the stream resource URI.

Return Value

string

Returns the current URI of the instance.

at line 151
string getExternalUrl()

Returns a web accessible URL for the resource.

This function should return a URL that can be embedded in a web page and accessed from a browser. For example, the external URL of "youtube://xIpLd0WQKCY" might be "http://www.youtube.com/watch?v=xIpLd0WQKCY".

Return Value

string

Returns a string containing a web accessible URL for the resource.

at line 165
string realpath()

Returns canonical, absolute path of the resource.

Implementation placeholder. PHP's realpath() does not support stream wrappers. We provide this as a default so that individual wrappers may implement their own solutions.

Return Value

string

Returns a string with absolute pathname on success (implemented by core wrappers), or FALSE on failure or if the registered wrapper does not provide an implementation.

at line 182
string dirname(string $uri = NULL)

Gets the name of the directory from a given path.

This method is usually accessed through \Drupal\Core\File\FileSystemInterface::dirname(), which wraps around the normal PHP dirname() function, which does not support stream wrappers.

Parameters

string $uri

An optional URI.

Return Value

string

A string containing the directory name, or FALSE if not applicable.

See also

FileSystemInterface::dirname