class ReadOnlyStream

Same name in other branches
  1. 9 core/lib/Drupal/Core/StreamWrapper/ReadOnlyStream.php \Drupal\Core\StreamWrapper\ReadOnlyStream
  2. 8.9.x core/lib/Drupal/Core/StreamWrapper/ReadOnlyStream.php \Drupal\Core\StreamWrapper\ReadOnlyStream
  3. 11.x core/lib/Drupal/Core/StreamWrapper/ReadOnlyStream.php \Drupal\Core\StreamWrapper\ReadOnlyStream

Defines a read-only Drupal stream wrapper base class.

This class provides a minimal-read only stream wrapper implementation. Specifically, it only implements the writing classes and read classes where we need to restrict 'write-capable' arguments.

Drupal\Core\StreamWrapper\ReadOnlyStream implementations need to implement all the read-related classes.

Hierarchy

Expanded class hierarchy of ReadOnlyStream

1 file declares its use of ReadOnlyStream
DummyExternalReadOnlyWrapper.php in core/modules/file/tests/file_test/src/StreamWrapper/DummyExternalReadOnlyWrapper.php

File

core/lib/Drupal/Core/StreamWrapper/ReadOnlyStream.php, line 15

Namespace

Drupal\Core\StreamWrapper
View source
abstract class ReadOnlyStream implements StreamWrapperInterface {
    
    /**
     * Stream context resource.
     *
     * @var resource
     */
    public $context;
    
    /**
     * A generic resource handle.
     *
     * @var resource
     */
    public $handle = NULL;
    
    /**
     * Instance URI (stream).
     *
     * A stream is referenced as "scheme://target".
     *
     * @var string
     */
    protected $uri;
    
    /**
     * {@inheritdoc}
     */
    public function setUri($uri) {
        $this->uri = $uri;
    }
    
    /**
     * {@inheritdoc}
     */
    public function getUri() {
        return $this->uri;
    }
    
    /**
     * Support for fopen(), file_get_contents(), etc.
     *
     * Any write modes will be rejected, as this is a read-only stream wrapper.
     *
     * @param string $uri
     *   A string containing the URI to the file to open.
     * @param int $mode
     *   The file mode, only strict readonly modes are supported.
     * @param int $options
     *   A bit mask of STREAM_USE_PATH and STREAM_REPORT_ERRORS.
     * @param string $opened_path
     *   A string containing the path actually opened.
     *
     * @return bool
     *   TRUE if $mode denotes a readonly mode and the file was opened
     *   successfully, FALSE otherwise.
     *
     * @throws \BadMethodCallException
     *   When ::getLocalPath() is not implemented in the concrete driver class.
     *
     * @see http://php.net/manual/streamwrapper.stream-open.php
     */
    public function stream_open($uri, $mode, $options, &$opened_path) {
        if (!in_array($mode, [
            'r',
            'rb',
            'rt',
        ])) {
            if ($options & STREAM_REPORT_ERRORS) {
                trigger_error('stream_open() write modes not supported for read-only stream wrappers', E_USER_WARNING);
            }
            return FALSE;
        }
        $this->uri = $uri;
        $path = $this->getLocalPath();
        $this->handle = $options & STREAM_REPORT_ERRORS ? fopen($path, $mode) : @fopen($path, $mode);
        if ($this->handle !== FALSE && $options & STREAM_USE_PATH) {
            $opened_path = $path;
        }
        return (bool) $this->handle;
    }
    
    /**
     * Returns the canonical absolute path of the URI, if possible.
     *
     * @param 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 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.
     *
     * @throws \BadMethodCallException
     *   If the method is not implemented in the concrete driver class.
     *
     * @todo This method is called by ReadOnlyStream::stream_open on the abstract
     *   class, and therefore should be defined as well on the abstract class to
     *   prevent static analysis errors. In D11, consider changing it to an
     *   abstract method.
     */
    protected function getLocalPath($uri = NULL) {
        throw new \BadMethodCallException(get_class($this) . '::getLocalPath() not implemented.');
    }
    
    /**
     * Support for flock().
     *
     * An exclusive lock attempt will be rejected, as this is a read-only stream
     * wrapper.
     *
     * @param int $operation
     *   One of the following:
     *   - 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 (not
     *     supported on Windows).
     *
     * @return bool
     *   Return FALSE for an exclusive lock (writer), as this is a read-only
     *   stream wrapper.  Return the result of flock() for other valid operations.
     *   Defaults to TRUE if an invalid operation is passed.
     *
     * @see http://php.net/manual/streamwrapper.stream-lock.php
     */
    public function stream_lock($operation) {
        if (in_array($operation, [
            LOCK_EX,
            LOCK_EX | LOCK_NB,
        ])) {
            trigger_error('stream_lock() exclusive lock operations not supported for read-only stream wrappers', E_USER_WARNING);
            return FALSE;
        }
        if (in_array($operation, [
            LOCK_SH,
            LOCK_UN,
            LOCK_SH | LOCK_NB,
        ])) {
            return flock($this->handle, $operation);
        }
        return TRUE;
    }
    
    /**
     * Support for fwrite(), file_put_contents() etc.
     *
     * Data will not be written as this is a read-only stream wrapper.
     *
     * @param string $data
     *   The string to be written.
     *
     * @return bool
     *   FALSE as data will not be written.
     *
     * @see http://php.net/manual/streamwrapper.stream-write.php
     */
    public function stream_write($data) {
        trigger_error('stream_write() not supported for read-only stream wrappers', E_USER_WARNING);
        return FALSE;
    }
    
    /**
     * 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 bool
     *   FALSE, as no data will be stored.
     *
     * @see http://php.net/manual/streamwrapper.stream-flush.php
     */
    public function stream_flush() {
        return FALSE;
    }
    
    /**
     * {@inheritdoc}
     *
     * Does not change meta data as this is a read-only stream wrapper.
     */
    public function stream_metadata($uri, $option, $value) {
        trigger_error('stream_metadata() not supported for read-only stream wrappers', E_USER_WARNING);
        return FALSE;
    }
    
    /**
     * {@inheritdoc}
     */
    public function stream_truncate($new_size) {
        trigger_error('stream_truncate() not supported for read-only stream wrappers', E_USER_WARNING);
        return FALSE;
    }
    
    /**
     * Support for unlink().
     *
     * The file will not be deleted from the stream as this is a read-only stream
     * wrapper.
     *
     * @param string $uri
     *   A string containing the uri to the resource to delete.
     *
     * @return bool
     *   TRUE so that file_delete() will remove db reference to file. File is not
     *   actually deleted.
     *
     * @see http://php.net/manual/streamwrapper.unlink.php
     */
    public function unlink($uri) {
        trigger_error('unlink() not supported for read-only stream wrappers', E_USER_WARNING);
        return TRUE;
    }
    
    /**
     * Support for rename().
     *
     * This file will not be renamed as this is a read-only stream wrapper.
     *
     * @param string $from_uri
     *   The uri to the file to rename.
     * @param string $to_uri
     *   The new uri for file.
     *
     * @return bool
     *   FALSE as file will never be renamed.
     *
     * @see http://php.net/manual/streamwrapper.rename.php
     */
    public function rename($from_uri, $to_uri) {
        trigger_error('rename() not supported for read-only stream wrappers', E_USER_WARNING);
        return FALSE;
    }
    
    /**
     * Support for mkdir().
     *
     * Directory will never be created as this is a read-only stream wrapper.
     *
     * @param string $uri
     *   A string containing the URI to the directory to create.
     * @param int $mode
     *   Permission flags - see mkdir().
     * @param int $options
     *   A bit mask of STREAM_REPORT_ERRORS and STREAM_MKDIR_RECURSIVE.
     *
     * @return bool
     *   FALSE as directory will never be created.
     *
     * @see http://php.net/manual/streamwrapper.mkdir.php
     */
    public function mkdir($uri, $mode, $options) {
        trigger_error('mkdir() not supported for read-only stream wrappers', E_USER_WARNING);
        return FALSE;
    }
    
    /**
     * Support for rmdir().
     *
     * Directory will never be deleted as this is a read-only stream wrapper.
     *
     * @param string $uri
     *   A string containing the URI to the directory to delete.
     * @param int $options
     *   A bit mask of STREAM_REPORT_ERRORS.
     *
     * @return bool
     *   FALSE as directory will never be deleted.
     *
     * @see http://php.net/manual/streamwrapper.rmdir.php
     */
    public function rmdir($uri, $options) {
        trigger_error('rmdir() not supported for read-only stream wrappers', E_USER_WARNING);
        return FALSE;
    }

}

Members

Title Sort descending Modifiers Object type Summary Overriden Title Overrides
PhpStreamWrapperInterface::dir_closedir public function Close directory handle. 2
PhpStreamWrapperInterface::dir_opendir public function Open directory handle. 2
PhpStreamWrapperInterface::dir_readdir public function Read entry from directory handle. 2
PhpStreamWrapperInterface::dir_rewinddir public function Rewind directory handle. 2
PhpStreamWrapperInterface::stream_cast public function Retrieve the underlying stream resource. 2
PhpStreamWrapperInterface::stream_close public function Closes stream. 2
PhpStreamWrapperInterface::stream_eof public function Tests for end-of-file on a file pointer. 2
PhpStreamWrapperInterface::stream_read public function Read from stream. 2
PhpStreamWrapperInterface::stream_seek public function Seeks to specific location in a stream. 2
PhpStreamWrapperInterface::stream_set_option public function Change stream options. 2
PhpStreamWrapperInterface::stream_stat public function Retrieve information about a file resource. 2
PhpStreamWrapperInterface::stream_tell public function Retrieve the current position of a stream. 2
PhpStreamWrapperInterface::url_stat public function Retrieve information about a file. 2
ReadOnlyStream::$context public property Stream context resource.
ReadOnlyStream::$handle public property A generic resource handle.
ReadOnlyStream::$uri protected property Instance URI (stream).
ReadOnlyStream::getLocalPath protected function Returns the canonical absolute path of the URI, if possible.
ReadOnlyStream::getUri public function Returns the stream resource URI. Overrides StreamWrapperInterface::getUri
ReadOnlyStream::mkdir public function Support for mkdir(). Overrides PhpStreamWrapperInterface::mkdir
ReadOnlyStream::rename public function Support for rename(). Overrides PhpStreamWrapperInterface::rename
ReadOnlyStream::rmdir public function Support for rmdir(). Overrides PhpStreamWrapperInterface::rmdir
ReadOnlyStream::setUri public function Sets the absolute stream resource URI. Overrides StreamWrapperInterface::setUri
ReadOnlyStream::stream_flush public function Support for fflush(). Overrides PhpStreamWrapperInterface::stream_flush
ReadOnlyStream::stream_lock public function Support for flock(). Overrides PhpStreamWrapperInterface::stream_lock
ReadOnlyStream::stream_metadata public function Does not change meta data as this is a read-only stream wrapper. Overrides PhpStreamWrapperInterface::stream_metadata
ReadOnlyStream::stream_open public function Support for fopen(), file_get_contents(), etc. Overrides PhpStreamWrapperInterface::stream_open
ReadOnlyStream::stream_truncate public function Truncate stream. Overrides PhpStreamWrapperInterface::stream_truncate
ReadOnlyStream::stream_write public function Support for fwrite(), file_put_contents() etc. Overrides PhpStreamWrapperInterface::stream_write
ReadOnlyStream::unlink public function Support for unlink(). Overrides PhpStreamWrapperInterface::unlink
StreamWrapperInterface::ALL constant A filter that matches all wrappers.
StreamWrapperInterface::dirname public function Gets the name of the directory from a given path. 2
StreamWrapperInterface::getDescription public function Returns the description of the stream wrapper for use in the UI. 7
StreamWrapperInterface::getExternalUrl public function Returns a web accessible URL for the resource. 7
StreamWrapperInterface::getName public function Returns the name of the stream wrapper for use in the UI. 7
StreamWrapperInterface::getType public static function Returns the type of stream wrapper. 2
StreamWrapperInterface::HIDDEN constant Defines the stream wrapper bit flag for a hidden file.
StreamWrapperInterface::LOCAL constant Refers to a local file system location.
StreamWrapperInterface::LOCAL_HIDDEN constant Hidden, readable and writable using local files.
StreamWrapperInterface::LOCAL_NORMAL constant Visible, readable and writable using local files.
StreamWrapperInterface::NORMAL constant The default 'type' flag.
StreamWrapperInterface::READ constant Wrapper is readable (almost always true).
StreamWrapperInterface::READ_VISIBLE constant Visible and read-only.
StreamWrapperInterface::realpath public function Returns canonical, absolute path of the resource. 2
StreamWrapperInterface::VISIBLE constant Exposed in the UI and potentially web accessible.
StreamWrapperInterface::WRITE constant Wrapper is writable.
StreamWrapperInterface::WRITE_VISIBLE constant Visible, readable and writable.

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.