|
|
XXIX. DOM Functions
The DOM extension is the replacement for the
DOM XML extension from PHP 4.
The extension still contains many old functions, but they should no
longer be used. In particular, functions that are not object-oriented
should be avoided.
The extension allows you to operate on an XML document with the DOM API.
There is no installation needed to use these
functions; they are part of the PHP core.
The API of the module follows the DOM Level 2 standard as closely
as possible. Consequently, the API is fully object-oriented.
It is a good idea to have the DOM standard available when
using this module.
This module defines a number of classes, which are explained in the
following tables. Classes with an equivalent in the DOM standard are
named DOMxxx.
Extends DOMNode. The DOMAttr
interface represents an attribute in an DOMElement object.
Table 1. Name | Type | Read-only | Description |
---|
name | string | yes | The name of the attribute | ownerElement | DOMElement | yes | The element which contains the attribute | schemaTypeInfo | bool | yes | Not implemented yet, always return NULL | specified | bool | yes | Not implemented yet, always return NULL | value | string | no | The value of the attribute |
Extends DOMNode.
Table 2. Name | Type | Read-only | Description |
---|
data | string | no | The contents of the node | length | int | yes | The length of the contents |
Extends DOMCharacterData.
Extends DOMNode.
Table 3. Name | Type | Read-only | Description |
---|
actualEncoding | string | yes | | config | DOMConfiguration | yes | | doctype | DOMDocumentType | yes |
The Document Type Declaration associated with this document.
| documentElement | DOMElement | yes |
This is a convenience attribute that allows direct access to the
child node that is the document element of the document.
| documentURI | string | no |
The location of the document or NULL if undefined.
| encoding | string | no | | formatOutput | bool | no | | implementation | DOMImplementation | yes |
The DOMImplementation object that handles
this document.
| preserveWhiteSpace | bool | no | Do not remove redundant white space. Default to TRUE. | recover | bool | no | | resolveExternals | bool | no |
Set it to TRUE to load external entities from a doctype
declaration. This is useful for including character entities in
your XML document.
| standalone | bool | no | | strictErrorChecking | bool | no | Throws DOMException on errors. Default to TRUE. | substituteEntities | bool | no | | validateOnParse | bool | no | Loads and validates against the DTD. Default to FALSE. | version | string | no | | xmlEncoding | string | yes |
An attribute specifying, as part of the XML declaration, the
encoding of this document. This is NULL when unspecified or when it
is not known, such as when the Document was created in memory.
| xmlStandalone | bool | no |
An attribute specifying, as part of the XML declaration, whether
this document is standalone. This is FALSE when unspecified.
| xmlVersion | string | no |
An attribute specifying, as part of the XML declaration, the
version number of this document. If there is no declaration and if
this document supports the "XML" feature, the value is "1.0".
|
Extends DOMNode
Each DOMDocument has a
doctype attribute whose value is either NULL or a
DOMDocumentType object.
Table 4. Name | Type | Read-only | Description |
---|
publicId | string | yes | The public identifier of the external subset. | systemId | string | yes | The system identifier of the external subset. This may be an
absolute URI or not. | name | string | yes | The name of DTD; i.e., the name immediately following the
DOCTYPE keyword. | entities | DOMNamedNodeMap | yes |
A DOMNamedNodeMap containing the general
entities, both external and internal, declared in the DTD.
| notations | DOMNamedNodeMap | yes |
A DOMNamedNodeMap containing the notations
declared in the DTD.
| internalSubset | string | yes |
The internal subset as a string, or null if there is none. This is
does not contain the delimiting square brackets.
|
Extends DOMNode.
Table 5. Name | Type | Read-only | Description |
---|
schemaTypeInfo | bool | yes | Not implemented yet, always return NULL | tagName | string | yes | The element name |
Extends DOMNode
This interface represents a known entity, either parsed or unparsed, in
an XML document.
Table 6. Name | Type | Read-only | Description |
---|
publicId | string | yes |
The public identifier associated with the entity if specified, and
NULL otherwise.
| systemId | string | yes |
The system identifier associated with the entity if specified, and
NULL otherwise. This may be an absolute URI or not.
| notationName | string | yes |
For unparsed entities, the name of the notation for the entity. For
parsed entities, this is NULL.
| actualEncoding | string | no |
An attribute specifying the encoding used for this entity at the
time of parsing, when it is an external parsed entity. This is
NULL if it an entity from the internal subset or if it is not
known.
| encoding | string | yes |
An attribute specifying, as part of the text declaration, the
encoding of this entity, when it is an external parsed entity. This
is NULL otherwise.
| version | string | yes |
An attribute specifying, as part of the text declaration, the
version number of this entity, when it is an external parsed
entity. This is NULL otherwise.
|
DOM operations raise exceptions under particular circumstances, i.e.,
when an operation is impossible to perform for logical reasons.
See also Chapter 20.
Table 7. Name | Type | Read-only | Description |
---|
code | int | yes | An integer indicating the type of error generated |
The DOMImplementation interface provides a number
of methods for performing operations that are independent of any
particular instance of the document object model.
Table 8. Name | Type | Read-only | Description |
---|
nodeName | string | yes | Returns the most accurate name for the current node type | nodeValue | string | no | The value of this node, depending on its type. | nodeType | int | yes | Gets the type of the node. One of the predefined XML_xxx_NODE constants | parentNode | DOMNode | yes | The parent of this node. | childNodes | DOMNodeList | yes |
A DOMNodeList that contains all children of
this node. If there are no children, this is an empty
DOMNodeList.
| firstChild | DOMNode | yes |
The first child of this node. If there is no such node, this
returns NULL.
| lastChild | DOMNode | yes |
The last child of this node. If there is no such node, this returns
NULL.
| previousSibling | DOMNode | yes |
The node immediately preceding this node. If there is no such node,
this returns NULL.
| nextSibling | DOMNode | yes |
The node immediately following this node. If there is no such node,
this returns NULL.
| attributes | DOMNamedNodeMap | yes |
A DOMNamedNodeMap containing the attributes
of this node (if it is a DOMElement) or
NULL otherwise.
| ownerDocument | DOMDocument | yes |
The DOMDocument object associated with this
node.
| namespaceURI | string | yes |
The namespace URI of this node, or NULL if it is unspecified.
| prefix | string | no |
The namespace prefix of this node, or NULL if it is unspecified.
| localName | string | yes |
Returns the local part of the qualified name of this node.
| baseURI | string | yes |
The absolute base URI of this node or NULL if the implementation
wasn't able to obtain an absolute URI.
| textContent | string | no |
This attribute returns the text content of this node and its
descendants.
|
Table 9. Name | Type | Read-only | Description |
---|
length | int | yes |
The number of nodes in the list. The range of valid child node
indices is 0 to length - 1 inclusive.
|
Extends DOMNode
Table 10. Name | Type | Read-only | Description |
---|
publicId | string | yes | | systemId | string | yes | |
Extends DOMNode.
Table 11. Name | Type | Read-only | Description |
---|
target | string | yes | | data | string | no | |
Extends DOMCharacterData.
Table 12. Name | Type | Read-only | Description |
---|
wholeText | string | yes | |
Table 13. Name | Type | Read-only | Description |
---|
document | DOMDocument | | |
Many examples in this reference require an XML file. We will use
book.xml that contains the following:
Example 1. chapter.xml <?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
]>
<book id="listing">
<title>My lists</title>
<chapter id="books">
<title>My books</title>
<para>
<informaltable>
<tgroup cols="4">
<thead>
<row>
<entry>Title</entry>
<entry>Author</entry>
<entry>Language</entry>
<entry>ISBN</entry>
</row>
</thead>
<tbody>
<row>
<entry>The Grapes of Wrath</entry>
<entry>John Steinbeck</entry>
<entry>en</entry>
<entry>0140186409</entry>
</row>
<row>
<entry>The Pearl</entry>
<entry>John Steinbeck</entry>
<entry>en</entry>
<entry>014017737X</entry>
</row>
<row>
<entry>Samarcande</entry>
<entry>Amine Maalouf</entry>
<entry>fr</entry>
<entry>2253051209</entry>
</row>
<!-- TODO: I have a lot of remaining books to add.. -->
</tbody>
</tgroup>
</informaltable>
</para>
</chapter>
</book> |
|
The constants below are defined by this extension, and
will only be available when the extension has either
been compiled into PHP or dynamically loaded at runtime.
Table 14. XML constants Constant | Value | Description |
---|
XML_ELEMENT_NODE
(integer)
| 1 | Node is a DOMElement |
XML_ATTRIBUTE_NODE
(integer)
| 2 | Node is a DOMAttr |
XML_TEXT_NODE
(integer)
| 3 | Node is a DOMText |
XML_CDATA_SECTION_NODE
(integer)
| 4 | Node is a DOMCharacterData |
XML_ENTITY_REF_NODE
(integer)
| 5 | Node is a DOMEntityReference |
XML_ENTITY_NODE
(integer)
| 6 | Node is a DOMEntity |
XML_PI_NODE
(integer)
| 7 | Node is a DOMProcessingInstruction |
XML_COMMENT_NODE
(integer)
| 8 | Node is a DOMComment |
XML_DOCUMENT_NODE
(integer)
| 9 | Node is a DOMDocument |
XML_DOCUMENT_TYPE_NODE
(integer)
| 10 | Node is a DOMDocumentType |
XML_DOCUMENT_FRAG_NODE
(integer)
| 11 | Node is a DOMDocumentFragment |
XML_NOTATION_NODE
(integer)
| 12 | Node is a DOMNotation |
XML_HTML_DOCUMENT_NODE
(integer)
| 13 | |
XML_DTD_NODE
(integer)
| 14 | |
XML_ELEMENT_DECL_NODE
(integer)
| 15 | |
XML_ATTRIBUTE_DECL_NODE
(integer)
| 16 | |
XML_ENTITY_DECL_NODE
(integer)
| 17 | |
XML_NAMESPACE_DECL_NODE
(integer)
| 18 | |
XML_ATTRIBUTE_CDATA
(integer)
| 1 | |
XML_ATTRIBUTE_ID
(integer)
| 2 | |
XML_ATTRIBUTE_IDREF
(integer)
| 3 | |
XML_ATTRIBUTE_IDREFS
(integer)
| 4 | |
XML_ATTRIBUTE_ENTITY
(integer)
| 5 | |
XML_ATTRIBUTE_NMTOKEN
(integer)
| 7 | |
XML_ATTRIBUTE_NMTOKENS
(integer)
| 8 | |
XML_ATTRIBUTE_ENUMERATION
(integer)
| 9 | |
XML_ATTRIBUTE_NOTATION
(integer)
| 10 | |
Table 15. DOMException constants Constant | Value | Description |
---|
DOM_INDEX_SIZE_ERR
(integer)
| 1 |
If index or size is negative, or greater than the allowed value.
|
DOMSTRING_SIZE_ERR
(integer)
| 2 |
If the specified range of text does not fit into a
DOMString.
|
DOM_HIERARCHY_REQUEST_ERR
(integer)
| 3 | If any node is inserted somewhere it doesn't belong |
DOM_WRONG_DOCUMENT_ERR
(integer)
| 4 |
If a node is used in a different document than the one that created it.
|
DOM_INVALID_CHARACTER_ERR
(integer)
| 5 |
If an invalid or illegal character is specified, such as in a name.
|
DOM_NO_DATA_ALLOWED_ERR
(integer)
| 6 |
If data is specified for a node which does not support data.
|
DOM_NO_MODIFICATION_ALLOWED_ERR
(integer)
| 7 |
If an attempt is made to modify an object where modifications are not allowed.
|
DOM_NOT_FOUND_ERR
(integer)
| 8 |
If an attempt is made to reference a node in a context where it does not exist.
|
DOM_NOT_SUPPORTED_ERR
(integer)
| 9 |
If the implementation does not support the requested type of object or operation.
|
DOM_INUSE_ATTRIBUTE_ERR
(integer)
| 10 |
If an attempt is made to add an attribute that is already in use elsewhere.
|
DOM_INVALID_STATE_ERR
(integer)
| 11 |
If an attempt is made to use an object that is not, or is no longer, usable.
|
DOM_SYNTAX_ERR
(integer)
| 12 | If an invalid or illegal string is specified. |
DOM_INVALID_MODIFICATION_ERR
(integer)
| 13 | If an attempt is made to modify the type of the underlying object. |
DOM_NAMESPACE_ERR
(integer)
| 14 |
If an attempt is made to create or change an object in a way which is
incorrect with regard to namespaces.
|
DOM_INVALID_ACCESS_ERR
(integer)
| 15 |
If a parameter or an operation is not supported by the underlying object.
|
DOM_VALIDATION_ERR
(integer)
| 16 |
If a call to a method such as insertBefore or removeChild would make the Node
invalid with respect to "partial validity", this exception would be raised and
the operation would not be done.
|
|
|
|