nicobn Sat Aug 18 03:32:51 2007 UTC
Modified files:
/phpdoc/en/reference/filesystem/functions file-put-contents.xml
Log:
- Added a table with the available flags for the flags parameter
- Added PHP 6's FILE_TEXT and FILE_BINARY
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/filesystem/functions/file-put-contents.xml?r1=1.15&r2=1.16&diff_format=u
Index: phpdoc/en/reference/filesystem/functions/file-put-contents.xml
diff -u phpdoc/en/reference/filesystem/functions/file-put-contents.xml:1.15
phpdoc/en/reference/filesystem/functions/file-put-contents.xml:1.16
--- phpdoc/en/reference/filesystem/functions/file-put-contents.xml:1.15 Wed Jun
20 22:24:27 2007
+++ phpdoc/en/reference/filesystem/functions/file-put-contents.xml Sat Aug
18 03:32:51 2007
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.15 $ -->
+<!-- $Revision: 1.16 $ -->
<refentry xmlns="http://docbook.org/ns/docbook";
xml:id="function.file-put-contents">
<refnamediv>
<refname>file_put_contents</refname>
@@ -16,13 +16,9 @@
<methodparam
choice="opt"><type>resource</type><parameter>context</parameter></methodparam>
</methodsynopsis>
<para>
- Identical to calling <function>fopen</function>,
<function>fwrite</function>,
- and <function>fclose</function> successively.
- </para>
- <para>
- You can also specify the <parameter>data</parameter> parameter as an array
- (not multi-dimension arrays). This is equivalent to
- <literal>file_put_contents($filename, implode('', $array))</literal>.
+ This function is identical to calling <function>fopen</function>,
+ <function>fwrite</function> and <function>fclose</function> successively
+ to write data to a file.
</para>
</refsect1>
@@ -34,7 +30,7 @@
<term><parameter>filename</parameter></term>
<listitem>
<para>
- The file name where to write the data
+ Path to the file where to write the data.
</para>
</listitem>
</varlistentry>
@@ -50,22 +46,87 @@
remaining buffer of that stream will be copied to the specified file.
This is similar with using <function>stream_copy_to_stream</function>.
</para>
+ <para>
+ You can also specify the <parameter>data</parameter> parameter as a
single
+ dimension array. This is equivalent to
+ <literal>file_put_contents($filename, implode('', $array))</literal>.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>flags</parameter></term>
<listitem>
<para>
- <parameter>flags</parameter> can take
- <constant>FILE_USE_INCLUDE_PATH</constant>,
- <constant>FILE_APPEND</constant> and/or <constant>LOCK_EX</constant>
- (acquire an exclusive lock), however the
- <constant>FILE_USE_INCLUDE_PATH</constant> option should be used with
- caution. As of PHP 6, it can also take one of
- <constant>FILE_TEXT</constant> or <constant>FILE_BINARY</constant> to
- specify how newlines should be handled when outputting the file. See
- <function>fopen</function>'s "t" and "b"
- modes for more information.
+ The value of <parameter>flags</parameter> can be any combination of
+ the following flags (with some restrictions), joined with the binary OR
+ (<literal>|</literal>) operator.
+ </para>
+ <para>
+ <table>
+ <title>Available flags</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Flag</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <constant>FILE_USE_INCLUDE_PATH</constant>
+ </entry>
+ <entry>
+ Search for <parameter>filename</parameter> in the include
directory.
+ See <link linkend="ini.include-path">include_path</link> for more
+ information.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <constant>FILE_APPEND</constant>
+ </entry>
+ <entry>
+ If file <parameter>filename</parameter> already exists, append
+ the data to the file instead of overwriting it.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <constant>LOCK_EX</constant>
+ </entry>
+ <entry>
+ Acquire an exclusive lock on the file while proceeding to the
+ writing.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <constant>FILE_TEXT</constant>
+ </entry>
+ <entry>
+ <parameter>data</parameter> will be written in UTF-8 encoding by
+ default. You can specify a different encoding by creating a
+ custom context. This flags cannot be used with
+ <constant>FILE_BINARY</constant>. If <parameter>data</parameter>
+ is UTF-8 and the <constant>FILE_TEXT</constant> flag is not set,
+ a warning will be issued. This flag is only available since PHP 6.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <constant>FILE_BINARY</constant>
+ </entry>
+ <entry>
+ <parameter>data</parameter> will be written in binary mode. This
+ is the default setting and cannot be used with
+ <constant>FILE_BINARY</constant>. This flag is only available since
+ PHP 6.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
</para>
</listitem>
</varlistentry>
@@ -117,8 +178,8 @@
<row>
<entry>6.0.0</entry>
<entry>
- Added support for <constant>FILE_TEXT</constant> and
- <constant>FILE_BINARY</constant>
+ Added support for the <constant>FILE_TEXT</constant> and
+ <constant>FILE_BINARY</constant> flags
</entry>
</row>
</tbody>
