<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.31 $ -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.file-get-contents">
 <refnamediv>
  <refname>file_get_contents</refname> 
  <refpurpose>Reads entire file into a string</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>file_get_contents</methodname>
   <methodparam><type>string</type><parameter>filename</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
   <methodparam choice="opt"><type>resource</type><parameter>context</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>offset</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>maxlen</parameter></methodparam>
  </methodsynopsis>
  <para> 
   This function is similar 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
   contents of a file into a string.  It will use memory mapping techniques if
   supported by your OS to enhance performance.
  </para>
  <note>
   <para>
    If you're opening a URI with special characters, such as spaces, you
    need to encode the URI with <function>urlencode</function>.
   </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>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>context</parameter></term>
     <listitem>
      <para>
       A valid context resource created with 
       <function>stream_context_create</function>. If you don't need to use a
       custom context, you can skip this parameter by &null;.
      </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">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>5.0.0</entry>
       <entry>
        Added context support.
       </entry>
      </row>
      <row>
       <entry>5.1.0</entry>
       <entry>
        Added the <parameter>offset</parameter> and
        <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>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  &note.bin-safe;
  &tip.fopen-wrapper;
  &warn.ssl-non-standard;
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>file</function></member>
    <member><function>fgets</function></member>
    <member><function>fread</function></member>
    <member><function>readfile</function></member>
    <member><function>file_put_contents</function></member>
    <member><function>stream_get_contents</function></member>
    <member><function>stream_context_create</function></member>
   </simplelist>
  </para>
 </refsect1>

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->