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>
