php-doc-en/reference/stream/reference.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.14 $ -->
 <reference id="ref.stream">
  <title>Stream functions</title>
  <titleabbrev>Streams</titleabbrev>

  <partintro>

   <section id="stream.intro">
    &reftitle.intro;
    <simpara>
     Streams were introduced with <literal>PHP</literal> 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 <literal>PHP</literal> by default (See <xref linkend="wrappers"/>),
     and additional, custom wrappers may be added either within a
     PHP script using <function>stream_register_wrapper</function>,
     or directly from an extension using the API Reference in <xref linkend="streams"/>.
     Because any variety of wrapper may be added to <literal>PHP</literal>, 
     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 <literal>PHP</literal> script using
     <function>stream_register_filter</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 realted 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 <literal>PHP</literal> 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 dependant 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 <literal>PHP</literal>
     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_register_wrapper</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_register_filter</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 <literal>PHP</literal>.  As with most PHP internal functions
     if a failure occours 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");

fputs($sock, "POST /form_action.php HTTP/1.0\r\n");
fputs($sock, "Host: secure.example.com\r\n");
fputs($sock, "Content-type: application/x-www-url-encoded\r\n");
fputs($sock, "Content-length: " . strlen($data) . "\r\n");
fputs($sock, "Accept: */*\r\n");
fputs($sock, "\r\n");
fputs($sock, "$data\r\n");
fputs($sock, "\r\n");

$headers = "";
while ($str = trim(fgets($sock, 4096)))
  $headers .= "$str\n";

print "\n";

$body = "";
while (!feof($sock))
  $body .= fgets($sock, 4096);

fclose($sock);
?>
]]>
      </programlisting>
     </example>
    </para>
    <para>
     <example>
      <title>Writting 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
-->