1	<?php
2	/**
3	* Jingga
4	*
5	* PHP Version 8.1
6	*
7	* @package   phpOMS\Contract
8	* @copyright Dennis Eichhorn
9	* @license   OMS License 2.0
10	* @version   1.0.0
11	* @link      https://jingga.app
12	*/
13	declare(strict_types=1);
14
15	namespace phpOMS\Contract;
16
17	/**
18	* Make a class streamable.
19	*
20	* @package phpOMS\Contract
21	* @license OMS License 2.0
22	* @link    https://jingga.app
23	* @since   1.0.0
24	*/
25	interface StreamInterface
26	{
27	/**
28	* Convert the stream to a string if the stream is readable and the stream is seekable.
29	*
30	* @return string
31	*
32	* @since 1.0.0
33	*/
34	public function __toString();
35
36	/**
37	* Close the underlying stream
38	*
39	* @return void
40	*
41	* @since 1.0.0
42	*/
43	public function close() : void;
44
45	/**
46	* Get stream metadata
47	*
48	* @param string $key Specific metadata to retrieve
49	*
50	* @return array|mixed|null
51	*
52	* @since 1.0.0
53	*/
54	public function getMetaData(string $key = null);
55
56	/**
57	* Get the stream resource
58	*
59	* @return resource
60	*
61	* @since 1.0.0
62	*/
63	public function getStream();
64
65	/**
66	* Set the stream that is wrapped by the object
67	*
68	* @param resource $stream Stream resource to wrap
69	* @param null|int $size   Size of the stream in bytes. Only pass if the size cannot be obtained from the stream.
70	*
71	* @return self
72	*
73	* @since 1.0.0
74	*/
75	public function setStream($stream, int $size = null) : self;
76
77	/**
78	* Detach the current stream resource
79	*
80	* @return self
81	*
82	* @since 1.0.0
83	*/
84	public function detachStream() : self;
85
86	/**
87	* Get the stream wrapper type
88	*
89	* @return string
90	*
91	* @since 1.0.0
92	*/
93	public function getWrapper() : string;
94
95	/**
96	* Wrapper specific data attached to this stream.
97	*
98	* @return array
99	*
100	* @since 1.0.0
101	*/
102	public function getWrapperData() : array;
103
104	/**
105	* Get a label describing the underlying implementation of the stream
106	*
107	* @return string
108	*
109	* @since 1.0.0
110	*/
111	public function getStreamType() : string;
112
113	/**
114	* Get the URI/filename associated with this stream
115	*
116	* @return string
117	*
118	* @since 1.0.0
119	*/
120	public function getUri() : string;
121
122	/**
123	* Get the size of the stream if able
124	*
125	* @return int
126	*
127	* @since 1.0.0
128	*/
129	public function getSize() : int;
130
131	/**
132	* Check if the stream is readable
133	*
134	* @return bool
135	*
136	* @since 1.0.0
137	*/
138	public function isReadable() : bool;
139
140	/**
141	* Check if the stream is repeatable
142	*
143	* @return bool
144	*
145	* @since 1.0.0
146	*/
147	public function isRepeatable() : bool;
148
149	/**
150	* Check if the stream is writable
151	*
152	* @return bool
153	*
154	* @since 1.0.0
155	*/
156	public function isWritable() : bool;
157
158	/**
159	* Check if the stream has been consumed
160	*
161	* @return bool
162	*
163	* @since 1.0.0
164	*/
165	public function isConsumed() : bool;
166
167	/**
168	* Alias of isConsumed
169	*
170	* @return bool
171	*
172	* @since 1.0.0
173	*/
174	public function feof() : bool;
175
176	/**
177	* Check if the stream is a local stream vs a remote stream
178	*
179	* @return bool
180	*
181	* @since 1.0.0
182	*/
183	public function isLocal() : bool;
184
185	/**
186	* Check if the string is repeatable
187	*
188	* @return bool
189	*
190	* @since 1.0.0
191	*/
192	public function isSeekable() : bool;
193
194	/**
195	* Specify the size of the stream in bytes
196	*
197	* @param int $size Size of the stream contents in bytes
198	*
199	* @return self
200	*
201	* @since 1.0.0
202	*/
203	public function setSize(int $size) : self;
204
205	/**
206	* Seek to a position in the stream
207	*
208	* @param int $offset Stream offset
209	* @param int $whence Where the offset is applied
210	*
211	* @return bool Returns TRUE on success or FALSE on failure
212	* @link   http://www.php.net/manual/en/function.fseek.php
213	*
214	* @since 1.0.0
215	*/
216	public function seek(int $offset, int $whence = \SEEK_SET) : bool;
217
218	/**
219	* Read data from the stream
220	*
221	* @param int $length up to length number of bytes read
222	*
223	* @return string Returns the data read from the stream or FALSE on failure or EOF
224	*
225	* @since 1.0.0
226	*/
227	public function read(int $length) : ?string;
228
229	/**
230	* Write data to the stream
231	*
232	* @param string $string the string that is to be written
233	*
234	* @return int returns the number of bytes written to the stream on success or FALSE on failure
235	*
236	* @since 1.0.0
237	*/
238	public function write(string $string) : int;
239
240	/**
241	* Returns the current position of the file read/write pointer
242	*
243	* @return int Returns the position of the file pointer or false on error
244	*
245	* @since 1.0.0
246	*/
247	public function ftell() : int;
248
249	/**
250	* Rewind to the beginning of the stream
251	*
252	* @return bool Returns true on success or false on failure
253	*
254	* @since 1.0.0
255	*/
256	public function rewind() : bool;
257
258	/**
259	* Read a line from the stream up to the maximum allowed buffer length
260	*
261	* @param int $maxLength Maximum buffer length
262	*
263	* @return string
264	*
265	* @since 1.0.0
266	*/
267	public function readLine(int $maxLength = null) : ?string;
268
269	/**
270	* Set custom data on the stream
271	*
272	* @param string $key   Key to set
273	* @param mixed  $value Value to set
274	*
275	* @return self
276	*
277	* @since 1.0.0
278	*/
279	public function setCustomData(string $key, mixed $value) : self;
280
281	/**
282	* Get custom data from the stream
283	*
284	* @param string $key Key to retrieve
285	*
286	* @return null|mixed
287	*
288	* @since 1.0.0
289	*/
290	public function getCustomData(string $key);
291	}