yaffs.net Git - yaffs-website/blob - vendor/psr/http-message/src/StreamInterface.php

   1 <?php
   2
   3 namespace Psr\Http\Message;
   4
   5 /**
   6  * Describes a data stream.
   7  *
   8  * Typically, an instance will wrap a PHP stream; this interface provides
   9  * a wrapper around the most common operations, including serialization of
  10  * the entire stream to a string.
  11  */
  12 interface StreamInterface
  13 {
  14     /**
  15      * Reads all data from the stream into a string, from the beginning to end.
  16      *
  17      * This method MUST attempt to seek to the beginning of the stream before
  18      * reading data and read the stream until the end is reached.
  19      *
  20      * Warning: This could attempt to load a large amount of data into memory.
  21      *
  22      * This method MUST NOT raise an exception in order to conform with PHP's
  23      * string casting operations.
  24      *
  25      * @see http://php.net/manual/en/language.oop5.magic.php#object.tostring
  26      * @return string
  27      */
  28     public function __toString();
  29
  30     /**
  31      * Closes the stream and any underlying resources.
  32      *
  33      * @return void
  34      */
  35     public function close();
  36
  37     /**
  38      * Separates any underlying resources from the stream.
  39      *
  40      * After the stream has been detached, the stream is in an unusable state.
  41      *
  42      * @return resource|null Underlying PHP stream, if any
  43      */
  44     public function detach();
  45
  46     /**
  47      * Get the size of the stream if known.
  48      *
  49      * @return int|null Returns the size in bytes if known, or null if unknown.
  50      */
  51     public function getSize();
  52
  53     /**
  54      * Returns the current position of the file read/write pointer
  55      *
  56      * @return int Position of the file pointer
  57      * @throws \RuntimeException on error.
  58      */
  59     public function tell();
  60
  61     /**
  62      * Returns true if the stream is at the end of the stream.
  63      *
  64      * @return bool
  65      */
  66     public function eof();
  67
  68     /**
  69      * Returns whether or not the stream is seekable.
  70      *
  71      * @return bool
  72      */
  73     public function isSeekable();
  74
  75     /**
  76      * Seek to a position in the stream.
  77      *
  78      * @link http://www.php.net/manual/en/function.fseek.php
  79      * @param int $offset Stream offset
  80      * @param int $whence Specifies how the cursor position will be calculated
  81      *     based on the seek offset. Valid values are identical to the built-in
  82      *     PHP $whence values for `fseek()`.  SEEK_SET: Set position equal to
  83      *     offset bytes SEEK_CUR: Set position to current location plus offset
  84      *     SEEK_END: Set position to end-of-stream plus offset.
  85      * @throws \RuntimeException on failure.
  86      */
  87     public function seek($offset, $whence = SEEK_SET);
  88
  89     /**
  90      * Seek to the beginning of the stream.
  91      *
  92      * If the stream is not seekable, this method will raise an exception;
  93      * otherwise, it will perform a seek(0).
  94      *
  95      * @see seek()
  96      * @link http://www.php.net/manual/en/function.fseek.php
  97      * @throws \RuntimeException on failure.
  98      */
  99     public function rewind();
 100
 101     /**
 102      * Returns whether or not the stream is writable.
 103      *
 104      * @return bool
 105      */
 106     public function isWritable();
 107
 108     /**
 109      * Write data to the stream.
 110      *
 111      * @param string $string The string that is to be written.
 112      * @return int Returns the number of bytes written to the stream.
 113      * @throws \RuntimeException on failure.
 114      */
 115     public function write($string);
 116
 117     /**
 118      * Returns whether or not the stream is readable.
 119      *
 120      * @return bool
 121      */
 122     public function isReadable();
 123
 124     /**
 125      * Read data from the stream.
 126      *
 127      * @param int $length Read up to $length bytes from the object and return
 128      *     them. Fewer than $length bytes may be returned if underlying stream
 129      *     call returns fewer bytes.
 130      * @return string Returns the data read from the stream, or an empty string
 131      *     if no bytes are available.
 132      * @throws \RuntimeException if an error occurs.
 133      */
 134     public function read($length);
 135
 136     /**
 137      * Returns the remaining contents in a string
 138      *
 139      * @return string
 140      * @throws \RuntimeException if unable to read or an error occurs while
 141      *     reading.
 142      */
 143     public function getContents();
 144
 145     /**
 146      * Get stream metadata as an associative array or retrieve a specific key.
 147      *
 148      * The keys returned are identical to the keys returned from PHP's
 149      * stream_get_meta_data() function.
 150      *
 151      * @link http://php.net/manual/en/function.stream-get-meta-data.php
 152      * @param string $key Specific metadata to retrieve.
 153      * @return array|mixed|null Returns an associative array if no key is
 154      *     provided. Returns a specific key value if a key is provided and the
 155      *     value is found, or null if the key is not found.
 156      */
 157     public function getMetadata($key = null);
 158 }