CHAPTER 9 – FILES AND STREAMS – User Streams

The streams layer in PHP 5 allows defining User Streams--stream wrappers implemented in PHP code. This User Stream is implemented by a class and, for every file operation (opening, reading, for instance), you need to implement a method. This section describes the methods that must be implemented. 9.2.5.1 boolean stream_open ( string path, string mode, int options, string opened_path); This function is called when fopen() is called on this stream. The path is the full URL as specified in the fopen() call, which you need to interpret correctly. The parseurl() function helps for this. You also need to validate the mode yourself. The options parameter, set by the stream's API, is a bit field consisting of the following constants: STREAM_USE_PATH. This constant is set in the bit field when TRUE was passed as the use_include_path parameter to fopen(). It's up to you to do some- thing with it if needed. STREAM_REPORT_ERRORS. If this constant is set, you need to handle trigger errors yourself with the trigger_error() function; if it's not set, you should not raise any errors yourself. 9.2.5.2 void stream_close ( void ); T h e s t r e a m _ cl o s e m e t h o d i s called when fclose() is called on the stream, or when PHP closes the stream resource during shutdown. You need to take care of releasing any resources that you might have locked or opened. 9.2.5.3 string stream_read ( int count); When fgets() or fread() triggers a read request on the stream, the stream_read method is called in response. You should always try to return count bytes from the stream. If there is not much data available, just return as many bytes as you have left in the stream. If no data is available, return FALSE or an empty string. Do not forget to update the read/write position of the stream. This position is usually stored in the position property of your class. 9.2.5.4 int stream_write ( string data); The stream_write method is called when fputs() or fwrite() is called on this stream. You should store as much of the data as possible, and return the number of bytes that actually were stored in the container. If no data could be stored, you should return 0. You should also take care of updating the position pointer. 9.2.5.5 boolean stream_eof ( void ); This method is called when feof() is called on the stream. Return TRUE if the end of the stream is reached, or FALSE if the end has not been reached yet.

9.2.5.6 int stream_tell ( void ); The stream_tell() method is called on a ftell() request on the stream. You should return the value of the read/ write position pointer. 9.2.5.7 boolean stream_seek ( int offset, int whence); stream_seek is called when fseek() is applied on the stream handle. The offset is an integer value that moves the file pointer (seeking) back (on a negative number) or forward (on a positive number). The seek offset is calculated based on the second parameter, which has one of the following constants: SEEK_SET. The offset passed to the function should be calculated from the beginning. SEEK_CUR. The offset is relative to the current stream position. SEEK_END. The offset is relative to the end of the stream. Positions in the stream have a negative offset; positive offsets correspond with positions after the end of the stream. The function should implement the changing of the stream pointer and return TRUE if the position could be changed, or FALSE if the seek could not be executed. 9.2.5.8 boolean stream_flush ( void ); Your user stream may cache data written to the stream for better performance. The stream_flush() method is called when the user commits all cached data with the fflush() function. If there was no cached data or all cached data could be written to the storage container (such as a file or a table in a database), the function should return TRUE; if the cached data could not be committed to the storage container, it should return FALSE.