wez Mon Sep 23 22:53:09 2002 EDT
Modified files:
/phpdoc/en/appendices wrappers.xml
/phpdoc/en/reference/filesystem reference.xml
/phpdoc/en/reference/filesystem/functions fopen.xml
Log:
Make fopen() docs actually readable.
Moved wrapper descriptions into the wrapper appendix.
I plan to add more details, such as the the file_get_wrapper_data()
structures for each wrapper, so this is a positive move in that direction.
Index: phpdoc/en/appendices/wrappers.xml
diff -u phpdoc/en/appendices/wrappers.xml:1.1 phpdoc/en/appendices/wrappers.xml:1.2
--- phpdoc/en/appendices/wrappers.xml:1.1 Mon Sep 16 14:13:37 2002
+++ phpdoc/en/appendices/wrappers.xml Mon Sep 23 22:53:08 2002
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
<appendix id="wrappers">
<title>List of Supported Protocols/Wrappers</title>
<para>
@@ -9,92 +9,139 @@
In addition to these wrappers, as of PHP 4.3, you can write
your own wrappers using PHP script and
<function>file_register_wrapper</function>.
-
- <table>
- <title>URL Wrappers</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Protocol</entry>
- <entry>Versions</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>http://</entry>
- <entry>All</entry>
- <entry>Allows read-only access to files/resources via HTTP.</entry>
- </row>
- <row>
- <entry>https://</entry>
- <entry>PHP 4.3 and up, with SSL support</entry>
- <entry>Allows read-only access to files/resources via SSL secured
- HTTP.
- </entry>
- </row>
- <row>
- <entry>ftp://</entry>
- <entry>All</entry>
- <entry>Allows read access to existing files and creation of new files
- via FTP.
- </entry>
- </row>
- <row>
- <entry>ftps://</entry>
- <entry>PHP 4.3 and up, with SSL support</entry>
- <entry>The same as ftp://, but uses SSL when supported by the FTP server.</entry>
- </row>
- <row>
- <entry>php://stdin</entry>
- <entry>PHP 3.0.13 and up</entry>
- <entry>Allows read acess to the standard input stream of the PHP process.</entry>
- </row>
- <row>
- <entry>php://stdout</entry>
- <entry>PHP 3.0.13 and up</entry>
- <entry>Allows write acess to the standard output stream of the PHP
process.</entry>
- </row>
- <row>
- <entry>php://stderr</entry>
- <entry>PHP 3.0.13 and up</entry>
- <entry>Allows write acess to the standard error stream of the PHP
process.</entry>
- </row>
- <row>
- <entry>php://output</entry>
- <entry>PHP 4.3 and up</entry>
- <entry>Allows write acess to the output buffer mechanism, just like
- <function>echo</function> and <function>print</function>.
- </entry>
- </row>
- <row>
- <entry>zlib:</entry>
- <entry>PHP 4.0.4 - PHP 4.2.3, systems with fopencookie only</entry>
- <entry>Works like <function>gzopen</function>, except that the
- stream can be used with <function>fread</function> and the other
- filesystem functions. This is deprecated as of PHP 4.3 due
- to ambiguities with filenames containing ':' characters; use
- compress.zlib:// instead.
- </entry>
- </row>
- <row>
- <entry>compress.zlib://</entry>
- <entry>PHP 4.3 and up</entry>
- <entry>Works just like <function>gzopen</function>, even on systems
- without fopencookie.
- </entry>
- </row>
- <row>
- <entry>compress.bzip2://</entry>
- <entry>PHP 4.3 and up</entry>
- <entry>Works just like <function>bzopen</function>.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
</para>
+
+ <section id="wrappers.http">
+ <title>HTTP and HTTPS</title>
+ <simpara>PHP 3, PHP 4. https:// since PHP 4.3</simpara>
+
+ <itemizedlist>
+ <listitem><simpara>http://example.com</simpara></listitem>
+ <listitem><simpara>http://user:[EMAIL PROTECTED]</simpara></listitem>
+ <listitem><simpara>https://example.com</simpara></listitem>
+ <listitem><simpara>https://user:[EMAIL PROTECTED]</simpara></listitem>
+ </itemizedlist>
+
+ <simpara>Allows read-only access to files/resources via HTTP 1.0,
+ using the HTTP GET method. A Host: header is sent with the request
+ to handle name-based virtual hosts. If you have configured
+ a <link linkend="ini.user-agent">user_agent</link> string using
+ your ini file or the stream context, it will also be included
+ in the request.
+ </simpara>
+ <simpara>
+ Redirects have been supported since PHP 4.0.5; if you are using
+ an earlier version you will need to include trailing slashes in
+ your URLs.
+ </simpara>
+ <simpara>
+ The stream allows access to the <emphasis>body</emphasis> of
+ the resource; the headers are stored in the
+ <parameter>$http_response_header</parameter> variable.
+ Since PHP 4.3, the headers are available using
+ <function>file_get_wrapper_data</function>.
+ </simpara>
+ <simpara>
+ HTTP connections are read-only; you cannot write data or copy
+ files to an HTTP resource.
+ </simpara>
+ <note>
+ <simpara>HTTPS is supported starting from PHP 4.3, if you
+ have compiled in support for OpenSSL.
+ </simpara>
+ </note>
+ </section>
+
+ <section id="wrappers.ftp">
+ <title>FTP and FTPS</title>
+ <simpara>PHP 3, PHP 4. ftps:// since PHP 4.3</simpara>
+
+ <itemizedlist>
+ <listitem><simpara>ftp://example.com/pub/file.txt</simpara></listitem>
+
+<listitem><simpara>ftp://user:[EMAIL PROTECTED]/pub/file.txt</simpara></listitem>
+ <listitem><simpara>ftps://example.com/pub/file.txt</simpara></listitem>
+
+<listitem><simpara>ftps://user:[EMAIL PROTECTED]/pub/file.txt</simpara></listitem>
+ </itemizedlist>
+
+ <simpara>
+ Allows read access to existing files and creation of new files
+ via FTP. If the server does not support passive mode ftp, the
+ connection will fail.
+ </simpara>
+ <simpara>
+ You can open files for either reading or writing, but not both
+ simultaneously. If the remote file already exists on the ftp
+ server and you attempt to open it for writing, the connection
+ will fail. If you need to update existing files over ftp,
+ use <function>ftp_connect</function>.
+ </simpara>
+ <simpara>
+ ftps:// was introduced in PHP 4.3. It is the same as ftp://,
+ but attempts to negotiate a secure connection with the ftp server.
+ If the server does not support SSL, then the connection falls back
+ to regular unencrypted ftp.
+ </simpara>
+ <note>
+ <simpara>FTPS is supported starting from PHP 4.3, if you
+ have compiled in support for OpenSSL.
+ </simpara>
+ </note>
+
+ </section>
+
+ <section id="wrappers.php">
+ <title>PHP input/output streams</title>
+ <simpara>PHP 3.0.13 and up, php://output since PHP 4.3</simpara>
+
+ <itemizedlist>
+ <listitem><simpara>php://stdin</simpara></listitem>
+ <listitem><simpara>php://stdout</simpara></listitem>
+ <listitem><simpara>php://stderr</simpara></listitem>
+ <listitem><simpara>php://output</simpara></listitem>
+ </itemizedlist>
+
+ <simpara>
+ php://stdin, php://stdout and php://stderr allow access to
+ the corresponding input or output stream of the PHP process.
+ </simpara>
+ <simpara>
+ php://output allows you to write to the output buffer mechanism
+ in the same way as <function>print</function> and
+ <function>echo</function>.
+ </simpara>
+ <simpara>
+ php://stdin is read-only, whereas php://stdout, php://stderr
+ and php://output are write-only.
+ </simpara>
+ </section>
+
+ <section id="wrappers.compression">
+ <title>Compression Streams</title>
+ <simpara>zlib: PHP 4.0.4 - PHP 4.2.3 (systems with fopencookie only)</simpara>
+ <simpara>compress.zlib:// and compress.bzip2:// PHP 4.3 and up</simpara>
+
+ <itemizedlist>
+ <listitem><simpara>zlib:</simpara></listitem>
+ <listitem><simpara>compress.zlib://</simpara></listitem>
+ <listitem><simpara>compress.bzip2://</simpara></listitem>
+ </itemizedlist>
+
+ <simpara>
+ zlib: works like <function>gzopen</function>, except that the
+ stream can be used with <function>fread</function> and the other
+ filesystem functions. This is deprecated as of PHP 4.3 due
+ to ambiguities with filenames containing ':' characters; use
+ compress.zlib:// instead.
+ </simpara>
+
+ <simpara>
+ compress.zlib:// and compress.bzip2:// are equivalent to
+ <function>gzopen</function> and <function>bzopen</function> respectively,
+ and operate even on systems that do not support fopencookie.
+ </simpara>
+ </section>
</appendix>
+
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
Index: phpdoc/en/reference/filesystem/reference.xml
diff -u phpdoc/en/reference/filesystem/reference.xml:1.4
phpdoc/en/reference/filesystem/reference.xml:1.5
--- phpdoc/en/reference/filesystem/reference.xml:1.4 Fri Aug 9 06:26:00 2002
+++ phpdoc/en/reference/filesystem/reference.xml Mon Sep 23 22:53:08 2002
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
<reference id="ref.filesystem">
<title>Filesystem functions</title>
<titleabbrev>Filesystem</titleabbrev>
@@ -23,7 +23,53 @@
<section id="filesystem.configuration">
&reftitle.runtime;
- &no.config;
+ &extension.runtime;
+ <para>
+ <table>
+ <title>Filesystem and Streams Configuration Options</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Default</entry>
+ <entry>Changeable</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>auto_detect_line_endings</entry>
+ <entry>"Off"</entry>
+ <entry>PHP_INI_ALL</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ <para>
+ Here is a short explanation of the configuration directives.
+ <variablelist>
+ <varlistentry id="ini.auto-detect-line-endings">
+ <term>
+ <parameter>auto_detect_line_endings</parameter>
+ <type>boolean</type>
+ </term>
+ <listitem>
+ <para>
+ When turned on, PHP will examine the data read by
+ <function>fgets</function> and <function>file</function> to see if it
+ is using Unix, MS-Dos or Macintosh line-ending conventions.
+ </para>
+ <para>This enables PHP to to interoperate with Macintosh systems,
+ but defaults to Off, as there is a very small performance penalty
+ when detecting the EOL conventions for the first line, and also
+ because people using carriage-returns as item separators under
+ Unix systems would experience non-backwards-compatible behaviour.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
</section>
<section id="filesystem.resources">
@@ -43,6 +89,10 @@
<simpara>
For related functions, see also the <link linkend="ref.dir">Directory</link>
and <link linkend="ref.exec">Program Execution</link> sections.
+ </simpara>
+ <simpara>
+ For a list and explanation of the various URL wrappers that can be used
+ as remote files, see also <xref linkend="wrappers"/>.
</simpara>
</section>
Index: phpdoc/en/reference/filesystem/functions/fopen.xml
diff -u phpdoc/en/reference/filesystem/functions/fopen.xml:1.4
phpdoc/en/reference/filesystem/functions/fopen.xml:1.5
--- phpdoc/en/reference/filesystem/functions/fopen.xml:1.4 Mon Sep 16 14:13:37
2002
+++ phpdoc/en/reference/filesystem/functions/fopen.xml Mon Sep 23 22:53:08 2002
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.fopen">
<refnamediv>
@@ -16,68 +16,41 @@
<methodparam
choice="opt"><type>resource</type><parameter>zcontext</parameter></methodparam>
</methodsynopsis>
<simpara>
- If <parameter>filename</parameter> begins with "http://"; (not
- case sensitive), an HTTP 1.0 connection is opened to the
- specified server, the page is requested using the HTTP GET
- method, and a file pointer is returned to the beginning
- of the body of the response. A 'Host:' header is sent with the
- request in order to handle name-based virtual hosts.
- </simpara>
- <simpara>
- As of PHP 4.3.0, if you have compiled in support for OpenSSL,
- you may use "https://"; to open an HTTP connection over SSL.
- </simpara>
- <simpara>
- Note that the file pointer allows you to retrieve only the
- <emphasis>body</emphasis> of the response; to retrieve the HTTP
- response header you need to be using PHP 4.0.5 or later;
- The headers will be stored in the $http_response_header variable.
- As of PHP 4.3.0, the header information can be retrieved using
- <function>file_get_wrapper_data</function>.
- </simpara>
- <simpara>
- HTTP connections are read-only; you cannot write data or copy
- files to an HTTP resource.
- </simpara>
- <simpara>
- Versions prior to PHP 4.0.5 do not handle HTTP redirects. Because
- of this, directories must include trailing slashes.
- </simpara>
- <simpara>
- If <parameter>filename</parameter> begins with "ftp://"; (not case
- sensitive), an ftp connection to the specified server is opened
- and a pointer to the requested file is returned. If the server
- does not support passive mode ftp, this will fail. You can open
- files for either reading or writing via ftp (but not both
- simultaneously). If the remote file already exists on the ftp
- server and you attempt to open it for writing, this will fail.
- If you need to update existing files over ftp, use
- <function>ftp_connect</function>.
- </simpara>
- <simpara>
- As of PHP 4.3.0, if you have compiled in support for OpenSSL,
- you may use "ftps://" to open an FTP connection that will
- use SSL to encrypt the connection. PHP will fall-back and
- work just like regular ftp:// if the server does not support
- SSL.
- </simpara>
- <simpara>
- If <parameter>filename</parameter> is one of "php://stdin",
- "php://stdout", or "php://stderr", the corresponding stdio
- stream will be opened. (This was introduced in PHP 3.0.13;
- in earlier versions, a filename such as "/dev/stdin" or
- "/dev/fd/0" must be used to access the stdio streams.)
- </simpara>
- <simpara>
- If <parameter>filename</parameter> begins with anything else, the
- file will be opened from the filesystem, and a file pointer to
- the file opened is returned.
- </simpara>
- <simpara>
- If the open fails, the function returns &false;.
+ <function>fopen</function> binds a named resource, specified
+ by <parameter>filename</parameter>, to a stream. If
+ <parameter>filename</parameter> is of the form "scheme://...",
+ it is assumed to be a URL and PHP will search for a protocol
+ handler (also known as a wrapper) for that scheme. If no
+ wrappers for that protocol are registered, PHP will emit
+ a notice to help you track potential problems in your script
+ and then continue as though <parameter>filename</parameter>
+ specifies a regular file.
+ </simpara>
+ <simpara>
+ If PHP has decided that <parameter>filename</parameter> specifies
+ a local file, then it will try to open a stream on that file.
+ The file must be accessible to PHP, so you need to ensure that
+ the file access permissions allow this access.
+ If you have enabled <link linkend="ini.safe-mode">safe_mode</link>,
+ or <link linkend="ini.open-basedir">open_basedir</link> further
+ restrictions may apply.
+ </simpara>
+ <simpara>
+ If PHP has decided that <parameter>filename</parameter> specifies
+ a registered protocol, and that protocol is registered as a
+ network URL, PHP will check to make sure that
+ <link linkend="ini.allow-url-fopen">allow_url_fopen</link> is
+ enabled. If it is switched off, PHP will emit a warning and
+ the fopen call will fail.
</simpara>
+ <note>
+ <simpara>
+ The list of supported protocols can be found in <xref linkend="wrappers"/>.
+ </simpara>
+ </note>
<para>
- <parameter>mode</parameter> may be any of the following:
+ <parameter>mode</parameter> specifies the type of access you
+ require to the stream. It may be any of the following:
<itemizedlist>
<listitem>
<simpara>
@@ -126,7 +99,8 @@
The <parameter>mode</parameter> may contain the letter
'b'. This is useful only on systems which differentiate between
binary and text files (i.e. Windows. It's useless on Unix).
- If not needed, this will be ignored.
+ If not needed, this will be ignored. You are encouraged to
+ include the 'b' flag in order to make your scripts more portable.
</para>
</note>
<para>
@@ -138,6 +112,9 @@
The optional fourth <parameter>zcontext</parameter> is used for
specifying tuning parameters and callbacks.
</para>
+ <simpara>
+ If the open fails, the function returns &false;.
+ </simpara>
<para>
<example>
<title><function>fopen</function> example</title>
@@ -173,7 +150,7 @@
</informalexample>
</para>
<simpara>
- See also <xref linkend="wrappers"/>
+ See also <xref linkend="wrappers"/>,
<function>fclose</function>,
<function>fgets</function>,
<function>fsockopen</function>,
--
PHP Documentation Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
