1<?php 2 3/** 4 * Hoa 5 * 6 * 7 * @license 8 * 9 * New BSD License 10 * 11 * Copyright © 2007-2017, Hoa community. All rights reserved. 12 * 13 * Redistribution and use in source and binary forms, with or without 14 * modification, are permitted provided that the following conditions are met: 15 * * Redistributions of source code must retain the above copyright 16 * notice, this list of conditions and the following disclaimer. 17 * * Redistributions in binary form must reproduce the above copyright 18 * notice, this list of conditions and the following disclaimer in the 19 * documentation and/or other materials provided with the distribution. 20 * * Neither the name of the Hoa nor the names of its contributors may be 21 * used to endorse or promote products derived from this software without 22 * specific prior written permission. 23 * 24 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 25 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 26 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 27 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS AND CONTRIBUTORS BE 28 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 29 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 30 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 31 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 32 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 33 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 34 * POSSIBILITY OF SUCH DAMAGE. 35 */ 36 37namespace Hoa\Stream\Wrapper\IWrapper; 38 39/** 40 * Interface \Hoa\Stream\Wrapper\IWrapper\Stream. 41 * 42 * Interface for “stream stream wrapper” class. 43 * 44 * @copyright Copyright © 2007-2017 Hoa community 45 * @license New BSD License 46 */ 47interface Stream 48{ 49 /** 50 * Retrieve the underlaying resource. 51 * 52 * @param int $castAs Can be STREAM_CAST_FOR_SELECT when 53 * stream_select() is calling stream_cast() or 54 * STREAM_CAST_AS_STREAM when stream_cast() is 55 * called for other uses. 56 * @return resource 57 */ 58 public function stream_cast($castAs); 59 60 /** 61 * Close a resource. 62 * This method is called in response to fclose(). 63 * All resources that were locked, or allocated, by the wrapper should be 64 * released. 65 * 66 * @return void 67 */ 68 public function stream_close(); 69 70 /** 71 * Tests for end-of-file on a file pointer. 72 * This method is called in response to feof(). 73 * 74 * @return bool 75 */ 76 public function stream_eof(); 77 78 /** 79 * Flush the output. 80 * This method is called in response to fflush(). 81 * If we have cached data in our stream but not yet stored it into the 82 * underlying storage, we should do so now. 83 * 84 * @return bool 85 */ 86 public function stream_flush(); 87 88 /** 89 * Advisory file locking. 90 * This method is called in response to flock(), when file_put_contents() 91 * (when flags contains LOCK_EX), stream_set_blocking() and when closing the 92 * stream (LOCK_UN). 93 * 94 * @param int $operation Operation is one the following: 95 * * LOCK_SH to acquire a shared lock (reader) ; 96 * * LOCK_EX to acquire an exclusive lock (writer) ; 97 * * LOCK_UN to release a lock (shared or exclusive) ; 98 * * LOCK_NB if we don't want flock() to 99 * block while locking (not supported on 100 * Windows). 101 * @return bool 102 */ 103 public function stream_lock($operation); 104 105 /** 106 * Change stream options. 107 * This method is called to set metadata on the stream. It is called when 108 * one of the following functions is called one a stream URL: touch, chmod, 109 * chown or chgrp. 110 * 111 * @param string $path The file path or URL to set metadata. 112 * @param int $option One of the following: 113 * * STREAM_META_TOUCH, 114 * * STREAM_META_OWNER_NAME, 115 * * STREAM_META_OWNER, 116 * * STREAM_META_GROUP_NAME, 117 * * STREAM_META_GROUP, 118 * * STREAM_META_ACCESS. 119 * @param mixed $value An array or a scalar depending of the option. 120 * @return bool 121 */ 122 public function stream_metadata($path, $option, $value); 123 124 /** 125 * Open file or URL. 126 * This method is called immediately after the wrapper is initialized (f.e. 127 * by fopen() and file_get_contents()). 128 * 129 * @param string $path Specifies the URL that was passed to the 130 * original function. 131 * @param string $mode The mode used to open the file, as 132 * detailed for fopen(). 133 * @param int $options Holds additional flags set by the 134 * streams API. It can hold one or more of 135 * the following values OR'd together: 136 * * STREAM_USE_PATH, if path is relative, 137 * search for the resource using the 138 * include_path; 139 * * STREAM_REPORT_ERRORS, if this is 140 * set, you are responsible for raising 141 * errors using trigger_error during 142 * opening the stream. If this is not 143 * set, you should not raise any errors. 144 * @param string &$openedPath If the $path is opened successfully, and 145 * STREAM_USE_PATH is set in $options, 146 * $openedPath should be set to the full 147 * path of the file/resource that was 148 * actually opened. 149 * @return bool 150 */ 151 public function stream_open($path, $mode, $options, &$openedPath); 152 153 /** 154 * Read from stream. 155 * This method is called in response to fread() and fgets(). 156 * 157 * @param int $count How many bytes of data from the current 158 * position should be returned. 159 * @return string 160 */ 161 public function stream_read($count); 162 163 /** 164 * Seek to specific location in a stream. 165 * This method is called in response to fseek(). 166 * The read/write position of the stream should be updated according to the 167 * $offset and $whence. 168 * 169 * @param int $offset The stream offset to seek to. 170 * @param int $whence Possible values: 171 * * SEEK_SET to set position equal to $offset 172 * bytes ; 173 * * SEEK_CUR to set position to current 174 * location plus $offsete ; 175 * * SEEK_END to set position to end-of-file 176 * plus $offset. 177 * @return bool 178 */ 179 public function stream_seek($offset, $whence = SEEK_SET); 180 181 /** 182 * Change stream options. 183 * This method is called to set options on the stream. 184 * 185 * @param int $option One of: 186 * * STREAM_OPTION_BLOCKING, the method was 187 * called in response to 188 * stream_set_blocking() ; 189 * * STREAM_OPTION_READ_TIMEOUT, the method 190 * was called in response to 191 * stream_set_timeout() ; 192 * * STREAM_OPTION_WRITE_BUFFER, the method 193 * was called in response to 194 * stream_set_write_buffer(). 195 * @param int $arg1 If $option is: 196 * * STREAM_OPTION_BLOCKING: requested blocking 197 * mode (1 meaning block, 0 not blocking) ; 198 * * STREAM_OPTION_READ_TIMEOUT: the timeout 199 * in seconds ; 200 * * STREAM_OPTION_WRITE_BUFFER: buffer mode 201 * (STREAM_BUFFER_NONE or 202 * STREAM_BUFFER_FULL). 203 * @param int $arg2 If $option is: 204 * * STREAM_OPTION_BLOCKING: this option is 205 * not set ; 206 * * STREAM_OPTION_READ_TIMEOUT: the timeout 207 * in microseconds ; 208 * * STREAM_OPTION_WRITE_BUFFER: the requested 209 * buffer size. 210 * @return bool 211 */ 212 public function stream_set_option($option, $arg1, $arg2); 213 214 /** 215 * Retrieve information about a file resource. 216 * This method is called in response to fstat(). 217 * 218 * @return array 219 */ 220 public function stream_stat(); 221 222 /** 223 * Retrieve the current position of a stream. 224 * This method is called in response to ftell(). 225 * 226 * @return int 227 */ 228 public function stream_tell(); 229 230 /** 231 * Truncate a stream to a given length. 232 * 233 * @param int $size Size. 234 * @return bool 235 */ 236 public function stream_truncate($size); 237 238 /** 239 * Write to stream. 240 * This method is called in response to fwrite(). 241 * 242 * @param string $data Should be stored into the underlying stream. 243 * @return int 244 */ 245 public function stream_write($data); 246} 247