1<?php
2namespace GuzzleHttp\Stream;
3
4/**
5 * Describes a stream instance.
6 */
7interface StreamInterface
8{
9    /**
10     * Attempts to seek to the beginning of the stream and reads all data into
11     * a string until the end of the stream is reached.
12     *
13     * Warning: This could attempt to load a large amount of data into memory.
14     *
15     * @return string
16     */
17    public function __toString();
18
19    /**
20     * Closes the stream and any underlying resources.
21     */
22    public function close();
23
24    /**
25     * Separates any underlying resources from the stream.
26     *
27     * After the underlying resource has been detached, the stream object is in
28     * an unusable state. If you wish to use a Stream object as a PHP stream
29     * but keep the Stream object in a consistent state, use
30     * {@see GuzzleHttp\Stream\GuzzleStreamWrapper::getResource}.
31     *
32     * @return resource|null Returns the underlying PHP stream resource or null
33     *                       if the Stream object did not utilize an underlying
34     *                       stream resource.
35     */
36    public function detach();
37
38    /**
39     * Replaces the underlying stream resource with the provided stream.
40     *
41     * Use this method to replace the underlying stream with another; as an
42     * example, in server-side code, if you decide to return a file, you
43     * would replace the original content-oriented stream with the file
44     * stream.
45     *
46     * Any internal state such as caching of cursor position should be reset
47     * when attach() is called, as the stream has changed.
48     *
49     * @param resource $stream
50     *
51     * @return void
52     */
53    public function attach($stream);
54
55    /**
56     * Get the size of the stream if known
57     *
58     * @return int|null Returns the size in bytes if known, or null if unknown
59     */
60    public function getSize();
61
62    /**
63     * Returns the current position of the file read/write pointer
64     *
65     * @return int|bool Returns the position of the file pointer or false on error
66     */
67    public function tell();
68
69    /**
70     * Returns true if the stream is at the end of the stream.
71     *
72     * @return bool
73     */
74    public function eof();
75
76    /**
77     * Returns whether or not the stream is seekable
78     *
79     * @return bool
80     */
81    public function isSeekable();
82
83    /**
84     * Seek to a position in the stream
85     *
86     * @param int $offset Stream offset
87     * @param int $whence Specifies how the cursor position will be calculated
88     *                    based on the seek offset. Valid values are identical
89     *                    to the built-in PHP $whence values for `fseek()`.
90     *                    SEEK_SET: Set position equal to offset bytes
91     *                    SEEK_CUR: Set position to current location plus offset
92     *                    SEEK_END: Set position to end-of-stream plus offset
93     *
94     * @return bool Returns true on success or false on failure
95     * @link   http://www.php.net/manual/en/function.fseek.php
96     */
97    public function seek($offset, $whence = SEEK_SET);
98
99    /**
100     * Returns whether or not the stream is writable
101     *
102     * @return bool
103     */
104    public function isWritable();
105
106    /**
107     * Write data to the stream
108     *
109     * @param string $string The string that is to be written.
110     *
111     * @return int|bool Returns the number of bytes written to the stream on
112     *                  success returns false on failure (e.g., broken pipe,
113     *                  writer needs to slow down, buffer is full, etc.)
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
129     *                    underlying stream call returns fewer bytes.
130     *
131     * @return string     Returns the data read from the stream.
132     */
133    public function read($length);
134
135    /**
136     * Returns the remaining contents of the stream as a string.
137     *
138     * Note: this could potentially load a large amount of data into memory.
139     *
140     * @return string
141     */
142    public function getContents();
143
144    /**
145     * Get stream metadata as an associative array or retrieve a specific key.
146     *
147     * The keys returned are identical to the keys returned from PHP's
148     * stream_get_meta_data() function.
149     *
150     * @param string $key Specific metadata to retrieve.
151     *
152     * @return array|mixed|null Returns an associative array if no key is
153     *                          no key is provided. Returns a specific key
154     *                          value if a key is provided and the value is
155     *                          found, or null if the key is not found.
156     * @see http://php.net/manual/en/function.stream-get-meta-data.php
157     */
158    public function getMetadata($key = null);
159}
160