reference/dom/domdocument/registernodeclass.xml
0e2dfef689e3b40b8a826a0f64ba741863ee8c2a
...
...
@@ -7,10 +7,10 @@
7
7
</refnamediv>
8
8
<refsect1 role="description">
9
9
&reftitle.description;
10
-
<methodsynopsis>
11
-
<modifier>public</modifier> <type>bool</type><methodname>DOMDocument::registerNodeClass</methodname>
12
-
<methodparam><type>string</type><parameter>baseclass</parameter></methodparam>
13
-
<methodparam><type>string</type><parameter>extendedclass</parameter></methodparam>
10
+
<methodsynopsis role="DOMDocument">
11
+
<modifier>public</modifier> <type>true</type><methodname>DOMDocument::registerNodeClass</methodname>
12
+
<methodparam><type>string</type><parameter>baseClass</parameter></methodparam>
13
+
<methodparam><type class="union"><type>string</type><type>null</type></type><parameter>extendedClass</parameter></methodparam>
14
14
</methodsynopsis>
15
15

16
16
<para>
...
...
@@ -20,6 +20,11 @@
20
20
<para>
21
21
This method is not part of the DOM standard.
22
22
</para>
23
+
<caution>
24
+
<simpara>
25
+
The constructor of the objects of the registered node classes is not called.
26
+
</simpara>
27
+
</caution>
23
28
</refsect1>
24
29

25
30
<refsect1 role="parameters">
...
...
@@ -27,7 +32,7 @@
27
32
<para>
28
33
<variablelist>
29
34
<varlistentry>
30
-
<term><parameter>baseclass</parameter></term>
35
+
<term><parameter>baseClass</parameter></term>
31
36
<listitem>
32
37
<para>
33
38
The DOM class that you want to extend. You can find a list of these
...
...
@@ -36,11 +41,11 @@
36
41
</listitem>
37
42
</varlistentry>
38
43
<varlistentry>
39
-
<term><parameter>extendedclass</parameter></term>
44
+
<term><parameter>extendedClass</parameter></term>
40
45
<listitem>
41
46
<para>
42
47
Your extended class name. If &null; is provided, any previously
43
-
registered class extending <parameter>baseclass</parameter> will
48
+
registered class extending <parameter>baseClass</parameter> will
44
49
be removed.
45
50
</para>
46
51
</listitem>
...
...
@@ -52,10 +57,33 @@
52
57
<refsect1 role="returnvalues">
53
58
&reftitle.returnvalues;
54
59
<para>
55
-
&return.success;
60
+
&return.true.always;
56
61
</para>
57
62
</refsect1>
58
63

64
+
<refsect1 role="changelog">
65
+
&reftitle.changelog;
66
+
<informaltable>
67
+
<tgroup cols="2">
68
+
<thead>
69
+
<row>
70
+
<entry>&Version;</entry>
71
+
<entry>&Description;</entry>
72
+
</row>
73
+
</thead>
74
+
<tbody>
75
+
<row>
76
+
<entry>8.4.0</entry>
77
+
<entry>
78
+
<methodname>DOMDocument::registerNodeClass</methodname>
79
+
now has a tentative return of <type>true</type>.
80
+
</entry>
81
+
</row>
82
+
</tbody>
83
+
</tgroup>
84
+
</informaltable>
85
+
</refsect1>
86
+

59
87
<refsect1 role="examples">
60
88
&reftitle.examples;
61
89
<para>
...
...
@@ -138,33 +166,44 @@ text in child
138
166
<para>
139
167
When instantiating a custom <classname>DOMDocument</classname> the
140
168
<varname>ownerDocument</varname> property will refer to the instantiated
141
-
class, meaning there is no need (and in fact not possible) to use
169
+
class. However, if all references to that class are removed, it
170
+
will be destroyed and new <classname>DOMDocument</classname> will be
171
+
created instead. For that reason you might use
142
172
<function>DOMDocument::registerNodeClass</function> with
143
173
<classname>DOMDocument</classname>
144
174
</para>
145
175
<programlisting role="php">
146
176
<![CDATA[
147
177
<?php
148
-
class myDOMDocument extends DOMDocument {
178
+
class MyDOMDocument extends DOMDocument {
149
179
}
150
180

151
-
class myOtherDOMDocument extends DOMDocument {
181
+
class MyOtherDOMDocument extends DOMDocument {
152
182
}
153
183

154
-
// Create myDOMDocument with some XML
155
-
$doc = new myDOMDocument;
184
+
// Create MyDOMDocument with some XML
185
+
$doc = new MyDOMDocument;
156
186
$doc->loadXML("<root><element><child>text in child</child></element></root>");
157
187

158
188
$child = $doc->getElementsByTagName("child")->item(0);
159
189

160
-
// The current owner of the node is myDOMDocument
190
+
// The current owner of the node is MyDOMDocument
191
+
var_dump(get_class($child->ownerDocument));
192
+
// MyDOMDocument is destroyed
193
+
unset($doc);
194
+
// And new DOMDocument instance is created
161
195
var_dump(get_class($child->ownerDocument));
162
196

163
-
// Import a node from myDOMDocument
164
-
$newdoc = new myOtherDOMDocument;
197
+
// Import a node from MyDOMDocument
198
+
$newdoc = new MyOtherDOMDocument;
165
199
$child = $newdoc->importNode($child);
166
200

167
-
// The new owner of the node has changed to myOtherDOMDocument
201
+
// Register custom DOMDocument
202
+
$newdoc->registerNodeClass("DOMDocument", "MyOtherDOMDocument");
203
+

204
+
var_dump(get_class($child->ownerDocument));
205
+
unset($doc);
206
+
// New MyOtherDOMDocument is created
168
207
var_dump(get_class($child->ownerDocument));
169
208
?>
170
209
]]>
...
...
@@ -172,8 +211,50 @@ var_dump(get_class($child->ownerDocument));
172
211
&example.outputs;
173
212
<screen role="xml">
174
213
<![CDATA[
175
-
string(13) "myDOMDocument"
176
-
string(18) "myOtherDOMDocument"
214
+
string(13) "MyDOMDocument"
215
+
string(11) "DOMDocument"
216
+
string(18) "MyOtherDOMDocument"
217
+
string(18) "MyOtherDOMDocument"
218
+
]]>
219
+
</screen>
220
+
</example>
221
+
</para>
222
+
<para>
223
+
<example xml:id="domdocument.registernodeclass.example.transient">
224
+
<title>Custom objects are transient</title>
225
+
<caution>
226
+
<simpara>
227
+
Objects of the registered node classes are transient, i.e. they are
228
+
destroyed when they are no longer referenced from PHP code, and recreated
229
+
when being retrieved again. That implies that custom property values will be
230
+
lost after recreation.
231
+
</simpara>
232
+
</caution>
233
+
<programlisting role="php">
234
+
<![CDATA[
235
+
<?php
236
+
class MyDOMElement extends DOMElement
237
+
{
238
+
public $myProp = 'default value';
239
+
}
240
+

241
+
$doc = new DOMDocument();
242
+
$doc->registerNodeClass('DOMElement', 'MyDOMElement');
243
+

244
+
$node = $doc->createElement('a');
245
+
$node->myProp = 'modified value';
246
+
$doc->appendChild($node);
247
+

248
+
echo $doc->childNodes[0]->myProp, PHP_EOL;
249
+
unset($node);
250
+
echo $doc->childNodes[0]->myProp, PHP_EOL;
251
+
?>]]>
252
+
</programlisting>
253
+
&example.outputs;
254
+
<screen role="xml">
255
+
<![CDATA[
256
+
modified value
257
+
default value
177
258
]]>
178
259
</screen>
179
260
</example>
...
...
@@ -181,7 +262,6 @@ string(18) "myOtherDOMDocument"
181
262
</refsect1>
182
263

183
264
</refentry>
184
-

185
265
<!-- Keep this comment at the end of the file
186
266
Local variables:
187
267
mode: sgml
188
268



Translation status