file-get-contents.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: ea62fb83196997032641b50fe44420305466195e Maintainer: HonestQiao Status: ready -->
<!-- CREDITS: mowangjuanzi -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.file-get-contents" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>file_get_contents</refname>
  <refpurpose>将整个文件读入一个字符串</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>string</type><type>false</type></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><initializer>&false;</initializer></methodparam>
   <methodparam choice="opt"><type class="union"><type>resource</type><type>null</type></type><parameter>context</parameter><initializer>&null;</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>offset</parameter><initializer>0</initializer></methodparam>
   <methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>length</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   和 <function>file</function> 一样，只除了
   <function>file_get_contents</function> 把文件读入一个字符串。将在参数
   <parameter>offset</parameter> 所指定的位置开始读取长度为
   <parameter>length</parameter> 的内容。如果失败，<function>file_get_contents</function>
   将返回 &false;。
  </para>
  <para>
   <function>file_get_contents</function>
   函数是用来将文件的内容读入到一个字符串中的首选方法。如果操作系统支持还会使用内存映射技术来增强性能。
  </para>
  <note>
   <para>
    如果要打开有特殊字符的 URL （比如说有空格），就需要使用
    <function>urlencode</function> 进行 URL 编码。
   </para>
  </note>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>filename</parameter></term>
     <listitem>
      <para>
       要读取的文件的名称。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>use_include_path</parameter></term>
     <listitem>
      <note>
       <para>
        常量 <constant>FILE_USE_INCLUDE_PATH</constant> 用于触发搜索
        <link linkend="ini.include-path">include path</link>。
        因为 <constant>FILE_USE_INCLUDE_PATH</constant> 是个 <type>int</type>，如果开启了<link
        linkend="language.types.declarations.strict">严格类型</link> 将无法启用。
        所以要用 &true; 来代替常量。
       </para>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>context</parameter></term>
     <listitem>
      <para>
       <function>stream_context_create</function> 创建的有效的上下文（context）资源。
       如果你不需要自定义 context，可以用 &null; 来忽略。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>offset</parameter></term>
     <listitem>
      <para>
       读取原始数据流的开始位置偏移量。负的 offset 会从数据流的末尾开始统计。
      </para>
      <para>
       远程文件不支持偏移量寻址（<parameter>offset</parameter>）。
       对远程文件以较小的 offset 可能可以正常寻址，
       但由于是对缓冲流进行操作，所以操作结果不可预测。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>length</parameter></term>
     <listitem>
      <para>
       要读取数据的最大长度。
       默认情况下会读到文件末尾。
       注意，该参数会应用到处理 stream 的过滤器（filter）中。
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   函数返回读取到的数据，&return.falseforfailure;。
  </para>
  &return.falseproblem;
 </refsect1>


 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   以下情况会导致 <constant>E_WARNING</constant> 级别错误：
   无法找到 <parameter>filename</parameter> 文件；
   <parameter>length</parameter> 小于零；
   在 steam 中无法寻址偏移量 <parameter>offset</parameter>。
  </para>
  <para>
   Windows 下用 <function>file_get_contents</function> 读取目录会导致 <constant>E_WARNING</constant> 错误。
   PHP 7.4 起，其他操作系统也会出现同样错误。
  </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>8.0.0</entry>
       <entry>
        现在 <parameter>length</parameter> 允许为 null。
       </entry>
      </row>
      <row>
       <entry>7.1.0</entry>
       <entry>
        支持负数 <parameter>offset</parameter>。
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>获取并输出网站首页 HTML 源码</title>
    <programlisting role="php">
<![CDATA[
<?php
$homepage = file_get_contents('http://www.example.com/');
echo $homepage;
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>在 include_path 里搜索</title>
    <programlisting role="php">
<![CDATA[
<?php
// 如果开启了严格类型，例如 declare(strict_types=1);
$file = file_get_contents('./people.txt', true);
// 否则就这样写
$file = file_get_contents('./people.txt', FILE_USE_INCLUDE_PATH);
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>读取文件一小节</title>
    <programlisting role="php">
<![CDATA[
<?php
// 从第 21 个字符开始，读取 14 字符长度
$section = file_get_contents('./people.txt', FALSE, NULL, 20, 14);
var_dump($section);
?>
]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
string(14) "lle Bjori Ro" 
]]>
    </screen>
   </example>
   <example>
    <title>使用 stream 上下文（context）</title>
    <programlisting role="php">
<![CDATA[
<?php
// 创建 stream
$opts = array(
  'http'=>array(
    'method'=>"GET",
    'header'=>"Accept-language: en\r\n" .
              "Cookie: foo=bar\r\n"
  )
);

$context = stream_context_create($opts);

// 以下面设置的 HTTP 头来打开文件
$file = file_get_contents('http://www.example.com/', false, $context);
?>
]]>
    </programlisting>
   </example>
  </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>
    <member><link linkend="reserved.variables.httpresponseheader">$http_response_header</link></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:"~/.phpdoc/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
-->