interface StreamWrapperInterface (View source)

A stream wrapper interface. Modeled after the PHP streamWrapper class prototype. Check http://php.net/streamwrapper for details on that.

We divert from the PHP prototype in the following:

  • better method names
  • methods that should not be implemented in the PHP prototype when not being supported (like mkdir) must throw a \BadMethodCallException instead.

Methods

static string
getScheme()

Returns the scheme ("protocol") this wrapper handles.

bool
closeDirectory()

Close directory handle.

bool
openDirectory(string $path, int $options)

Open directory handle.

string
readDirectory()

Read entry from directory handle.

bool
rewindDirectory()

Rewind directory handle.

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

Create a directory.

bool
removeDirectory(string $path, int $options)

Removes a directory.

bool
rename(string $source, string $target)

Renames a file or directory.

resource
cast(int $castType)

Retrieve the underlying resource.

void
close()

Close an resource.

bool
isAtEof()

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

bool
flush()

Flushes the output.

bool
lock(int $operation)

Advisory file locking.

bool
unlock()

Advisory file locking.

bool
open(string $path, string $mode, int $options, string $openedPathAndFilename)

Opens file or URL.

string
read(int $count)

Read from stream.

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

Seeks to specific location in a stream.

bool
setOption(int $option, int $argument1, int $argument2)

Change stream options.

int
tell()

Retrieve the current position of a stream.

int
write(string $data)

Write to stream.

bool
unlink(string $path)

Delete a file.

array
resourceStat()

Retrieve information about a file resource.

array
pathStat(string $path, int $flags)

Retrieve information about a file.

Details

static string getScheme()

Returns the scheme ("protocol") this wrapper handles.

Return Value

string

bool closeDirectory()

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

true on success or false on failure.

bool openDirectory(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

true on success or false on failure.

string readDirectory()

Read entry from directory handle.

This method is called in response to readdir().

Return Value

string

Should return string representing the next filename, or false if there is no next file.

bool rewindDirectory()

Rewind directory handle.

This method is called in response to rewinddir().

Should reset the output generated by dir_readdir(). I.e.: The next call to dir_readdir() should return the first entry in the location returned by dir_opendir().

Return Value

bool

true on success or false on failure.

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

Create a directory.

This method is called in response to mkdir().

Note: If the wrapper does not support creating directories it must throw a \BadMethodCallException.

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

true on success or false on failure.

bool removeDirectory(string $path, int $options)

Removes a directory.

This method is called in response to rmdir().

Note: If the wrapper does not support creating directories it must throw a \BadMethodCallException.

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

true on success or false on failure.

bool rename(string $source, string $target)

Renames a file or directory.

This method is called in response to rename().

Should attempt to rename path_from to path_to.

Parameters

string $source

The URL to the current file.

string $target

The URL which the path_from should be renamed to.

Return Value

bool

true on success or false on failure.

resource cast(int $castType)

Retrieve the underlying resource.

This method is called in response to stream_select().

Parameters

int $castType

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

Should return the underlying stream resource used by the wrapper, or false.

void close()

Close an resource.

This method is called in response to fclose().

All resources that were locked, or allocated, by the wrapper should be released.

Return Value

void

bool isAtEof()

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

This method is called in response to feof().

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.

bool flush()

Flushes the output.

This method is called in response to fflush().

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.

bool 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().

$operation is one of the following: LOCK_SH to acquire a shared lock (reader). LOCK_EX to acquire an exclusive lock (writer). LOCK_NB if you don't want flock() to block while locking.

Parameters

int $operation

One of the LOCK_* constants

Return Value

bool

true on success or false on failure.

bool unlock()

Advisory file locking.

This method is called when closing the stream (LOCK_UN).

Return Value

bool

true on success or false on failure.

bool open(string $path, string $mode, int $options, string $openedPathAndFilename)

Opens file or URL.

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

$options can hold one of the following values OR'd 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.

Parameters

string $path

Specifies the URL that was passed to the original function.

string $mode

The mode used to open the file, as detailed for fopen().

int $options

Holds additional flags set by the streams API.

string $openedPathAndFilename

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

true on success or false on failure.

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

Parameters

int $count

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

Return Value

string

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.

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

$whence can one of: 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.

Parameters

int $offset

The stream offset to seek to.

int $whence

Return Value

bool

true on success or false on failure.

bool setOption(int $option, int $argument1, int $argument2)

Change stream options.

This method is called to set options on the stream.

$option can be 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())

If $option is ... then $arg1 is set to: STREAM_OPTION_BLOCKING: requested blocking mode (1 meaning block 0 not blocking). STREAM_OPTION_READ_TIMEOUT: the timeout in seconds. STREAM_OPTION_WRITE_BUFFER: buffer mode (STREAM_BUFFER_NONE or STREAM_BUFFER_FULL).

If $option is ... then $arg2 is set to: STREAM_OPTION_BLOCKING: This option is not set. STREAM_OPTION_READ_TIMEOUT: the timeout in microseconds. STREAM_OPTION_WRITE_BUFFER: the requested buffer size.

Parameters

int $option
int $argument1
int $argument2

Return Value

bool

true on success or false on failure. If option is not implemented, false should be returned.

int tell()

Retrieve the current position of a stream.

This method is called in response to ftell().

Return Value

int

Should return the current position of the stream.

int write(string $data)

Write to stream.

This method is called in response to fwrite().

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

Note: 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.

Return Value

int

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

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.

Parameters

string $path

The file URL which should be deleted.

Return Value

bool

true on success or false on failure.

array resourceStat()

Retrieve information about a file resource.

This method is called in response to fstat().

Return Value

array

See http://php.net/stat

array pathStat(string $path, int $flags)

Retrieve information about a file.

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

$flags can hold one or more of the following values OR'd 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.

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.

Return Value

array

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