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: