MFB: Upgrade to the new-reference-structure

- Split reference.xml into book.xml and setup.xml
- Moved from reference.xml to book.xml:
  - The intro text (partintro), link to constants and:
  - Linked to new chapters: contexts, errors, examples, and filters
- Moved from reference.xml to setup.xml:
  - The setup: requirements, installation, configuration, and resources
- Changed the constants section to be an <appendix>
- Changed the intro ID from <extname>.intro to intro.<extname>


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@248588 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Philip Olson 2007-12-19 22:44:25 +00:00
parent 96510a663e
commit c838b3e026
8 changed files with 425 additions and 260 deletions

91
reference/stream/book.xml Normal file
View file

@ -0,0 +1,91 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
<!-- Purpose: remote.other -->
<!-- Membership: core -->
<book xml:id="book.stream" xmlns="http://docbook.org/ns/docbook">
<title>Stream &Functions;</title>
<titleabbrev>Streams</titleabbrev>
<preface xml:id="intro.stream">
&reftitle.intro;
<simpara>
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 <literal>stream</literal> is a
<literal>resource</literal> object which exhibits streamable
behavior. That is, it can be read from or written to in a linear
fashion, and may be able to <function>fseek</function> to an
arbitrary locations within the stream.
</simpara>
<simpara>
A <literal>wrapper</literal> is additional code which tells the stream how to handle
specific protocols/encodings. For example, the <literal>http</literal>
wrapper knows how to translate a URL into an <literal>HTTP/1.0</literal>
request for a file on a remote server. There are many wrappers
built into PHP by default (See <xref linkend="wrappers"/>),
and additional, custom wrappers may be added either within a
PHP script using <function>stream_wrapper_register</function>,
or directly from an extension using the API Reference in <xref linkend="internals2.streams"/>.
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 <function>stream_get_wrappers</function>.
</simpara>
<para>
A stream is referenced as: <parameter>scheme</parameter>://<parameter>target</parameter>
<itemizedlist>
<listitem>
<simpara>
<parameter>scheme</parameter>(string) -
The name of the wrapper to be used. Examples include: file,
http, https, ftp, ftps, compress.zlib, compress.bz2, and php. See
<xref linkend="wrappers"/> for a list of PHP built-in wrappers. If
no wrapper is specified, the function default is used (typically
<literal>file</literal>://).
</simpara>
</listitem>
<listitem>
<simpara>
<parameter>target</parameter> -
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
<xref linkend="wrappers"/> for a description of targets for built-in streams.
</simpara>
</listitem>
</itemizedlist>
</para>
</preface>
&reference.stream.setup;
&reference.stream.constants;
&reference.stream.filters;
&reference.stream.contexts;
&reference.stream.errors;
&reference.stream.examples;
&reference.stream.reference;
</book>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -1,6 +1,6 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.16 $ -->
<section xml:id="stream.constants" xmlns="http://docbook.org/ns/docbook">
<!-- $Revision: 1.17 $ -->
<appendix xml:id="stream.constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.constants;
&extension.constants;
<para>
@ -315,7 +315,7 @@
constants might not be available in your system.
</simpara>
</note>
</section>
</appendix>
<!-- Keep this comment at the end of the file
Local variables:
@ -338,4 +338,3 @@ vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,74 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
<chapter xml:id="stream.contexts">
<title>Stream Contexts</title>
<simpara>
A <literal>context</literal> is a set of <literal>parameters</literal> and
wrapper specific <literal>options</literal> which modify or enhance the
behavior of a stream. <literal>Contexts</literal> are created using
<function>stream_context_create</function> and can be passed to most
filesystem related stream creation functions (i.e. <function>fopen</function>,
<function>file</function>, <function>file_get_contents</function>, etc...).
</simpara>
<simpara>
<literal>Options</literal> can be specified when calling
<function>stream_context_create</function>, or later using
<function>stream_context_set_option</function>.
A list of wrapper specific <literal>options</literal> can be found with
the list of built-in wrappers (See <xref linkend="wrappers"/>).
</simpara>
<simpara>
In addition, <literal>parameters</literal> may be set on a <literal>context</literal>
using <function>stream_context_set_params</function>. Currently the only
<literal>context parameter</literal> supported by PHP is
<literal>notification</literal>. 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:
</simpara>
<methodsynopsis>
<type>void</type><methodname>my_notifier</methodname>
<methodparam><type>int</type><parameter>notification_code</parameter></methodparam>
<methodparam><type>int</type><parameter>severity</parameter></methodparam>
<methodparam><type>string</type><parameter>message</parameter></methodparam>
<methodparam><type>int</type><parameter>message_code</parameter></methodparam>
<methodparam><type>int</type><parameter>bytes_transferred</parameter></methodparam>
<methodparam><type>int</type><parameter>bytes_max</parameter></methodparam>
</methodsynopsis>
<simpara>
<parameter>notification_code</parameter> and <parameter>severity</parameter>
are numerical values which correspond to the <constant>STREAM_NOTIFY_*</constant>
constants listed below.
If a descriptive message is available from the stream, <parameter>message</parameter>
and <parameter>message_code</parameter> will be populated with the appropriate values.
The meaning of these values is dependent on the specific wrapper in use.
<parameter>bytes_transferred</parameter> and <parameter>bytes_max</parameter> will
be populated when applicable.
</simpara>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,38 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
<chapter xml:id="stream.errors">
<title>Stream Errors</title>
<para>
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 <function>stream_get_wrappers</function> for a list of streams supported by your
installation of PHP. As with most PHP internal functions
if a failure occurs an <constant>E_WARNING</constant> message will be generated
describing the nature of the error.
</para>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,117 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
<chapter xml:id="stream.examples">
&reftitle.examples;
<para>
<example>
<title>Using <function>file_get_contents</function>
to retrieve data from multiple sources</title>
<programlisting role="php">
<![CDATA[
<?php
/* Read local file from /home/bar */
$localfile = file_get_contents("/home/bar/foo.txt");
/* Identical to above, explicitly naming FILE scheme */
$localfile = file_get_contents("file:///home/bar/foo.txt");
/* Read remote file from www.example.com using HTTP */
$httpfile = file_get_contents("http://www.example.com/foo.txt");
/* Read remote file from www.example.com using HTTPS */
$httpsfile = file_get_contents("https://www.example.com/foo.txt");
/* Read remote file from ftp.example.com using FTP */
$ftpfile = file_get_contents("ftp://user:pass@ftp.example.com/foo.txt");
/* Read remote file from ftp.example.com using FTPS */
$ftpsfile = file_get_contents("ftps://user:pass@ftp.example.com/foo.txt");
?>
]]>
</programlisting>
</example>
</para>
<para>
<example>
<title>Making a POST request to an https server</title>
<programlisting role="php">
<![CDATA[
<?php
/* Send POST request to https://secure.example.com/form_action.php
* Include form elements named "foo" and "bar" with dummy values
*/
$sock = fsockopen("ssl://secure.example.com", 443, $errno, $errstr, 30);
if (!$sock) die("$errstr ($errno)\n");
$data = "foo=" . urlencode("Value for Foo") . "&bar=" . urlencode("Value for Bar");
fwrite($sock, "POST /form_action.php HTTP/1.0\r\n");
fwrite($sock, "Host: secure.example.com\r\n");
fwrite($sock, "Content-type: application/x-www-form-urlencoded\r\n");
fwrite($sock, "Content-length: " . strlen($data) . "\r\n");
fwrite($sock, "Accept: */*\r\n");
fwrite($sock, "\r\n");
fwrite($sock, "$data\r\n");
fwrite($sock, "\r\n");
$headers = "";
while ($str = trim(fgets($sock, 4096)))
$headers .= "$str\n";
echo "\n";
$body = "";
while (!feof($sock))
$body .= fgets($sock, 4096);
fclose($sock);
?>
]]>
</programlisting>
</example>
</para>
<para>
<example>
<title>Writing data to a compressed file</title>
<programlisting role="php">
<![CDATA[
<?php
/* Create a compressed file containing an arbitrarty string
* File can be read back using compress.zlib stream or just
* decompressed from the command line using 'gzip -d foo-bar.txt.gz'
*/
$fp = fopen("compress.zlib://foo-bar.txt.gz", "wb");
if (!$fp) die("Unable to create file.");
fwrite($fp, "This is a test.\n");
fclose($fp);
?>
]]>
</programlisting>
</example>
</para>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,37 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
<chapter xml:id="stream.filters">
<title>Stream Filters</title>
<simpara>
A <literal>filter</literal> 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
<function>stream_filter_register</function> or in an extension using the
API Reference in <xref linkend="internals2.streams"/>. To access the list of currently
registered filters, use <function>stream_get_filters</function>.
</simpara>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -1,264 +1,13 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.28 $ -->
<!-- Purpose: remote.other -->
<!-- Membership: core -->
<!-- $Revision: 1.29 $ -->
<reference xml:id="ref.stream" xmlns="http://docbook.org/ns/docbook">
<title>Stream Functions</title>
<titleabbrev>Streams</titleabbrev>
<reference xml:id="ref.stream" xmlns="http://docbook.org/ns/docbook">
<title>Streams &Functions;</title>
<partintro>
&reference.stream.entities.functions;
<section xml:id="stream.intro">
&reftitle.intro;
<simpara>
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 <literal>stream</literal> is a
<literal>resource</literal> object which exhibits streamable
behavior. That is, it can be read from or written to in a linear
fashion, and may be able to <function>fseek</function> to an
arbitrary locations within the stream.
</simpara>
<simpara>
A <literal>wrapper</literal> is additional code which tells the stream how to handle
specific protocols/encodings. For example, the <literal>http</literal>
wrapper knows how to translate a URL into an <literal>HTTP/1.0</literal>
request for a file on a remote server. There are many wrappers
built into PHP by default (See <xref linkend="wrappers"/>),
and additional, custom wrappers may be added either within a
PHP script using <function>stream_wrapper_register</function>,
or directly from an extension using the API Reference in <xref linkend="internals2.streams"/>.
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 <function>stream_get_wrappers</function>.
</simpara>
<para>
A stream is referenced as: <parameter>scheme</parameter>://<parameter>target</parameter>
<itemizedlist>
<listitem>
<simpara>
<parameter>scheme</parameter>(string) -
The name of the wrapper to be used. Examples include: file,
http, https, ftp, ftps, compress.zlib, compress.bz2, and php. See
<xref linkend="wrappers"/> for a list of PHP built-in wrappers. If
no wrapper is specified, the function default is used (typically
<literal>file</literal>://).
</simpara>
</listitem>
<listitem>
<simpara>
<parameter>target</parameter> -
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
<xref linkend="wrappers"/> for a description of targets for built-in streams.
</simpara>
</listitem>
</itemizedlist>
</para>
</section>
</reference>
<section xml:id="stream.filters">
<title>Stream Filters</title>
<simpara>
A <literal>filter</literal> 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
<function>stream_filter_register</function> or in an extension using the
API Reference in <xref linkend="internals2.streams"/>. To access the list of currently
registered filters, use <function>stream_get_filters</function>.
</simpara>
</section>
<section xml:id="stream.contexts">
<title>Stream Contexts</title>
<simpara>
A <literal>context</literal> is a set of <literal>parameters</literal> and
wrapper specific <literal>options</literal> which modify or enhance the
behavior of a stream. <literal>Contexts</literal> are created using
<function>stream_context_create</function> and can be passed to most
filesystem related stream creation functions (i.e. <function>fopen</function>,
<function>file</function>, <function>file_get_contents</function>, etc...).
</simpara>
<simpara>
<literal>Options</literal> can be specified when calling
<function>stream_context_create</function>, or later using
<function>stream_context_set_option</function>.
A list of wrapper specific <literal>options</literal> can be found with
the list of built-in wrappers (See <xref linkend="wrappers"/>).
</simpara>
<simpara>
In addition, <literal>parameters</literal> may be set on a <literal>context</literal>
using <function>stream_context_set_params</function>. Currently the only
<literal>context parameter</literal> supported by PHP is
<literal>notification</literal>. 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:
</simpara>
<methodsynopsis>
<type>void</type><methodname>my_notifier</methodname>
<methodparam><type>int</type><parameter>notification_code</parameter></methodparam>
<methodparam><type>int</type><parameter>severity</parameter></methodparam>
<methodparam><type>string</type><parameter>message</parameter></methodparam>
<methodparam><type>int</type><parameter>message_code</parameter></methodparam>
<methodparam><type>int</type><parameter>bytes_transferred</parameter></methodparam>
<methodparam><type>int</type><parameter>bytes_max</parameter></methodparam>
</methodsynopsis>
<simpara>
<parameter>notification_code</parameter> and <parameter>severity</parameter>
are numerical values which correspond to the <constant>STREAM_NOTIFY_*</constant>
constants listed below.
If a descriptive message is available from the stream, <parameter>message</parameter>
and <parameter>message_code</parameter> will be populated with the appropriate values.
The meaning of these values is dependent on the specific wrapper in use.
<parameter>bytes_transferred</parameter> and <parameter>bytes_max</parameter> will
be populated when applicable.
</simpara>
</section>
<section xml:id="stream.installation">
&reftitle.install;
<para>
Streams are an integral part of PHP as of version 4.3.0. No steps are
required to enable them.
</para>
</section>
<section xml:id="stream.resources">
<title>Stream Classes</title>
<simpara>
User designed wrappers can be registered via <function>stream_wrapper_register</function>,
using the class definition shown on that manual page.
</simpara>
<simpara>
<literal>class</literal> php_user_filter is predefined and is an abstract
baseclass for use with user defined filters. See the manual page for
<function>stream_filter_register</function> for details on implementing
user defined filters.
</simpara>
</section>
&reference.stream.constants;
<section xml:id="stream.errors">
<title>Stream Errors</title>
<para>
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 <function>stream_get_wrappers</function> for a list of streams supported by your
installation of PHP. As with most PHP internal functions
if a failure occurs an <constant>E_WARNING</constant> message will be generated
describing the nature of the error.
</para>
</section>
<section xml:id="stream.examples">
&reftitle.examples;
<para>
<example>
<title>Using <function>file_get_contents</function>
to retrieve data from multiple sources</title>
<programlisting role="php">
<![CDATA[
<?php
/* Read local file from /home/bar */
$localfile = file_get_contents("/home/bar/foo.txt");
/* Identical to above, explicitly naming FILE scheme */
$localfile = file_get_contents("file:///home/bar/foo.txt");
/* Read remote file from www.example.com using HTTP */
$httpfile = file_get_contents("http://www.example.com/foo.txt");
/* Read remote file from www.example.com using HTTPS */
$httpsfile = file_get_contents("https://www.example.com/foo.txt");
/* Read remote file from ftp.example.com using FTP */
$ftpfile = file_get_contents("ftp://user:pass@ftp.example.com/foo.txt");
/* Read remote file from ftp.example.com using FTPS */
$ftpsfile = file_get_contents("ftps://user:pass@ftp.example.com/foo.txt");
?>
]]>
</programlisting>
</example>
</para>
<para>
<example>
<title>Making a POST request to an https server</title>
<programlisting role="php">
<![CDATA[
<?php
/* Send POST request to https://secure.example.com/form_action.php
* Include form elements named "foo" and "bar" with dummy values
*/
$sock = fsockopen("ssl://secure.example.com", 443, $errno, $errstr, 30);
if (!$sock) die("$errstr ($errno)\n");
$data = "foo=" . urlencode("Value for Foo") . "&bar=" . urlencode("Value for Bar");
fwrite($sock, "POST /form_action.php HTTP/1.0\r\n");
fwrite($sock, "Host: secure.example.com\r\n");
fwrite($sock, "Content-type: application/x-www-form-urlencoded\r\n");
fwrite($sock, "Content-length: " . strlen($data) . "\r\n");
fwrite($sock, "Accept: */*\r\n");
fwrite($sock, "\r\n");
fwrite($sock, "$data\r\n");
fwrite($sock, "\r\n");
$headers = "";
while ($str = trim(fgets($sock, 4096)))
$headers .= "$str\n";
echo "\n";
$body = "";
while (!feof($sock))
$body .= fgets($sock, 4096);
fclose($sock);
?>
]]>
</programlisting>
</example>
</para>
<para>
<example>
<title>Writing data to a compressed file</title>
<programlisting role="php">
<![CDATA[
<?php
/* Create a compressed file containing an arbitrarty string
* File can be read back using compress.zlib stream or just
* decompressed from the command line using 'gzip -d foo-bar.txt.gz'
*/
$fp = fopen("compress.zlib://foo-bar.txt.gz", "wb");
if (!$fp) die("Unable to create file.");
fwrite($fp, "This is a test.\n");
fclose($fp);
?>
]]>
</programlisting>
</example>
</para>
</section>
</partintro>
&reference.stream.entities.functions;
</reference>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml

View file

@ -0,0 +1,60 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
<chapter xml:id="stream.setup" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.setup;
<section xml:id="stream.requirements">
&reftitle.required;
&no.requirement;
</section>
<section xml:id="stream.installation">
&reftitle.install;
<para>
Streams are an integral part of PHP as of version 4.3.0. No steps are
required to enable them.
</para>
</section>
<section xml:id="stream.configuration">
&reftitle.runtime;
&no.config;
</section>
<section xml:id="stream.resources">
<title>Stream Classes</title>
<simpara>
User designed wrappers can be registered via <function>stream_wrapper_register</function>,
using the class definition shown on that manual page.
</simpara>
<simpara>
<literal>class</literal> php_user_filter is predefined and is an abstract
baseclass for use with user defined filters. See the manual page for
<function>stream_filter_register</function> for details on implementing
user defined filters.
</simpara>
</section>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->