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:      *
 27:      * @return string
 28:      */
 29:     public function __toString();
 30: 
 31:     /**
 32:      * Closes the stream and any underlying resources.
 33:      */
 34:     public function close();
 35: 
 36:     /**
 37:      * Separates any underlying resources from the stream.
 38:      *
 39:      * After the stream has been detached, the stream is in an unusable state.
 40:      *
 41:      * @return resource|null Underlying PHP stream, if any
 42:      */
 43:     public function detach();
 44: 
 45:     /**
 46:      * Get the size of the stream if known.
 47:      *
 48:      * @return int|null returns the size in bytes if known, or null if unknown
 49:      */
 50:     public function getSize();
 51: 
 52:     /**
 53:      * Returns the current position of the file read/write pointer.
 54:      *
 55:      * @throws \RuntimeException on error
 56:      *
 57:      * @return int Position of the file pointer
 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:      *     based on the seek offset. Valid values are identical to the built-in
 79:      *     PHP $whence values for `fseek()`.  SEEK_SET: Set position equal to
 80:      *     offset bytes SEEK_CUR: Set position to current location plus offset
 81:      *     SEEK_END: Set position to end-of-stream plus offset.
 82:      *
 83:      * @see http://www.php.net/manual/en/function.fseek.php
 84:      *
 85:      * @param int $offset Stream offset
 86:      * @param int $whence Specifies how the cursor position will be calculated
 87:      *
 88:      * @throws \RuntimeException on failure
 89:      */
 90:     public function seek($offset, $whence = SEEK_SET);
 91: 
 92:     /**
 93:      * Seek to the beginning of the stream.
 94:      *
 95:      * If the stream is not seekable, this method will raise an exception;
 96:      * otherwise, it will perform a seek(0).
 97:      *
 98:      * @see http://www.php.net/manual/en/function.fseek.php
 99:      * @see seek()
100:      *
101:      * @throws \RuntimeException on failure
102:      */
103:     public function rewind();
104: 
105:     /**
106:      * Returns whether or not the stream is writable.
107:      *
108:      * @return bool
109:      */
110:     public function isWritable();
111: 
112:     /**
113:      * Write data to the stream.
114:      *
115:      * @param string $string the string that is to be written
116:      *
117:      * @throws \RuntimeException on failure
118:      *
119:      * @return int returns the number of bytes written to the stream
120:      */
121:     public function write($string);
122: 
123:     /**
124:      * Returns whether or not the stream is readable.
125:      *
126:      * @return bool
127:      */
128:     public function isReadable();
129: 
130:     /**
131:      * Read data from the stream.
132:      *
133:      *     them. Fewer than $length bytes may be returned if underlying stream
134:      *     call returns fewer bytes.
135:      *     if no bytes are available.
136:      *
137:      * @param int $length Read up to $length bytes from the object and return
138:      *
139:      * @throws \RuntimeException if an error occurs
140:      *
141:      * @return string Returns the data read from the stream, or an empty string
142:      */
143:     public function read($length);
144: 
145:     /**
146:      * Returns the remaining contents in a string.
147:      *
148:      *     reading.
149:      *
150:      * @throws \RuntimeException if unable to read or an error occurs while
151:      *
152:      * @return string
153:      */
154:     public function getContents();
155: 
156:     /**
157:      * Get stream metadata as an associative array or retrieve a specific key.
158:      *
159:      * The keys returned are identical to the keys returned from PHP's
160:      * stream_get_meta_data() function.
161:      *
162:      *     provided. Returns a specific key value if a key is provided and the
163:      *     value is found, or null if the key is not found.
164:      *
165:      * @see http://php.net/manual/en/function.stream-get-meta-data.php
166:      *
167:      * @param string $key specific metadata to retrieve
168:      *
169:      * @return array|mixed|null Returns an associative array if no key is
170:      */
171:     public function getMetadata($key = null);
172: }
173: