diff --git a/reference/stream/book.xml b/reference/stream/book.xml new file mode 100644 index 0000000000..8223710d55 --- /dev/null +++ b/reference/stream/book.xml @@ -0,0 +1,91 @@ + + + + + + + Stream &Functions; + Streams + + + &reftitle.intro; + + Streams were introduced with PHP 4.3.0 as + a way of generalizing file, network, data compression, and other + operations which share a common set of functions and uses. In + its simplest definition, a stream is a + resource object which exhibits streamable + behavior. That is, it can be read from or written to in a linear + fashion, and may be able to fseek to an + arbitrary locations within the stream. + + + A wrapper is additional code which tells the stream how to handle + specific protocols/encodings. For example, the http + wrapper knows how to translate a URL into an HTTP/1.0 + request for a file on a remote server. There are many wrappers + built into PHP by default (See ), + and additional, custom wrappers may be added either within a + PHP script using stream_wrapper_register, + or directly from an extension using the API Reference in . + Because any variety of wrapper may be added to PHP, + there is no set limit on what can be done with them. To access the list + of currently registered wrappers, use stream_get_wrappers. + + + A stream is referenced as: scheme://target + + + + scheme(string) - + The name of the wrapper to be used. Examples include: file, + http, https, ftp, ftps, compress.zlib, compress.bz2, and php. See + for a list of PHP built-in wrappers. If + no wrapper is specified, the function default is used (typically + file://). + + + + + target - + Depends on the wrapper used. For filesystem related streams this is + typically a path and filename of the desired file. For network related + streams this is typically a hostname, often with a path appended. Again, see + for a description of targets for built-in streams. + + + + + + + &reference.stream.setup; + &reference.stream.constants; + &reference.stream.filters; + &reference.stream.contexts; + &reference.stream.errors; + &reference.stream.examples; + &reference.stream.reference; + + + + + diff --git a/reference/stream/constants.xml b/reference/stream/constants.xml index fe88bf1925..ad50145447 100644 --- a/reference/stream/constants.xml +++ b/reference/stream/constants.xml @@ -1,6 +1,6 @@ - -
+ + &reftitle.constants; &extension.constants; @@ -315,7 +315,7 @@ constants might not be available in your system. -
+ - diff --git a/reference/stream/contexts.xml b/reference/stream/contexts.xml new file mode 100644 index 0000000000..b0792cccf6 --- /dev/null +++ b/reference/stream/contexts.xml @@ -0,0 +1,74 @@ + + + + + Stream Contexts + + A context is a set of parameters and + wrapper specific options which modify or enhance the + behavior of a stream. Contexts are created using + stream_context_create and can be passed to most + filesystem related stream creation functions (i.e. fopen, + file, file_get_contents, etc...). + + + Options can be specified when calling + stream_context_create, or later using + stream_context_set_option. + + A list of wrapper specific options can be found with + the list of built-in wrappers (See ). + + + In addition, parameters may be set on a context + using stream_context_set_params. Currently the only + context parameter supported by PHP is + notification. The value of this parameter must be the + name of a function to be called when an event occurs on a stream. + The notification function called during an event should accept the following + six parameters: + + + voidmy_notifier + intnotification_code + intseverity + stringmessage + intmessage_code + intbytes_transferred + intbytes_max + + + notification_code and severity + are numerical values which correspond to the STREAM_NOTIFY_* + constants listed below. + + If a descriptive message is available from the stream, message + and message_code will be populated with the appropriate values. + The meaning of these values is dependent on the specific wrapper in use. + + bytes_transferred and bytes_max will + be populated when applicable. + + + + + diff --git a/reference/stream/errors.xml b/reference/stream/errors.xml new file mode 100644 index 0000000000..54732e3a86 --- /dev/null +++ b/reference/stream/errors.xml @@ -0,0 +1,38 @@ + + + + + Stream Errors + + As with any file or socket related function, an operation on a stream + may fail for a variety of normal reasons (i.e.: Unable to connect to remote + host, file not found, etc...). A stream related call may also fail because + the desired stream is not registered on the running system. See the array returned + by stream_get_wrappers for a list of streams supported by your + installation of PHP. As with most PHP internal functions + if a failure occurs an E_WARNING message will be generated + describing the nature of the error. + + + + + diff --git a/reference/stream/examples.xml b/reference/stream/examples.xml new file mode 100644 index 0000000000..3d7340b79a --- /dev/null +++ b/reference/stream/examples.xml @@ -0,0 +1,117 @@ + + + + &reftitle.examples; + + + Using <function>file_get_contents</function> + to retrieve data from multiple sources + + +]]> + + + + + + Making a POST request to an https server + + +]]> + + + + + + Writing data to a compressed file + + +]]> + + + + + + + diff --git a/reference/stream/filters.xml b/reference/stream/filters.xml new file mode 100644 index 0000000000..4ad1af95ea --- /dev/null +++ b/reference/stream/filters.xml @@ -0,0 +1,37 @@ + + + + + Stream Filters + + A filter is a final piece of code which may perform + operations on data as it is being read from or written to a stream. + Any number of filters may be stacked onto a stream. Custom + filters can be defined in a PHP script using + stream_filter_register or in an extension using the + API Reference in . To access the list of currently + registered filters, use stream_get_filters. + + + + + diff --git a/reference/stream/reference.xml b/reference/stream/reference.xml index 72b4bcac6c..bc891d0132 100644 --- a/reference/stream/reference.xml +++ b/reference/stream/reference.xml @@ -1,264 +1,13 @@ - - - + - - Stream Functions - Streams + + Streams &Functions; - + &reference.stream.entities.functions; -
- &reftitle.intro; - - Streams were introduced with PHP 4.3.0 as - a way of generalizing file, network, data compression, and other - operations which share a common set of functions and uses. In - its simplest definition, a stream is a - resource object which exhibits streamable - behavior. That is, it can be read from or written to in a linear - fashion, and may be able to fseek to an - arbitrary locations within the stream. - - - A wrapper is additional code which tells the stream how to handle - specific protocols/encodings. For example, the http - wrapper knows how to translate a URL into an HTTP/1.0 - request for a file on a remote server. There are many wrappers - built into PHP by default (See ), - and additional, custom wrappers may be added either within a - PHP script using stream_wrapper_register, - or directly from an extension using the API Reference in . - Because any variety of wrapper may be added to PHP, - there is no set limit on what can be done with them. To access the list - of currently registered wrappers, use stream_get_wrappers. - - - A stream is referenced as: scheme://target - - - - scheme(string) - - The name of the wrapper to be used. Examples include: file, - http, https, ftp, ftps, compress.zlib, compress.bz2, and php. See - for a list of PHP built-in wrappers. If - no wrapper is specified, the function default is used (typically - file://). - - - - - target - - Depends on the wrapper used. For filesystem related streams this is - typically a path and filename of the desired file. For network related - streams this is typically a hostname, often with a path appended. Again, see - for a description of targets for built-in streams. - - - - -
+
-
- Stream Filters - - A filter is a final piece of code which may perform - operations on data as it is being read from or written to a stream. - Any number of filters may be stacked onto a stream. Custom - filters can be defined in a PHP script using - stream_filter_register or in an extension using the - API Reference in . To access the list of currently - registered filters, use stream_get_filters. - -
- -
- Stream Contexts - - A context is a set of parameters and - wrapper specific options which modify or enhance the - behavior of a stream. Contexts are created using - stream_context_create and can be passed to most - filesystem related stream creation functions (i.e. fopen, - file, file_get_contents, etc...). - - - Options can be specified when calling - stream_context_create, or later using - stream_context_set_option. - - A list of wrapper specific options can be found with - the list of built-in wrappers (See ). - - - In addition, parameters may be set on a context - using stream_context_set_params. Currently the only - context parameter supported by PHP is - notification. The value of this parameter must be the - name of a function to be called when an event occurs on a stream. - The notification function called during an event should accept the following - six parameters: - - - voidmy_notifier - intnotification_code - intseverity - stringmessage - intmessage_code - intbytes_transferred - intbytes_max - - - notification_code and severity - are numerical values which correspond to the STREAM_NOTIFY_* - constants listed below. - - If a descriptive message is available from the stream, message - and message_code will be populated with the appropriate values. - The meaning of these values is dependent on the specific wrapper in use. - - bytes_transferred and bytes_max will - be populated when applicable. - -
- -
- &reftitle.install; - - Streams are an integral part of PHP as of version 4.3.0. No steps are - required to enable them. - -
- -
- Stream Classes - - User designed wrappers can be registered via stream_wrapper_register, - using the class definition shown on that manual page. - - - class php_user_filter is predefined and is an abstract - baseclass for use with user defined filters. See the manual page for - stream_filter_register for details on implementing - user defined filters. - -
- - &reference.stream.constants; - -
- Stream Errors - - As with any file or socket related function, an operation on a stream - may fail for a variety of normal reasons (i.e.: Unable to connect to remote - host, file not found, etc...). A stream related call may also fail because - the desired stream is not registered on the running system. See the array returned - by stream_get_wrappers for a list of streams supported by your - installation of PHP. As with most PHP internal functions - if a failure occurs an E_WARNING message will be generated - describing the nature of the error. - -
- -
- &reftitle.examples; - - - Using <function>file_get_contents</function> - to retrieve data from multiple sources - - -]]> - - - - - - Making a POST request to an https server - - -]]> - - - - - - Writing data to a compressed file - - -]]> - - - -
- - -&reference.stream.entities.functions; - -
+ + &reftitle.setup; + +
+ &reftitle.required; + &no.requirement; +
+ +
+ &reftitle.install; + + Streams are an integral part of PHP as of version 4.3.0. No steps are + required to enable them. + +
+ +
+ &reftitle.runtime; + &no.config; +
+ +
+ Stream Classes + + User designed wrappers can be registered via stream_wrapper_register, + using the class definition shown on that manual page. + + + class php_user_filter is predefined and is an abstract + baseclass for use with user defined filters. See the manual page for + stream_filter_register for details on implementing + user defined filters. + +
+ +
+ + +