reference/dom/domdocument.xml
d75a54118772b34c7a538962ac5f994900c99690
...
...
@@ -1,6 +1,6 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<phpdoc:classref xmlns:phpdoc="http://php.net/ns/phpdoc" xml:id="class.domdocument" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
3
+
<reference xml:id="class.domdocument" role="class" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
4
4
<title>The DOMDocument class</title>
5
5
<titleabbrev>DOMDocument</titleabbrev>
6
6
...
...
@@ -20,138 +20,164 @@
20
20
&reftitle.classsynopsis;
21
21
22
22
<!-- {{{ Synopsis -->
23
-
<classsynopsis>
24
-
<ooclass><classname>DOMDocument</classname></ooclass>
23
+
<classsynopsis class="class">
24
+
<ooclass>
25
+
<classname>DOMDocument</classname>
26
+
</ooclass>
25
27

26
-
<!-- {{{ Class synopsis -->
27
-
<classsynopsisinfo>
28
-
<ooclass>
29
-
<classname>DOMDocument</classname>
30
-
</ooclass>
28
+
<ooclass>
29
+
<modifier>extends</modifier>
30
+
<classname>DOMNode</classname>
31
+
</ooclass>
31
32

32
-
<!-- If the class extends another one, use this -->
33
-
<ooclass>
34
-
<modifier>extends</modifier>
35
-
<classname>DOMNode</classname>
36
-
</ooclass>
33
+
<oointerface>
34
+
<modifier>implements</modifier>
35
+
<interfacename>DOMParentNode</interfacename>
36
+
</oointerface>
37
37

38
-
</classsynopsisinfo>
39
-
<!-- }}} -->
38
+
<classsynopsisinfo role="comment">&InheritedConstants;</classsynopsisinfo>
39
+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.domnode')/db:partintro/db:section/db:classsynopsis/db:fieldsynopsis[preceding-sibling::db:classsynopsisinfo[1][@role='comment' and text()='&Constants;']]))">
40
+
<xi:fallback/>
41
+
</xi:include>
40
42

41
43
<classsynopsisinfo role="comment">&Properties;</classsynopsisinfo>
42
-
<!-- If the property is documented below (xml:id=domdocument.props) use this -->
43
44
<fieldsynopsis>
44
-
<modifier>readonly</modifier>
45
45
<modifier>public</modifier>
46
-
<type>string</type>
47
-
<varname linkend="domdocument.props.actualencoding">actualEncoding</varname>
46
+
<modifier>readonly</modifier>
47
+
<type class="union"><type>DOMDocumentType</type><type>null</type></type>
48
+
<varname linkend="domdocument.props.doctype">doctype</varname>
48
49
</fieldsynopsis>
49
50
<fieldsynopsis>
50
-
<modifier>readonly</modifier>
51
51
<modifier>public</modifier>
52
-
<type>DOMConfiguration</type>
53
-
<varname linkend="domdocument.props.config">config</varname>
52
+
<modifier>readonly</modifier>
53
+
<type>DOMImplementation</type>
54
+
<varname linkend="domdocument.props.implementation">implementation</varname>
54
55
</fieldsynopsis>
55
56
<fieldsynopsis>
56
-
<modifier>readonly</modifier>
57
57
<modifier>public</modifier>
58
-
<type>DOMDocumentType</type>
59
-
<varname linkend="domdocument.props.doctype">doctype</varname>
58
+
<modifier>readonly</modifier>
59
+
<type class="union"><type>DOMElement</type><type>null</type></type>
60
+
<varname linkend="domdocument.props.documentelement">documentElement</varname>
60
61
</fieldsynopsis>
61
62
<fieldsynopsis>
63
+
<modifier>public</modifier>
62
64
<modifier>readonly</modifier>
65
+
<type class="union"><type>string</type><type>null</type></type>
66
+
<varname linkend="domdocument.props.actualencoding">actualEncoding</varname>
67
+
</fieldsynopsis>
68
+
<fieldsynopsis>
63
69
<modifier>public</modifier>
64
-
<type>DOMElement</type>
65
-
<varname linkend="domdocument.props.documentelement">documentElement</varname>
70
+
<type class="union"><type>string</type><type>null</type></type>
71
+
<varname linkend="domdocument.props.encoding">encoding</varname>
66
72
</fieldsynopsis>
67
73
<fieldsynopsis>
68
74
<modifier>public</modifier>
69
-
<type>string</type>
70
-
<varname linkend="domdocument.props.documenturi">documentURI</varname>
75
+
<modifier>readonly</modifier>
76
+
<type class="union"><type>string</type><type>null</type></type>
77
+
<varname linkend="domdocument.props.xmlencoding">xmlEncoding</varname>
71
78
</fieldsynopsis>
72
79
<fieldsynopsis>
73
80
<modifier>public</modifier>
74
-
<type>string</type>
75
-
<varname linkend="domdocument.props.encoding">encoding</varname>
81
+
<type>bool</type>
82
+
<varname linkend="domdocument.props.standalone">standalone</varname>
76
83
</fieldsynopsis>
77
84
<fieldsynopsis>
78
85
<modifier>public</modifier>
79
86
<type>bool</type>
80
-
<varname linkend="domdocument.props.formatoutput">formatOutput</varname>
87
+
<varname linkend="domdocument.props.xmlstandalone">xmlStandalone</varname>
81
88
</fieldsynopsis>
82
89
<fieldsynopsis>
83
-
<modifier>readonly</modifier>
84
90
<modifier>public</modifier>
85
-
<type>DOMImplementation</type>
86
-
<varname linkend="domdocument.props.implementation">implementation</varname>
91
+
<type class="union"><type>string</type><type>null</type></type>
92
+
<varname linkend="domdocument.props.version">version</varname>
87
93
</fieldsynopsis>
88
94
<fieldsynopsis>
89
95
<modifier>public</modifier>
90
-
<type>bool</type>
91
-
<varname linkend="domdocument.props.preservewhitespace">preserveWhiteSpace</varname>
92
-
<initializer>true</initializer>
96
+
<type class="union"><type>string</type><type>null</type></type>
97
+
<varname linkend="domdocument.props.xmlversion">xmlVersion</varname>
93
98
</fieldsynopsis>
94
99
<fieldsynopsis>
95
100
<modifier>public</modifier>
96
101
<type>bool</type>
97
-
<varname linkend="domdocument.props.recover">recover</varname>
102
+
<varname linkend="domdocument.props.stricterrorchecking">strictErrorChecking</varname>
103
+
</fieldsynopsis>
104
+
<fieldsynopsis>
105
+
<modifier>public</modifier>
106
+
<type class="union"><type>string</type><type>null</type></type>
107
+
<varname linkend="domdocument.props.documenturi">documentURI</varname>
108
+
</fieldsynopsis>
109
+
<fieldsynopsis>
110
+
<modifier>public</modifier>
111
+
<modifier>readonly</modifier>
112
+
<type>mixed</type>
113
+
<varname linkend="domdocument.props.config">config</varname>
98
114
</fieldsynopsis>
99
115
<fieldsynopsis>
100
116
<modifier>public</modifier>
101
117
<type>bool</type>
102
-
<varname linkend="domdocument.props.resolveexternals">resolveExternals</varname>
118
+
<varname linkend="domdocument.props.formatoutput">formatOutput</varname>
103
119
</fieldsynopsis>
104
120
<fieldsynopsis>
105
121
<modifier>public</modifier>
106
122
<type>bool</type>
107
-
<varname linkend="domdocument.props.standalone">standalone</varname>
123
+
<varname linkend="domdocument.props.validateonparse">validateOnParse</varname>
108
124
</fieldsynopsis>
109
125
<fieldsynopsis>
110
126
<modifier>public</modifier>
111
127
<type>bool</type>
112
-
<varname linkend="domdocument.props.stricterrorchecking">strictErrorChecking</varname>
113
-
<initializer>true</initializer>
128
+
<varname linkend="domdocument.props.resolveexternals">resolveExternals</varname>
114
129
</fieldsynopsis>
115
130
<fieldsynopsis>
116
131
<modifier>public</modifier>
117
132
<type>bool</type>
118
-
<varname linkend="domdocument.props.substituteentities">substituteEntities</varname>
133
+
<varname linkend="domdocument.props.preservewhitespace">preserveWhiteSpace</varname>
119
134
</fieldsynopsis>
120
135
<fieldsynopsis>
121
136
<modifier>public</modifier>
122
137
<type>bool</type>
123
-
<varname linkend="domdocument.props.validateonparse">validateOnParse</varname>
124
-
<initializer>false</initializer>
138
+
<varname linkend="domdocument.props.recover">recover</varname>
125
139
</fieldsynopsis>
126
140
<fieldsynopsis>
127
141
<modifier>public</modifier>
128
-
<type>string</type>
129
-
<varname linkend="domdocument.props.version">version</varname>
142
+
<type>bool</type>
143
+
<varname linkend="domdocument.props.substituteentities">substituteEntities</varname>
130
144
</fieldsynopsis>
131
145
<fieldsynopsis>
132
-
<modifier>readonly</modifier>
133
146
<modifier>public</modifier>
134
-
<type>string</type>
135
-
<varname linkend="domdocument.props.xmlencoding">xmlEncoding</varname>
147
+
<modifier>readonly</modifier>
148
+
<type class="union"><type>DOMElement</type><type>null</type></type>
149
+
<varname linkend="domdocument.props.firstelementchild">firstElementChild</varname>
136
150
</fieldsynopsis>
137
151
<fieldsynopsis>
138
152
<modifier>public</modifier>
139
-
<type>bool</type>
140
-
<varname linkend="domdocument.props.xmlstandalone">xmlStandalone</varname>
153
+
<modifier>readonly</modifier>
154
+
<type class="union"><type>DOMElement</type><type>null</type></type>
155
+
<varname linkend="domdocument.props.lastelementchild">lastElementChild</varname>
141
156
</fieldsynopsis>
142
157
<fieldsynopsis>
143
158
<modifier>public</modifier>
144
-
<type>string</type>
145
-
<varname linkend="domdocument.props.xmlversion">xmlVersion</varname>
159
+
<modifier>readonly</modifier>
160
+
<type>int</type>
161
+
<varname linkend="domdocument.props.childelementcount">childElementCount</varname>
146
162
</fieldsynopsis>
147
163

164
+
<classsynopsisinfo role="comment">&InheritedProperties;</classsynopsisinfo>
165
+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.domnode')/db:partintro/db:section/db:classsynopsis/db:fieldsynopsis[preceding-sibling::db:classsynopsisinfo[1][@role='comment' and text()='&Properties;']]))">
166
+
<xi:fallback/>
167
+
</xi:include>
168
+

148
169
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
149
-
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.domdocument')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
170
+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.domdocument')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[@role='DOMDocument'])">
171
+
<xi:fallback/>
172
+
</xi:include>
173
+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.domdocument')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='DOMDocument'])">
174
+
<xi:fallback/>
175
+
</xi:include>
150
176

151
-
<!-- Again, if the class extends a class use this -->
152
177
<classsynopsisinfo role="comment">&InheritedMethods;</classsynopsisinfo>
153
-
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.domnode')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
154
-

178
+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.domnode')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='DOMNode'])">
179
+
<xi:fallback/>
180
+
</xi:include>
155
181
</classsynopsis>
156
182
<!-- }}} -->
157
183
...
...
@@ -165,17 +191,24 @@
165
191
<term><varname>actualEncoding</varname></term>
166
192
<listitem>
167
193
<para>
168
-
<emphasis>Deprecated</emphasis>. Actual encoding of the document,
169
-
is a readonly equivalent to
194
+
<emphasis>Deprecated as of PHP 8.4.0</emphasis>.
195
+
Actual encoding of the document, is a readonly equivalent to
170
196
<varname linkend="domdocument.props.encoding">encoding</varname>.
171
197
</para>
172
198
</listitem>
173
199
</varlistentry>
200
+
<varlistentry xml:id="domdocument.props.childelementcount">
201
+
<term><varname>childElementCount</varname></term>
202
+
<listitem>
203
+
<para>The number of child elements.</para>
204
+
</listitem>
205
+
</varlistentry>
174
206
<varlistentry xml:id="domdocument.props.config">
175
207
<term><varname>config</varname></term>
176
208
<listitem>
177
209
<para>
178
-
<emphasis>Deprecated</emphasis>. Configuration used when
210
+
<emphasis>Deprecated as of PHP 8.4.0</emphasis>.
211
+
Configuration used when
179
212
<function>DOMDocument::normalizeDocument</function> is
180
213
invoked.
181
214
</para>
...
...
@@ -191,8 +224,8 @@
191
224
<term><varname>documentElement</varname></term>
192
225
<listitem>
193
226
<para>
194
-
This is a convenience attribute that allows direct access to the
195
-
child node that is the document element of the document.
227
+
The <classname>DOMElement</classname> object that is the first
228
+
document element. If not found, this evaluates to &null;.
196
229
</para>
197
230
</listitem>
198
231
</varlistentry>
...
...
@@ -213,10 +246,20 @@
213
246
</para>
214
247
</listitem>
215
248
</varlistentry>
249
+
<varlistentry xml:id="domdocument.props.firstelementchild">
250
+
<term><varname>firstElementChild</varname></term>
251
+
<listitem>
252
+
<para>First child element or &null;.</para>
253
+
</listitem>
254
+
</varlistentry>
216
255
<varlistentry xml:id="domdocument.props.formatoutput">
217
256
<term><varname>formatOutput</varname></term>
218
257
<listitem>
219
-
<para>Nicely formats output with indentation and extra space.</para>
258
+
<para>
259
+
Nicely formats output with indentation and extra space.
260
+
This has no effect if the document was loaded with
261
+
<varname linkend="domdocument.props.preservewhitespace">preserveWhitespace</varname> enabled.
262
+
</para>
220
263
</listitem>
221
264
</varlistentry>
222
265
<varlistentry xml:id="domdocument.props.implementation">
...
...
@@ -228,10 +271,20 @@
228
271
</para>
229
272
</listitem>
230
273
</varlistentry>
274
+
<varlistentry xml:id="domdocument.props.lastelementchild">
275
+
<term><varname>lastElementChild</varname></term>
276
+
<listitem>
277
+
<para>Last child element or &null;.</para>
278
+
</listitem>
279
+
</varlistentry>
231
280
<varlistentry xml:id="domdocument.props.preservewhitespace">
232
281
<term><varname>preserveWhiteSpace</varname></term>
233
282
<listitem>
234
-
<para>Do not remove redundant white space. Default to &true;.</para>
283
+
<para>
284
+
Do not remove redundant white space. Default to &true;.
285
+
Setting this to &false; has the same effect as passing <constant>LIBXML_NOBLANKS</constant>
286
+
as <parameter>option</parameter> to <methodname>DOMDocument::load</methodname> etc.
287
+
</para>
235
288
</listitem>
236
289
</varlistentry>
237
290
<varlistentry xml:id="domdocument.props.recover">
...
...
@@ -276,14 +329,24 @@
276
329
<para>
277
330
<emphasis>Proprietary</emphasis>. Whether or not to substitute
278
331
entities. This attribute is not part of
279
-
the DOM specification and is specific to libxml.
332
+
the DOM specification and is specific to libxml. Default to &false;.
280
333
</para>
334
+
<caution>
335
+
<simpara>
336
+
Enabling entity substitution may facilitate XML External Entity (XXE) attacks.
337
+
</simpara>
338
+
</caution>
281
339
</listitem>
282
340
</varlistentry>
283
341
<varlistentry xml:id="domdocument.props.validateonparse">
284
342
<term><varname>validateOnParse</varname></term>
285
343
<listitem>
286
344
<para>Loads and validates against the DTD. Default to &false;.</para>
345
+
<caution>
346
+
<simpara>
347
+
Enabling validating the DTD may facilitate XML External Entity (XXE) attacks.
348
+
</simpara>
349
+
</caution>
287
350
</listitem>
288
351
</varlistentry>
289
352
<varlistentry xml:id="domdocument.props.version">
...
...
@@ -310,7 +373,10 @@
310
373
<listitem>
311
374
<para>
312
375
An attribute specifying, as part of the XML declaration, whether
313
-
this document is standalone. This is &false; when unspecified.
376
+
this document is standalone.
377
+
This is &false; when unspecified.
378
+
A standalone document is one where there are no external markup declarations.
379
+
An example of such a markup declaration is when the DTD declares an attribute with a default value.
314
380
</para>
315
381
</listitem>
316
382
</varlistentry>
...
...
@@ -328,16 +394,48 @@
328
394
</section>
329
395
<!-- }}} -->
330
396

397
+
<section role="changelog">
398
+
&reftitle.changelog;
399
+
<informaltable>
400
+
<tgroup cols="2">
401
+
<thead>
402
+
<row>
403
+
<entry>&Version;</entry>
404
+
<entry>&Description;</entry>
405
+
</row>
406
+
</thead>
407
+
<tbody>
408
+
<row>
409
+
<entry>8.4.0</entry>
410
+
<entry>
411
+
<varname>actualEncoding</varname> and
412
+
<varname>config</varname> are formally deprecated now.
413
+
</entry>
414
+
</row>
415
+
<row>
416
+
<entry>8.0.0</entry>
417
+
<entry>
418
+
<classname>DOMDocument</classname> implements
419
+
<interfacename>DOMParentNode</interfacename> now.
420
+
</entry>
421
+
</row>
422
+
<row>
423
+
<entry>8.0.0</entry>
424
+
<entry>
425
+
The unimplemented method <methodname>DOMDocument::renameNode</methodname>
426
+
has been removed.
427
+
</entry>
428
+
</row>
429
+
</tbody>
430
+
</tgroup>
431
+
</informaltable>
432
+
</section>
433
+

331
434
<!-- {{{ Notes -->
332
435
<section role="notes">
333
436
&reftitle.notes;
334
-
<note>
335
-
<para>
336
-
The DOM extension uses UTF-8 encoding. Use <function>utf8_encode</function>
337
-
and <function>utf8_decode</function> to work with texts in ISO-8859-1
338
-
encoding or <link linkend="ref.iconv">Iconv</link> for other encodings.
339
-
</para>
340
-
</note>
437
+
&dom.note.utf8;
438
+
&dom.note.json;
341
439
</section>
342
440
<!-- }}} -->
343
441
...
...
@@ -356,8 +454,7 @@
356
454
357
455
&reference.dom.entities.domdocument;
358
456
359
-
</phpdoc:classref>
360
-
457
+
</reference>
361
458
<!-- Keep this comment at the end of the file
362
459
Local variables:
363
460
mode: sgml
...
...
@@ -378,4 +475,3 @@ vim600: syn=xml fen fdm=syntax fdl=2 si
378
475
vim: et tw=78 syn=sgml
379
476
vi: ts=1 sw=1
380
477
-->
381
-

382
478