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: }
159: