- Added a table with the available flags for the flags parameter

- Added PHP 6's FILE_TEXT and FILE_BINARY


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@241491 c90b9560-bf6c-de11-be94-00142212c4b1

reference/filesystem/functions/file-put-contents.xml

@@ -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 &quot;t&quot; and &quot;b&quot;
-       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>