path: root/core/lib/Drupal/Core/StreamWrapper/PhpStreamWrapperInterface.php

<?php

namespace Drupal\Core\StreamWrapper;

/**
 * Defines a generic PHP stream wrapper interface.
 *
 * @see http://php.net/manual/class.streamwrapper.php
 */
interface PhpStreamWrapperInterface {

  /**
   * 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 bool
   *   Returns TRUE on success or FALSE on failure.
   *
   * @see closedir()
   * @see http://php.net/manual/en/streamwrapper.dir-closedir.php
   */
  public function dir_closedir();

  /**
   * Open directory handle.
   *
   * This method is called in response to opendir().
   *
   * @param string $path
   *   Specifies the URL that was passed to opendir().
   * @param int $options
   *   Whether or not to enforce safe_mode (0x04).
   *
   * @return bool
   *   Returns TRUE on success or FALSE on failure.
   *
   * @see opendir()
   * @see http://php.net/manual/en/streamwrapper.dir-opendir.php
   */
  public function dir_opendir($path, $options);

  /**
   * Read entry from directory handle.
   *
   * This method is called in response to readdir().
   *
   * @return 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 readdir()
   * @see http://php.net/manual/en/streamwrapper.dir-readdir.php
   */
  public function dir_readdir();

  /**
   * 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 bool
   *   Returns TRUE on success or FALSE on failure.
   *
   * @see rewinddir()
   * @see PhpStreamWrapperInterface::dir_readdir()
   * @see http://php.net/manual/en/streamwrapper.dir-rewinddir.php
   */
  public function dir_rewinddir();

  /**
   * 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.
   *
   * @param string $path
   *   Directory which should be created.
   * @param int $mode
   *   The value passed to mkdir().
   * @param int $options
   *   A bitwise mask of values, such as STREAM_MKDIR_RECURSIVE.
   *
   * @return bool
   *   Returns TRUE on success or FALSE on failure.
   *
   * @see mkdir()
   * @see PhpStreamWrapperInterface::rmdir()
   * @see http://php.net/manual/en/streamwrapper.mkdir.php
   */
  public function mkdir($path, $mode, $options);

  /**
   * 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.
   *
   * @param string $path_from
   *   The URL to the current file.
   * @param string $path_to
   *   The URL which the $path_from should be renamed to.
   *
   * @return bool
   *   Returns TRUE on success or FALSE on failure.
   *
   * @see rename()
   * @see http://php.net/manual/en/streamwrapper.rename.php
   */
  public function rename($path_from, $path_to);

  /**
   * 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.
   *
   * @param string $path
   *   The directory URL which should be removed.
   * @param int $options
   *   A bitwise mask of values, such as STREAM_MKDIR_RECURSIVE.
   *
   * @return bool
   *   Returns TRUE on success or FALSE on failure.
   *
   * @see rmdir()
   * @see PhpStreamWrapperInterface::mkdir()
   * @see PhpStreamWrapperInterface::unlink()
   * @see http://php.net/manual/en/streamwrapper.rmdir.php
   */
  public function rmdir($path, $options);

  /**
   * Retrieve the underlying stream resource.
   *
   * This method is called in response to stream_select().
   *
   * @param 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 resource|false
   *   The underlying stream resource or FALSE if stream_select() is not
   *   supported.
   *
   * @see stream_select()
   * @see http://php.net/manual/streamwrapper.stream-cast.php
   */
  public function stream_cast($cast_as);

  /**
   * Closes stream.
   *
   * This method is called in response to fclose(). All resources that were
   * locked, or allocated, by the wrapper should be released.
   *
   * @see fclose()
   * @see PhpStreamWrapperInterface::dir_closedir()
   * @see http://php.net/manual/en/streamwrapper.stream-close.php
   */
  public function stream_close();

  /**
   * 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 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 feof()
   * @see http://php.net/manual/en/streamwrapper.stream-eof.php
   */
  public function stream_eof();

  /**
   * 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 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 fflush()
   * @see http://php.net/manual/en/streamwrapper.stream-flush.php
   */
  public function stream_flush();

  /**
   * 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).
   *
   * @param 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 bool
   *   Returns TRUE on success or FALSE on failure.
   *
   * @see flock()
   * @see stream_set_blocking()
   * @see http://php.net/manual/en/streamwrapper.stream-lock.php
   */
  public function stream_lock($operation);

  /**
   * Sets metadata on the stream.
   *
   * @param string $path
   *   A string containing the URI to the file to set metadata on.
   * @param 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().
   * @param 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 bool
   *   Returns TRUE on success or FALSE on failure. If $option is not
   *   implemented, FALSE should be returned.
   *
   * @see http://php.net/manual/streamwrapper.stream-metadata.php
   */
  public function stream_metadata($path, $option, $value);

  /**
   * 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.
   *
   * @param 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.
   * @param 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.
   * @param 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.
   * @param 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 bool
   *   Returns TRUE on success or FALSE on failure.
   *
   * @see fopen()
   * @see parse_url()
   * @see http://php.net/manual/en/streamwrapper.stream-open.php
   */
  public function stream_open($path, $mode, $options, &$opened_path);

  /**
   * 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.
   *
   * @param int $count
   *   How many bytes of data from the current position should be returned.
   *
   * @return 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 fread()
   * @see fgets()
   * @see http://php.net/manual/en/streamwrapper.stream-read.php
   */
  public function stream_read($count);

  /**
   * 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.
   *
   * @param int $offset
   *   The byte offset to seek to.
   * @param 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 bool
   *   TRUE if the position was updated, FALSE otherwise.
   *
   * @see http://php.net/manual/streamwrapper.stream-seek.php
   */
  public function stream_seek($offset, $whence = SEEK_SET);

  /**
   * Change stream options.
   *
   * This method is called to set options on the stream.
   *
   * @param 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().
   * @param 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.
   * @param 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 bool
   *   TRUE on success, FALSE otherwise. If $option is not implemented, FALSE
   *   should be returned.
   */
  public function stream_set_option($option, $arg1, $arg2);

  /**
   * Retrieve information about a file resource.
   *
   * This method is called in response to fstat().
   *
   * @return array|false
   *   See stat().
   *
   * @see stat()
   * @see PhpStreamWrapperInterface::url_stat()
   * @see http://php.net/manual/en/streamwrapper.stream-stat.php
   */
  public function stream_stat();

  /**
   * Retrieve the current position of a stream.
   *
   * This method is called in response to fseek() to determine the current
   * position.
   *
   * @return int
   *   Should return the current position of the stream.
   *
   * @see PhpStreamWrapperInterface::stream_tell()
   * @see http://php.net/manual/en/streamwrapper.stream-tell.php
   */
  public function stream_tell();

  /**
   * Truncate stream.
   *
   * Will respond to truncation; e.g., through ftruncate().
   *
   * @param int $new_size
   *   The new size.
   *
   * @return bool
   *   TRUE on success, FALSE otherwise.
   *
   * @see ftruncate()
   * @see http://php.net/manual/en/streamwrapper.stream-truncate.php
   */
  public function stream_truncate($new_size);

  /**
   * 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.
   *
   * @param 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 int
   *   Should return the number of bytes that were successfully stored, or 0 if
   *   none could be stored.
   *
   * @see fwrite()
   * @see http://php.net/manual/en/streamwrapper.stream-write.php
   */
  public function stream_write($data);

  /**
   * 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.
   *
   * @param string $path
   *   The file URL which should be deleted.
   *
   * @return bool
   *   Returns TRUE on success or FALSE on failure.
   *
   * @see unlink()
   * @see PhpStreamWrapperInterface::rmdir()
   * @see http://php.net/manual/en/streamwrapper.unlink.php
   */
  public function unlink($path);

  /**
   * 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.
   *
   * @param 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.
   * @param 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 array|false
   *   Should return the same as stat() does. Unknown or unavailable values
   *   should be set to a rational value (usually 0).
   *
   * @see stat()
   * @see PhpStreamWrapperInterface::stream_stat()
   * @see http://php.net/manual/en/streamwrapper.url-stat.php
   */
  public function url_stat($path, $flags);

}