mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-19 02:18:56 +00:00
a3f050e977
no more <literal> with PHP (versions) replace literal with meaningful tags where appropriate git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@165937 c90b9560-bf6c-de11-be94-00142212c4b1
278 lines
10 KiB
XML
278 lines
10 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision: 1.23 $ -->
|
|
<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
|
|
-->
|