1. class
  2. Drupal
  3. \
  4. Core
  5. \
  6. StreamWrapper
  7. \
  8. LocalStream

LocalStream

abstract class LocalStream implements StreamWrapperInterface (View source)

Defines a Drupal stream wrapper base class for local files.

This class provides a complete stream wrapper implementation. URIs such as "public://example.txt" are expanded to a normal filesystem path such as "sites/default/files/example.txt" and then PHP filesystem functions are invoked.

Drupal\Core\StreamWrapper\LocalStream implementations need to implement at least the getDirectoryPath() and getExternalUrl() methods.

Properties

resource $context

Stream context resource.
resource $handle

A generic resource handle.
protected string $uri

Instance URI (stream).

Methods

static int
getType()

Returns the type of stream wrapper.

string
getDirectoryPath()

Gets the path that the wrapper is responsible for.

setUri(string $uri)

Sets the absolute stream resource URI.

string
getUri()

Returns the stream resource URI.

string|bool
getTarget(string $uri = NULL)

Returns the local writable target of the resource within the stream.

string
realpath()

Returns canonical, absolute path of the resource.

string|bool
getLocalPath(string $uri = NULL)

Returns the canonical absolute path of the URI, if possible.

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

Opens file or URL.

bool
stream_lock(int $operation)

Advisory file locking.

string|false
stream_read(int $count)

Read from stream.

int
stream_write(string $data)

Write to stream.

bool
stream_eof()

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

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

Seeks to specific location in a stream.

bool
stream_flush()

Flushes the output.

int
stream_tell()

Retrieve the current position of a stream.

array|false
stream_stat()

Retrieve information about a file resource.

stream_close()

Closes stream.

resource|false
stream_cast(int $cast_as)

Retrieve the underlying stream resource.

bool
stream_metadata($uri, int $option, mixed $value)

Sets metadata on the stream.

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

Change stream options.

bool
stream_truncate(int $new_size)

Truncate stream.

bool
unlink($uri)

Delete a file.

bool
rename($from_uri, $to_uri)

Renames a file or directory.

string
dirname(string $uri = NULL)

Gets the name of the directory from a given path.

bool
mkdir($uri, int $mode, int $options)

Create a directory.

bool
rmdir($uri, int $options)

Removes a directory.

array|false
url_stat($uri, int $flags)

Retrieve information about a file.

bool
dir_opendir($uri, int $options)

Open directory handle.

string|false
dir_readdir()

Read entry from directory handle.

bool
dir_rewinddir()

Rewind directory handle.

bool
dir_closedir()

Close directory handle.

Details

at line 43
static int getType()

Returns the type of stream wrapper.

Return Value

int

at line 53
abstract string getDirectoryPath()

Gets the path that the wrapper is responsible for.

Return Value

string

String specifying the path.

at line 58
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 65
string getUri()

Returns the stream resource URI.

Return Value

string

Returns the current URI of the instance.

at line 85
protected string|bool getTarget(string $uri = NULL)

Returns the local writable target of the resource within the stream.

This function should be used in place of calls to realpath() or similar functions when attempting to determine the location of a file. While functions like realpath() may return the location of a read-only file, this method may return a URI or path suitable for writing that is completely separate from the URI used for reading.

Parameters

string $uri

Optional URI.

Return Value

string|bool

Returns a string representing a location suitable for writing of a file, or FALSE if unable to write to the file such as with read-only streams.

at line 99
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 118
protected string|bool getLocalPath(string $uri = NULL)

Returns the canonical absolute path of the URI, if possible.

Parameters

string $uri

(optional) The stream wrapper URI to be converted to a canonical absolute path. This may point to a directory or another type of file.

Return Value

string|bool

If $uri is not set, returns the canonical absolute path of the URI previously set by the Drupal\Core\StreamWrapper\StreamWrapperInterface::setUri() function. If $uri is set and valid for this class, returns its canonical absolute path, as determined by the realpath() function. If $uri is set but not valid, returns FALSE.

at line 147
bool stream_open($uri, 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

$uri
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.

at line 168
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.

at line 179
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.

at line 186
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.

at line 193
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.

at line 200
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.

at line 209
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.

at line 216
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.

at line 223
array|false stream_stat()

Retrieve information about a file resource.

This method is called in response to fstat().

Return Value

array|false

See stat().

at line 230
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.

at line 237
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.

at line 244
bool stream_metadata($uri, int $option, mixed $value)

Sets metadata on the stream.

Parameters

$uri
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.

at line 287
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 295
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.

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

$uri

Return Value

bool

Returns TRUE on success or FALSE on failure.

at line 310
bool rename($from_uri, $to_uri)

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

$from_uri
$to_uri

Return Value

bool

Returns TRUE on success or FALSE on failure.

at line 317
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.

at line 332
bool mkdir($uri, 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

$uri
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.

at line 356
bool rmdir($uri, 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

$uri
int $options

A bitwise mask of values, such as STREAM_MKDIR_RECURSIVE.

Return Value

bool

Returns TRUE on success or FALSE on failure.

at line 371
array|false url_stat($uri, 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

$uri
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).

at line 387
bool dir_opendir($uri, int $options)

Open directory handle.

This method is called in response to opendir().

Parameters

$uri
int $options

Whether or not to enforce safe_mode (0x04).

Return Value

bool

Returns TRUE on success or FALSE on failure.

at line 397
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.

at line 404
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.

at line 415
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.