<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.24 $ -->
<!-- Purpose: remote.other -->
<!-- Membership: core -->

 <reference id="ref.stream">
  <title>Stream Functions</title>
  <titleabbrev>Streams</titleabbrev>

  <partintro>

   <section 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="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 builtin 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 builtin streams.
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
   </section>

   <section 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="streams"/>.  To access the list of currently 
     registered filters, use <function>stream_get_filters</function>.
    </simpara>
   </section>
  
   <section 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 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 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 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 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.functions;

 </reference>
<!-- 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
-->