Skip to content

Commit d5beb58

Browse files
lkrmslkrms
committed
Merge branch 'cleanup'
2 parents ee943ff + a9eb98c commit d5beb58

File tree

3 files changed

+282
-289
lines changed

3 files changed

+282
-289
lines changed

‎src/Toolkit/Contract/Polyfill/FilesystemStreamWrapperInterface.php‎ renamed to ‎src/Toolkit/Contract/Polyfill/FilesystemStreamWrapper.php‎

Lines changed: 15 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,14 @@
33
namespace Salient\Contract\Polyfill;
44

55
/**
6+
* Abstraction of the streamWrapper prototype described in the PHP manual
7+
*
8+
* Stream wrappers that do not support filesystem operations should extend
9+
* {@see StreamWrapper} instead.
10+
*
611
* @api
712
*/
8-
interface FilesystemStreamWrapperInterface extends StreamWrapperInterface
13+
abstract class FilesystemStreamWrapper extends StreamWrapper
914
{
1015
/**
1116
* Close directory handle
@@ -17,7 +22,7 @@ interface FilesystemStreamWrapperInterface extends StreamWrapperInterface
1722
*
1823
* @return bool `true` on success or `false` on failure.
1924
*/
20-
public function dir_closedir(): bool;
25+
abstract public function dir_closedir(): bool;
2126

2227
/**
2328
* Open directory handle
@@ -28,7 +33,7 @@ public function dir_closedir(): bool;
2833
* {@see opendir()}.
2934
* @return bool `true` on success or `false` on failure.
3035
*/
31-
public function dir_opendir(string $path, int $options): bool;
36+
abstract public function dir_opendir(string $path, int $options): bool;
3237

3338
/**
3439
* Read entry from directory handle
@@ -38,7 +43,7 @@ public function dir_opendir(string $path, int $options): bool;
3843
* @return string|false The next filename, or `false` if there is no next
3944
* file.
4045
*/
41-
public function dir_readdir();
46+
abstract public function dir_readdir();
4247

4348
/**
4449
* Rewind directory handle
@@ -52,7 +57,7 @@ public function dir_readdir();
5257
*
5358
* @return bool `true` on success or `false` on failure.
5459
*/
55-
public function dir_rewinddir(): bool;
60+
abstract public function dir_rewinddir(): bool;
5661

5762
/**
5863
* Create a directory
@@ -65,7 +70,7 @@ public function dir_rewinddir(): bool;
6570
* {@see \STREAM_MKDIR_RECURSIVE}.
6671
* @return bool `true` on success or `false` on failure.
6772
*/
68-
public function mkdir(string $path, int $mode, int $options): bool;
73+
abstract public function mkdir(string $path, int $mode, int $options): bool;
6974

7075
/**
7176
* Renames a file or directory
@@ -77,7 +82,7 @@ public function mkdir(string $path, int $mode, int $options): bool;
7782
* to.
7883
* @return bool `true` on success or `false` on failure.
7984
*/
80-
public function rename(string $path_from, string $path_to): bool;
85+
abstract public function rename(string $path_from, string $path_to): bool;
8186

8287
/**
8388
* Removes a directory
@@ -89,7 +94,7 @@ public function rename(string $path_from, string $path_to): bool;
8994
* {@see \STREAM_MKDIR_RECURSIVE}.
9095
* @return bool `true` on success or `false` on failure.
9196
*/
92-
public function rmdir(string $path, int $options): bool;
97+
abstract public function rmdir(string $path, int $options): bool;
9398

9499
/**
95100
* Advisory file locking
@@ -108,7 +113,7 @@ public function rmdir(string $path, int $options): bool;
108113
* locking (not supported on Windows).
109114
* @return bool `true` on success or `false` on failure.
110115
*/
111-
public function stream_lock(int $operation): bool;
116+
abstract public function stream_lock(int $operation): bool;
112117

113118
/**
114119
* Delete a file
@@ -118,5 +123,5 @@ public function stream_lock(int $operation): bool;
118123
* @param string $path The file URL which should be deleted.
119124
* @return bool `true` on success or `false` on failure.
120125
*/
121-
public function unlink(string $path): bool;
126+
abstract public function unlink(string $path): bool;
122127
}

‎src/Toolkit/Contract/Polyfill/StreamWrapper.php‎

Lines changed: 267 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,18 +3,280 @@
33
namespace Salient\Contract\Polyfill;
44

55
/**
6-
* Abstraction of the streamWrapper prototype class described in the PHP manual
6+
* Abstraction of the streamWrapper prototype described in the PHP manual
77
*
8-
* Methods that should not be defined by wrappers that do not support them are
9-
* declared in {@see FilesystemStreamWrapperInterface}, which may be implemented
10-
* by wrappers that extend this class.
8+
* Stream wrappers that support filesystem operations should extend
9+
* {@see FilesystemStreamWrapper} instead.
1110
*
1211
* @api
1312
*
1413
* @link https://www.php.net/manual/en/class.streamwrapper.php
1514
*/
16-
abstract class StreamWrapper implements StreamWrapperInterface
15+
abstract class StreamWrapper
1716
{
1817
/** @var resource|null */
1918
public $context;
19+
20+
/**
21+
* Constructs a new stream wrapper
22+
*
23+
* Called when opening the stream wrapper, right before
24+
* {@see StreamWrapper::stream_open()}.
25+
*/
26+
abstract public function __construct();
27+
28+
/**
29+
* Retrieve the underlying resource
30+
*
31+
* This method is called in response to {@see stream_select()}.
32+
*
33+
* @param int $cast_as Can be {@see \STREAM_CAST_FOR_SELECT} when
34+
* {@see stream_select()} is calling **stream_cast()** or
35+
* {@see \STREAM_CAST_AS_STREAM} when **stream_cast()** is called for other
36+
* uses.
37+
* @return resource|false The underlying stream resource used by the
38+
* wrapper, or `false`.
39+
*/
40+
abstract public function stream_cast(int $cast_as);
41+
42+
/**
43+
* Close a resource
44+
*
45+
* This method is called in response to {@see fclose()}.
46+
*
47+
* All resources that were locked, or allocated, by the wrapper should be
48+
* released.
49+
*/
50+
abstract public function stream_close(): void;
51+
52+
/**
53+
* Tests for end-of-file on a file pointer
54+
*
55+
* This method is called in response to {@see feof()}.
56+
*
57+
* @return bool `true` if the read/write position is at the end of the
58+
* stream and if no more data is available to be read, or `false` otherwise.
59+
*/
60+
abstract public function stream_eof(): bool;
61+
62+
/**
63+
* Flushes the output
64+
*
65+
* This method is called in response to {@see fflush()} and when the stream
66+
* is being closed while any unflushed data has been written to it before.
67+
*
68+
* If you have cached data in your stream but not yet stored it into the
69+
* underlying storage, you should do so now.
70+
*
71+
* @return bool `true` if the cached data was successfully stored (or if
72+
* there was no data to store), or `false` if the data could not be stored.
73+
*/
74+
abstract public function stream_flush(): bool;
75+
76+
/**
77+
* Change stream metadata
78+
*
79+
* This method is called to set metadata on the stream. It is called when
80+
* one of the following functions is called on a stream URL:
81+
*
82+
* - {@see touch()}
83+
* - {@see chmod()}
84+
* - {@see chown()}
85+
* - {@see chgrp()}
86+
*
87+
* @param string $path The file path or URL to set metadata. Note that in
88+
* the case of a URL, it must be a :// delimited URL. Other URL forms are
89+
* not supported.
90+
* @param int $option One of:
91+
*
92+
* - {@see \STREAM_META_TOUCH} (The method was called in response to
93+
* {@see touch()})
94+
* - {@see \STREAM_META_OWNER_NAME} (The method was called in response to
95+
* {@see chown()})
96+
* - {@see \STREAM_META_OWNER} (The method was called in response to
97+
* {@see chown()})
98+
* - {@see \STREAM_META_GROUP_NAME} (The method was called in response to
99+
* {@see chgrp()})
100+
* - {@see \STREAM_META_GROUP} (The method was called in response to
101+
* {@see chgrp()})
102+
* - {@see \STREAM_META_ACCESS} (The method was called in response to
103+
* {@see chmod()})
104+
* @param mixed $value If `option` is
105+
*
106+
* - {@see \STREAM_META_TOUCH}: Array consisting of two arguments of the
107+
* {@see touch()} function.
108+
* - {@see \STREAM_META_OWNER_NAME} or {@see \STREAM_META_GROUP_NAME}: The
109+
* name of the owner user/group as `string`.
110+
* - {@see \STREAM_META_OWNER} or {@see \STREAM_META_GROUP}: The value of
111+
* the owner user/group as `int`.
112+
* - {@see \STREAM_META_ACCESS}: The argument of the {@see chmod()} function
113+
* as `int`.
114+
* @return bool `true` on success or `false` on failure. If `option` is not
115+
* implemented, `false` should be returned.
116+
*/
117+
abstract public function stream_metadata(string $path, int $option, $value): bool;
118+
119+
/**
120+
* Opens file or URL
121+
*
122+
* This method is called immediately after the wrapper is initialized (e.g.
123+
* by {@see fopen()} and {@see file_get_contents()}).
124+
*
125+
* @param string $path Specifies the URL that was passed to the original
126+
* function. Only URLs delimited by :// are supported.
127+
* @param string $mode The mode used to open the file, as detailed for
128+
* {@see fopen()}.
129+
* @param int $options Holds additional flags set by the streams API. It can
130+
* hold one or more of the following values OR'd together.
131+
*
132+
* - {@see \STREAM_USE_PATH}: If `path` is relative, search for the resource
133+
* using the include_path.
134+
* - {@see \STREAM_REPORT_ERRORS}: If this flag is set, you are responsible
135+
* for raising errors using {@see trigger_error()} during opening of the
136+
* stream. If this flag is not set, you should not raise any errors.
137+
* @param string|null $opened_path If the `path` is opened successfully, and
138+
* {@see \STREAM_USE_PATH} is set in `options`, `opened_path` should be set
139+
* to the full path of the file/resource that was actually opened.
140+
* @return bool `true` on success or `false` on failure.
141+
*/
142+
abstract public function stream_open(
143+
string $path,
144+
string $mode,
145+
int $options,
146+
?string &$opened_path
147+
): bool;
148+
149+
/**
150+
* Read from stream
151+
*
152+
* This method is called in response to {@see fread()} and {@see fgets()}.
153+
*
154+
* > Remember to update the read/write position of the stream (by the number
155+
* > of bytes that were successfully read).
156+
*
157+
* @param int $count How many bytes of data from the current position should
158+
* be returned.
159+
* @return string|false If there are less than `count` bytes available, as
160+
* many as are available should be returned. If no more data is available,
161+
* an empty string should be returned. To signal that reading failed,
162+
* `false` should be returned.
163+
*/
164+
abstract public function stream_read(int $count);
165+
166+
/**
167+
* Seeks to specific location in a stream
168+
*
169+
* This method is called in response to {@see fseek()}.
170+
*
171+
* @param int $offset The stream offset to seek to.
172+
* @param int $whence Possible values:
173+
*
174+
* - {@see \SEEK_SET}: Set position equal to `offset` bytes.
175+
* - {@see \SEEK_CUR}: Set position to current location plus `offset`.
176+
* (Never used by current implementation; always internally converted to
177+
* {@see \SEEK_SET}.)
178+
* - {@see \SEEK_END}: Set position to end-of-file plus `offset`.
179+
* @return bool `true` if the position was updated, `false` otherwise.
180+
*/
181+
abstract public function stream_seek(int $offset, int $whence = \SEEK_SET): bool;
182+
183+
/**
184+
* Change stream options
185+
*
186+
* @param int $option One of:
187+
*
188+
* - {@see \STREAM_OPTION_BLOCKING} (The method was called in response to
189+
* {@see stream_set_blocking()})
190+
* - {@see \STREAM_OPTION_READ_TIMEOUT} (The method was called in response
191+
* to {@see stream_set_timeout()})
192+
* - {@see \STREAM_OPTION_READ_BUFFER} (The method was called in response to
193+
* {@see stream_set_read_buffer()})
194+
* - {@see \STREAM_OPTION_WRITE_BUFFER} (The method was called in response
195+
* to {@see stream_set_write_buffer()})
196+
* @param int $arg1 If `option` is
197+
*
198+
* - {@see \STREAM_OPTION_BLOCKING}: requested blocking mode (1 meaning
199+
* block, 0 not blocking).
200+
* - {@see \STREAM_OPTION_READ_TIMEOUT}: the timeout in seconds.
201+
* - {@see \STREAM_OPTION_READ_BUFFER}: buffer mode
202+
* ({@see \STREAM_BUFFER_NONE} or {@see \STREAM_BUFFER_FULL}).
203+
* - {@see \STREAM_OPTION_WRITE_BUFFER}: buffer mode
204+
* ({@see \STREAM_BUFFER_NONE} or {@see \STREAM_BUFFER_FULL}).
205+
* @param int $arg2 If `option` is
206+
*
207+
* - {@see \STREAM_OPTION_BLOCKING}: not set.
208+
* - {@see \STREAM_OPTION_READ_TIMEOUT}: the timeout in microseconds.
209+
* - {@see \STREAM_OPTION_READ_BUFFER}: the requested buffer size.
210+
* - {@see \STREAM_OPTION_WRITE_BUFFER}: the requested buffer size.
211+
* @return bool `true` on success or `false` on failure. If `option` is not
212+
* implemented, `false` should be returned.
213+
*/
214+
abstract public function stream_set_option(int $option, int $arg1, int $arg2): bool;
215+
216+
/**
217+
* Retrieve information about a file resource
218+
*
219+
* This method is called in response to {@see fstat()}.
220+
*
221+
* @return mixed[]|false
222+
*/
223+
abstract public function stream_stat();
224+
225+
/**
226+
* Retrieve the current position of a stream
227+
*
228+
* This method is called in response to {@see fseek()}.
229+
*/
230+
abstract public function stream_tell(): int;
231+
232+
/**
233+
* Truncate stream
234+
*
235+
* This method is called in response to {@see ftruncate()}.
236+
*
237+
* @return bool `true` on success or `false` on failure.
238+
*/
239+
abstract public function stream_truncate(int $new_size): bool;
240+
241+
/**
242+
* Write to stream
243+
*
244+
* This method is called in response to {@see fwrite()}.
245+
*
246+
* > Remember to update the current position of the stream by number of
247+
* > bytes that were successfully written.
248+
*
249+
* @param string $data Should be stored into the underlying stream. If there
250+
* is not enough room in the underlying stream, store as much as possible.
251+
* @return int The number of bytes that were successfully stored, or `0` if
252+
* none could be stored.
253+
*/
254+
abstract public function stream_write(string $data): int;
255+
256+
/**
257+
* Retrieve information about a file
258+
*
259+
* This method is called in response to all {@see stat()} related functions.
260+
*
261+
* @param string $path The file path or URL to stat. Note that in the case
262+
* of a URL, it must be a :// delimited URL. Other URL forms are not
263+
* supported.
264+
* @param int $flags Holds additional flags set by the streams API. It can
265+
* hold one or more of the following values OR'd together.
266+
*
267+
* - {@see \STREAM_URL_STAT_LINK}: For resources with the ability to link to
268+
* other resource (such as an HTTP Location: forward, or a filesystem
269+
* symlink). This flag specified that only information about the link
270+
* itself should be returned, not the resource pointed to by the link.
271+
* This flag is set in response to calls to {@see lstat()},
272+
* {@see is_link()}, or {@see filetype()}.
273+
* - {@see \STREAM_URL_STAT_QUIET}: If this flag is set, your wrapper should
274+
* not raise any errors. If this flag is not set, you are responsible for
275+
* reporting errors using the {@see trigger_error()} function.
276+
* @return mixed[]|false `false` on failure, otherwise an `array` with the
277+
* same elements returned by {@see stat()}. Unknown or unavailable values
278+
* should be set to a rational value (usually `0`). Special attention should
279+
* be paid to `mode` as documented under {@see stat()}.
280+
*/
281+
abstract public function url_stat(string $path, int $flags);
20282
}

0 commit comments

Comments
 (0)