cvs: phpdoc /en/reference/filesystem/functions file-get-contents.xml

nicobn Sat Aug 18 18:20:50 2007 UTC Modified files: /phpdoc/en/reference/filesystem/functions file-get-contents.xml Log: - Added parameter informations - Added return value informations - Updated prototype - Added warning for versions prior to PHP 6 about the 'flags' parameter - Made the page unicode-aware http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/filesystem/functions/file-get-contents.xml?r1=1.27&r2=1.28&diff_format=u Index: phpdoc/en/reference/filesystem/functions/file-get-contents.xml diff -u phpdoc/en/reference/filesystem/functions/file-get-contents.xml:1.27 phpdoc/en/reference/filesystem/functions/file-get-contents.xml:1.28 --- phpdoc/en/reference/filesystem/functions/file-get-contents.xml:1.27 Wed Jun 20 22:24:27 2007 +++ phpdoc/en/reference/filesystem/functions/file-get-contents.xml Sat Aug 18 18:20:50 2007 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.27 $ --> +<!-- $Revision: 1.28 $ --> <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.file-get-contents"> <refnamediv> <refname>file_get_contents</refname> @@ -11,17 +11,17 @@ <methodsynopsis> <type>string</type><methodname>file_get_contents</methodname> <methodparam><type>string</type><parameter>filename</parameter></methodparam> - <methodparam choice="opt"><type>bool</type><parameter>use_include_path</parameter></methodparam> <methodparam choice="opt"><type>resource</type><parameter>context</parameter></methodparam> + <methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam> <methodparam choice="opt"><type>int</type><parameter>offset</parameter></methodparam> <methodparam choice="opt"><type>int</type><parameter>maxlen</parameter></methodparam> </methodsynopsis> <para> - Identical to <function>file</function>, except that - <function>file_get_contents</function> returns the file in a string, - starting at the specified <parameter>offset</parameter> up to - <parameter>maxlen</parameter> bytes. - On failure, <function>file_get_contents</function> will return &false;. + This function is identical to <function>file</function>, except that + <function>file_get_contents</function> returns the file in a + <type>string</type>, starting at the specified <parameter>offset</parameter> + up to <parameter>maxlen</parameter> bytes. On failure, + <function>file_get_contents</function> will return &false;. </para> <para> <function>file_get_contents</function> is the preferred way to read the @@ -34,11 +34,123 @@ need to encode the URI with <function>urlencode</function>. </para> </note> - <note> - <para> - <parameter>context</parameter> parameter can be skipped by &null;. - </para> - </note> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>filename</parameter></term> + <listitem> + <para> + Name of the file to read. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>context</parameter></term> + <listitem> + <para> + A valid context resource created with + <function>stream_create_context</function>. If you don't need to use a + custom context, you can skip this parameter by &null;. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter></term> + <listitem> + <warning> + <para> + For all versions prior to PHP 6, this parameter is called + <parameter>use_include_path</parameter> and is a <type>bool</type>. + The <parameter>flags</parameter> parameter is only available since + PHP 6. If you use an older version and want to search for + <parameter>filename</parameter> in the + <link linkend="ini.include-path">include path</link>, this + parameter must be &true;. Since PHP 6, you have to use the + <constant>FILE_USE_INCLUDE_PATH</constant> flag instead. + </para> + </warning> + <para> + 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_TEXT</constant> + </entry> + <entry> + If unicode semantics are enabled, the default encoding of the read + data is UTF-8. You can specify a different encoding by creating a + custom context or by changing the default using + <function>stream_default_encoding</function>. This flag cannot be + used with <constant>FILE_BINARY</constant>. + </entry> + </row> + <row> + <entry> + <constant>FILE_BINARY</constant> + </entry> + <entry> + With this flag, the file is read in binary mode. This is the default + setting and cannot be used with <constant>FILE_TEXT</constant>. + </entry> + </row> + </tbody> + </tgroup> + </table> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>offset</parameter></term> + <listitem> + <para> + The offset where the reading starts. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>maxlen</parameter></term> + <listitem> + <para> + Maximum length of data read. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + The function returns the read data or &false; on failure. + </para> </refsect1> <refsect1 role="changelog"> @@ -66,6 +178,13 @@ <parameter>maxlen</parameter> parameters. </entry> </row> + <row> + <entry>6.0.0</entry> + <entry> + The <parameter>use_include_path</parameter> parameter was replaced by + the <parameter>flags</parameter> parameter. + </entry> + </row> </tbody> </tgroup> </informaltable>