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

LocalReadOnlyStream

abstract class LocalReadOnlyStream extends LocalStream (View source)

Defines a read-only Drupal stream wrapper base class for local files.

This class extends the complete stream wrapper implementation in LocalStream. 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\LocalReadOnlyStream implementations need to implement at least the getDirectoryPath() and getExternalUrl() methods.

Properties

resource $context

Stream context resource.

 from  LocalStream
resource $handle

A generic resource handle.

 from  LocalStream
protected string $uri

Instance URI (stream).

 from  LocalStream

Methods

static int
getType()

Returns the type of stream wrapper.

string
getDirectoryPath()

Gets the path that the wrapper is responsible for.

from  LocalStream
setUri(string $uri)

Sets the absolute stream resource URI.

from  LocalStream
string
getUri()

Returns the stream resource URI.

from  LocalStream
string|bool
getTarget(string $uri = NULL)

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

from  LocalStream
string
realpath()

Returns canonical, absolute path of the resource.

from  LocalStream
string|bool
getLocalPath(string $uri = NULL)

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

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

Opens file or URL.

bool
stream_lock(int $operation)

Support for flock().

string|false
stream_read(int $count)

Read from stream.

from  LocalStream
int
stream_write(string $data)

Support for fwrite(), file_put_contents() etc.

bool
stream_eof()

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

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

Seeks to specific location in a stream.

from  LocalStream
bool
stream_flush()

Support for fflush().

int
stream_tell()

Retrieve the current position of a stream.

from  LocalStream
array|false
stream_stat()

Retrieve information about a file resource.

from  LocalStream
stream_close()

Closes stream.

from  LocalStream
resource|false
stream_cast(int $cast_as)

Retrieve the underlying stream resource.

from  LocalStream
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.

from  LocalStream
bool
stream_truncate(int $new_size)

Truncate stream.

bool
unlink($uri)

Support for unlink().

bool
rename($from_uri, $to_uri)

Support for rename().

string
dirname(string $uri = NULL)

Gets the name of the directory from a given path.

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

Support for mkdir().

bool
rmdir($uri, int $options)

Support for rmdir().

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

Retrieve information about a file.

from  LocalStream
bool
dir_opendir($uri, int $options)

Open directory handle.

from  LocalStream
string|false
dir_readdir()

Read entry from directory handle.

from  LocalStream
bool
dir_rewinddir()

Rewind directory handle.

from  LocalStream
bool
dir_closedir()

Close directory handle.

from  LocalStream

Details

at line 21
static int getType()

Returns the type of stream wrapper.

Return Value

int

in LocalStream at line 55
abstract string getDirectoryPath()

Gets the path that the wrapper is responsible for.

Review this method name in D8 per https://www.drupal.org/node/701358.

Return Value

string

String specifying the path.

in LocalStream at line 60
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.

in LocalStream at line 67
string getUri()

Returns the stream resource URI.

Return Value

string

Returns the current URI of the instance.

in LocalStream at line 87
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.

in LocalStream at line 101
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.

in LocalStream at line 120
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 28
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 59
bool stream_lock(int $operation)

Support for flock().

An exclusive lock attempt will be rejected, as this is a read-only stream wrapper.

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

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

in LocalStream at line 181
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 85
int stream_write(string $data)

Support for fwrite(), file_put_contents() etc.

Data will not be written as this is a read-only stream wrapper.

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

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

in LocalStream at line 195
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.

in LocalStream at line 202
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 102
bool stream_flush()

Support for fflush().

Nothing will be output to the file, as this is a read-only stream wrapper. However as stream_flush is called during stream_close we should not trigger an error.

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

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

in LocalStream at line 218
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.

in LocalStream at line 225
array|false stream_stat()

Retrieve information about a file resource.

This method is called in response to fstat().

Return Value

array|false

See stat().

in LocalStream at line 232
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.

in LocalStream at line 239
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 111
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.

in LocalStream at line 289
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 119
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.

Support for unlink().

The file will not be deleted from the stream as this is a read-only stream wrapper.

Parameters

$uri

Return Value

bool

Returns TRUE on success or FALSE on failure.

See also

http://php.net/manual/streamwrapper.unlink.php

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

Support for rename().

The file will not be renamed as this is a read-only stream wrapper.

Parameters

$from_uri
$to_uri

Return Value

bool

Returns TRUE on success or FALSE on failure.

See also

http://php.net/manual/streamwrapper.rename.php

in LocalStream at line 319
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 181
bool mkdir($uri, int $mode, int $options)

Support for mkdir().

Directory will never be created as this is a read-only stream wrapper.

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.

See also

http://php.net/manual/streamwrapper.mkdir.php

at line 201
bool rmdir($uri, int $options)

Support for rmdir().

Directory will never be deleted as this is a read-only stream wrapper.

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.

See also

http://php.net/manual/streamwrapper.rmdir.php

in LocalStream at line 373
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).

in LocalStream at line 389
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.

in LocalStream at line 399
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.

in LocalStream at line 406
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.

in LocalStream at line 417
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.