From c9d8e1779e81b71d115da3bc1b2de1bd24f092d3 Mon Sep 17 00:00:00 2001
From: Hannes Magnusson <bjori@php.net>
Date: Tue, 3 Apr 2007 20:38:29 +0000
Subject: [PATCH] Document the second parameter correctly (user note)

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@233199 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/filesystem/functions/file.xml | 52 +++++++++++++++++++++----
 1 file changed, 45 insertions(+), 7 deletions(-)

diff --git a/reference/filesystem/functions/file.xml b/reference/filesystem/functions/file.xml
index 015da0452e..7887c233d4 100644
--- a/reference/filesystem/functions/file.xml
+++ b/reference/filesystem/functions/file.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.20 $ -->
+<!-- $Revision: 1.21 $ -->
 <!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
 <refentry id="function.file">
  <refnamediv>
@@ -11,21 +11,59 @@
   <methodsynopsis>
    <type>array</type><methodname>file</methodname>
    <methodparam><type>string</type><parameter>filename</parameter></methodparam>
-   <methodparam choice="opt"><type>int</type><parameter>use_include_path</parameter></methodparam>
+   <methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
    <methodparam choice="opt"><type>resource</type><parameter>context</parameter></methodparam>
   </methodsynopsis>
   <para>
-   Identical to <function>file_get_contents</function>, except that
+   Similiar to <function>file_get_contents</function>, except that
    <function>file</function> returns the file in an array. Each
    element of the array corresponds to a line in the file, with the
    newline still attached.  Upon failure, <function>file</function>
    returns &false;.
   </para>
   <para>
-   You can use the optional <parameter>use_include_path</parameter> parameter
-   and set it to "1", if you want to search for the file in the <link
-   linkend="ini.include-path">include_path</link>, too.
+   The optional parameter <parameter>flags</parameter> can be one, or more, of
+   the following constants:
+   <variablelist>
+    <varlistentry>
+     <term>
+      <constant>FILE_USE_INCLUDE_PATH</constant>
+     </term>
+     <listitem>
+      <simpara>
+       Search for the file in the <link linkend="ini.include-path">include_path</link>.
+      </simpara>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term>
+      <constant>FILE_IGNORE_NEW_LINES</constant>
+     </term>
+     <listitem>
+      <simpara>
+       Do not add newline at the end of each array element
+      </simpara>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term>
+      <constant>FILE_SKIP_EMPTY_LINES</constant>
+     </term>
+     <listitem>
+      <simpara>
+       Skip empty lines
+      </simpara>
+     </listitem>
+    </varlistentry>
+   </variablelist>
   </para>
+  <note>
+   <para>
+    Prior to PHP 5.0.0 the <parameter>flags</parameter> parameter only
+    covered <link linkend="ini.include-path">include_path</link> and was
+    enabled with 1.
+   </para>
+  </note>
   <para>
    <informalexample>
     <programlisting role="php">
@@ -50,7 +88,7 @@ $html = implode('', file('http://www.example.com/'));
   &tip.fopen-wrapper;
   <note>
    <para>
-    Each line in the resulting array will include the line ending, so you
+    Each line in the resulting array will include the line ending, unless FILE_IGNORE_NEW_LINES is used, so you
     still need to use <function>rtrim</function> if you do not want the line
     ending present.
    </para>