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

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.10 $ -->
 <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
     opperations 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>
    <simpara>
     A <literal>filter</literal> is a final piece of code which may perform
     opperations 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>
    <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.requirements">
    &reftitle.required;
    &no.requirement;
   </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.configuration">
    &reftitle.runtime;
    &no.config;
   </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>

   <section id="stream.constants">
    &reftitle.constants;
    <para>
     <informaltable>
      <tgroup cols="2">
       <thead>
        <row>
         <entry>Constant</entry>
         <entry>Description</entry>
        </row>
       </thead>
       <tbody>
        <row>
         <entry><constant>STREAM_FILTER_READ</constant></entry>
         <entry>
          Used with <function>stream_filter_append</function> and
          <function>stream_filter_prepend</function> to indicate
          that the specified filter should only be applied when
          <emphasis>reading</emphasis>
         </entry>
        </row>
        <row>
         <entry><constant>STREAM_FILTER_WRITE</constant></entry>
         <entry>
          Used with <function>stream_filter_append</function> and
          <function>stream_filter_prepend</function> to indicate
          that the specified filter should only be applied when
          <emphasis>writting</emphasis>
         </entry>
        </row>
        <row>
         <entry><constant>STREAM_FILTER_ALL</constant></entry>
         <entry>
          This constant is equivalent to 
          <literal><constant>STREAM_FILTER_READ</constant> |
          <constant>STREAM_FILTER_WRITE</constant></literal>
         </entry>
        </row>
        <row>
         <entry><constant>STREAM_USE_PATH</constant></entry>
         <entry><literal>Flag</literal> indicating if the <literal>stream</literal>
          used the include path.
         </entry>
        </row>
        <row>
         <entry><constant>STREAM_REPORT_ERRORS</constant></entry>
         <entry><literal>Flag</literal> indicating if the <literal>wrapper</literal>
          is responsible for raising errors using <function>trigger_error</function> 
          during opening of the stream.  If this flag is not set, you
          should not raise any errors.
         </entry>
        </row>
       </tbody>
      </tgroup>
     </informaltable>
    </para>
   </section>

   <section id="stream.errors">
    <title>Stream Errors</title>
    <para>
     As with any file or socket related function, an opperation 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
-->