reference/filesystem/functions/file-get-contents.xml
ea62fb83196997032641b50fe44420305466195e
...
...
@@ -1,6 +1,6 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.file-get-contents">
3
+
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.file-get-contents" xmlns:xlink="http://www.w3.org/1999/xlink">
4
4
<refnamediv>
5
5
<refname>file_get_contents</refname>
6
6
<refpurpose>Reads entire file into a string</refpurpose>
...
...
@@ -9,18 +9,18 @@
9
9
<refsect1 role="description">
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
-
<type>string</type><methodname>file_get_contents</methodname>
12
+
<type class="union"><type>string</type><type>false</type></type><methodname>file_get_contents</methodname>
13
13
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
14
-
<methodparam choice="opt"><type>bool</type><parameter>use_include_path</parameter><initializer>false</initializer></methodparam>
15
-
<methodparam choice="opt"><type>resource</type><parameter>context</parameter></methodparam>
14
+
<methodparam choice="opt"><type>bool</type><parameter>use_include_path</parameter><initializer>&false;</initializer></methodparam>
15
+
<methodparam choice="opt"><type class="union"><type>resource</type><type>null</type></type><parameter>context</parameter><initializer>&null;</initializer></methodparam>
16
16
<methodparam choice="opt"><type>int</type><parameter>offset</parameter><initializer>0</initializer></methodparam>
17
-
<methodparam choice="opt"><type>int</type><parameter>maxlen</parameter></methodparam>
17
+
<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>length</parameter><initializer>&null;</initializer></methodparam>
18
18
</methodsynopsis>
19
19
<para>
20
20
This function is similar to <function>file</function>, except that
21
21
<function>file_get_contents</function> returns the file in a
22
22
<type>string</type>, starting at the specified <parameter>offset</parameter>
23
-
up to <parameter>maxlen</parameter> bytes. On failure,
23
+
up to <parameter>length</parameter> bytes. On failure,
24
24
<function>file_get_contents</function> will return &false;.
25
25
</para>
26
26
<para>
...
...
@@ -53,9 +53,13 @@
53
53
<listitem>
54
54
<note>
55
55
<para>
56
-
As of PHP 5 the <constant>FILE_USE_INCLUDE_PATH</constant> constant can be used
56
+
The <constant>FILE_USE_INCLUDE_PATH</constant> constant can be used
57
57
to trigger <link linkend="ini.include-path">include path</link>
58
58
search.
59
+
This is not possible if <link
60
+
linkend="language.types.declarations.strict">strict typing</link>
61
+
is enabled, since <constant>FILE_USE_INCLUDE_PATH</constant> is an
62
+
<type>int</type>. Use &true; instead.
59
63
</para>
60
64
</note>
61
65
</listitem>
...
...
@@ -85,7 +89,7 @@
85
89
</listitem>
86
90
</varlistentry>
87
91
<varlistentry>
88
-
<term><parameter>maxlen</parameter></term>
92
+
<term><parameter>length</parameter></term>
89
93
<listitem>
90
94
<para>
91
95
Maximum length of data read. The default is to read until end
...
...
@@ -109,9 +113,44 @@
109
113
<refsect1 role="errors">
110
114
&reftitle.errors;
111
115
<para>
112
-
An <constant>E_WARNING</constant> level error is generated if <parameter>filename</parameter> cannot be found, <parameter>maxlength</parameter>
116
+
An <constant>E_WARNING</constant> level error is generated if <parameter>filename</parameter> cannot be found, <parameter>length</parameter>
113
117
is less than zero, or if seeking to the specified <parameter>offset</parameter> in the stream fails.
114
118
</para>
119
+
<para>
120
+
When <function>file_get_contents</function> is called on a directory,
121
+
an <constant>E_WARNING</constant> level error is generated on Windows,
122
+
and as of PHP 7.4 on other operating systems as well.
123
+
</para>
124
+
</refsect1>
125
+

126
+
<refsect1 role="changelog">
127
+
&reftitle.changelog;
128
+
<para>
129
+
<informaltable>
130
+
<tgroup cols="2">
131
+
<thead>
132
+
<row>
133
+
<entry>&Version;</entry>
134
+
<entry>&Description;</entry>
135
+
</row>
136
+
</thead>
137
+
<tbody>
138
+
<row>
139
+
<entry>8.0.0</entry>
140
+
<entry>
141
+
<parameter>length</parameter> is nullable now.
142
+
</entry>
143
+
</row>
144
+
<row>
145
+
<entry>7.1.0</entry>
146
+
<entry>
147
+
Support for negative <parameter>offset</parameter>s has been added.
148
+
</entry>
149
+
</row>
150
+
</tbody>
151
+
</tgroup>
152
+
</informaltable>
153
+
</para>
115
154
</refsect1>
116
155

117
156
<refsect1 role="examples">
...
...
@@ -133,9 +172,9 @@ echo $homepage;
133
172
<programlisting role="php">
134
173
<![CDATA[
135
174
<?php
136
-
// <= PHP 5
175
+
// If strict types are enabled i.e. declare(strict_types=1);
137
176
$file = file_get_contents('./people.txt', true);
138
-
// > PHP 5
177
+
// Otherwise
139
178
$file = file_get_contents('./people.txt', FILE_USE_INCLUDE_PATH);
140
179
?>
141
180
]]>
...
...
@@ -147,7 +186,7 @@ $file = file_get_contents('./people.txt', FILE_USE_INCLUDE_PATH);
147
186
<![CDATA[
148
187
<?php
149
188
// Read 14 characters starting from the 21st character
150
-
$section = file_get_contents('./people.txt', NULL, NULL, 20, 14);
189
+
$section = file_get_contents('./people.txt', FALSE, NULL, 20, 14);
151
190
var_dump($section);
152
191
?>
153
192
]]>
...
...
@@ -184,37 +223,6 @@ $file = file_get_contents('http://www.example.com/', false, $context);
184
223
</para>
185
224
</refsect1>
186
225

187
-
<refsect1 role="changelog">
188
-
&reftitle.changelog;
189
-
<para>
190
-
<informaltable>
191
-
<tgroup cols="2">
192
-
<thead>
193
-
<row>
194
-
<entry>&Version;</entry>
195
-
<entry>&Description;</entry>
196
-
</row>
197
-
</thead>
198
-
<tbody>
199
-
<row>
200
-
<entry>7.1.0</entry>
201
-
<entry>
202
-
Support for negative <parameter>offset</parameter>s has been added.
203
-
</entry>
204
-
</row>
205
-
<row>
206
-
<entry>5.1.0</entry>
207
-
<entry>
208
-
Added the <parameter>offset</parameter> and
209
-
<parameter>maxlen</parameter> parameters.
210
-
</entry>
211
-
</row>
212
-
</tbody>
213
-
</tgroup>
214
-
</informaltable>
215
-
</para>
216
-
</refsect1>
217
-

218
226
<refsect1 role="notes">
219
227
&reftitle.notes;
220
228
&note.bin-safe;
221
229