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

PhpStreamWrapperInterface

interface PhpStreamWrapperInterface (View source)

Defines a generic PHP stream wrapper interface.

Methods

bool
dir_closedir()

Close directory handle.

bool
dir_opendir(string $path, int $options)

Open directory handle.

string|false
dir_readdir()

Read entry from directory handle.

bool
dir_rewinddir()

Rewind directory handle.

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

Create a directory.

bool
rename(string $path_from, string $path_to)

Renames a file or directory.

bool
rmdir(string $path, int $options)

Removes a directory.

resource|false
stream_cast(int $cast_as)

Retrieve the underlying stream resource.

stream_close()

Closes stream.

bool
stream_eof()

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

bool
stream_flush()

Flushes the output.

bool
stream_lock(int $operation)

Advisory file locking.

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

Sets metadata on the stream.

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

Opens file or URL.

string|false
stream_read(int $count)

Read from stream.

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

Seeks to specific location in a stream.

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

Change stream options.

array|false
stream_stat()

Retrieve information about a file resource.

int
stream_tell()

Retrieve the current position of a stream.

bool
stream_truncate(int $new_size)

Truncate stream.

int
stream_write(string $data)

Write to stream.

bool
unlink(string $path)

Delete a file.

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

Retrieve information about a file.

Details

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

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

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

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

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

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