Manuel PHP
Précédent |  | Suivant

# XXX. Fonctions DOM

# Introduction

L'extension DOM est le remplacement de l'extension DOM XML en PHP 4. Cette extension contient encore plusieurs anciennes fonctions mais elles ne doivent plus être utilisées. En particulier, les fonctions procédurales.

Cette extension vous permet de manipuler des documents XML avec l'API DOM.

# Installation

Il n'y pas d'installation nécessaire pour utiliser ces fonctions, elles font parties du coeur de PHP.

# Classes pré-définies

L'API de ce module suit, autant que possible, les standards niveau 2 de DOM. En conséquent, l'API est pleinement orientée objets. Il est bien d'avoir les standards DOM sous la main lors de l'utilisation de cette extension.

Ce module définit plusieurs classes, qui sont expliquées dans les tableaux suivants. Les classes avec un équivalent dans les standards sont nommées DOMxxx.

## DOMAttr

Étend DOMNode. L'interface DOMAttr représente un attribut dans l'objet DOMElement.

### Constructeur

- DOMAttr->__construct() - construit un nouvel objet DOMAttr

### Méthodes

- DOMAttr->isId() - Vérifie si un attribut est un ID défini

### Propriétés

Tableau 1.

Nom | Type | Lecture seule | Description
--- | --- | --- | ---
name | string | oui | Le nom de l'attribut
ownerElement | DOMElement | oui | L'élément qui contient l'attribut
schemaTypeInfo | bool | oui | Pas encore implémenté, retourne toujours `NULL`
specified | bool | oui | Pas encore implémenté, retourne toujours `NULL`
value | string | non | La valeur de l'attribut

## DOMCharacterData

Étend DOMNode.

### Méthodes

- DOMCharacterData->appendData() - Ajoute une chaîne à la fin des données du noeud

- DOMCharacterData->deleteData() - Efface une rangée de caractères du noeud

- DOMCharacterData->insertData() - Insère une chaîne à une position 16-bit spécifiée

- DOMCharacterData->replaceData() - Remplace une sous-chaîne d'un noeud DOMCharacterData

- DOMCharacterData->substringData() - Extrait une rangée de données depuis le noeud

### Propriétés

Tableau 2.

Nom | Type | Lecture seule | Description
--- | --- | --- | ---
data | string | non | Le contenu du noeud
length | int | oui | La longueur du contenu

## DOMComment

Étend DOMCharacterData.

### Constructeur

- DOMComment->__construct() - construit un nouvel objet DOMComment

## DOMDocument

Étend DOMNode.

### Constructeur

- DOMDocument->__construct() - construit un nouvel objet DOMDocument

### Méthodes

- DOMDocument->createAttribute() - Crée un nouvel attribut

- DOMDocument->createAttributeNS() - Crée un nouvel noeud d'attribut avec un espace de nom associé

- DOMDocument->createCDATASection() - Crée un nouveau noeud cdata

- DOMDocument->createComment() - Crée un nouveau noeud de commentaire

- DOMDocument->createDocumentFragment() - Crée un nouveau fragment de document

- DOMDocument->createElement() - Crée un nouvel élément

- DOMDocument->createElementNS() - Crée un nouvel élément avec un espace de noms associé

- DOMDocument->createEntityReference() - Crée une nouvelle entité de référence

- DOMDocument->createProcessingInstruction() - Crée un nouveau noeud PI

- DOMDocument->createTextNode() - Crée un nouveau noeud de texte

- DOMDocument->getElementById() - Recherche un élément avec un ID précis

- DOMDocument->getElementsByTagName() - Recherche tous les éléments ayant un tag portant un nom donné

- DOMDocument->getElementsByTagNameNS() - Recherche tous les éléments ayant un tag portant un nom donné dans un espace de noms spécifié

- DOMDocument->importNode() - Importe un noeud dans le document courant

- DOMDocument->load() - Charge du XML depuis un fichier

- DOMDocument->loadHTML() - Charge du HTML depuis une chaîne de caractères

- DOMDocument->loadHTMLFile() - Charge du HTML depuis un fichier

- DOMDocument->loadXML() - Charge du XML depuis une chaîne de caractères

- DOMDocument->normalize() - Normalise un document

- DOMDocument->relaxNGValidate() - Effectue une validation relaxNG sur le document

- DOMDocument->relaxNGValidateSource() - Effectue une validation relaxNG sur le document

- DOMDocument->save() - Sauvegarde l'arbre interne XML dans un fichier

- DOMDocument->saveHTML() - Sauvegarde le document interne dans une chaîne de caractères en utilisant un formatage HTML

- DOMDocument->saveHTMLFile() - Sauvegarde le document interne dans un fichier en utilisant un formatage HTML

- DOMDocument->saveXML() - Sauvegarde l'arbre interne XML dans une chaîne de caractères

- DOMDocument->schemaValidate() - Valide un document basé sur un schéma

- DOMDocument->schemaValidateSource() - Valide un document basé sur un schéma

- DOMDocument->validate() - Valide un document en se basant sur sa DTD

- DOMDocument->xinclude() - Remplace les XIncludes dans un objet DOMDocument

### Propriétés

Tableau 3.

Nom | Type | Lecture seule | Description
--- | --- | --- | ---
actualEncoding | string | oui |
config | DOMConfiguration | oui |
doctype | DOMDocumentType | oui | La déclaration de type de document associée avec ce document.
documentElement | DOMElement | oui | C'est un attribut de convenance qui permet l'accès direct à l'enfant d'un noeud qui est l'élément document de ce document.
documentURI | string | non | La localisation du document ou `NULL` si non défini.
encoding | string | non |
formatOutput | bool | non |
implementation | DOMImplementation | oui | L'objet DOMImplementation qui représente ce document.
preserveWhiteSpace | bool | non | Ne pas supprimer les espaces redondants. Vaut `TRUE` par défaut.
recover | bool | non |
resolveExternals | bool | non | Définir à `TRUE` pour charger les entités externes depuis une déclaration doctype. Ceci est utile pour inclure des entités correspondants à des caractères dans vos documents XML.
standalone | bool | non |
strictErrorChecking | bool | non | Envoie une DOMException en cas d'erreurs. Vaut par défaut `TRUE`.
substituteEntities | bool | non |
validateOnParse | bool | non | Charge et valide à nouveau la DTD. Vaut par défaut `FALSE`.
version | string | non |
xmlEncoding | string | oui | Un attribut spécifiant, en tant que partie de la déclaration XML, l'encodage de ce document. Il vaut `NULL` lorsqu'il n'et pas spécifié ou lorsqu'il n'est pas connu, par exemple, lorsque le document a été créé en mémoire.
xmlStandalone | bool | non | Un attribut spécifiant, en tant que partie de la déclaration XML, si oui ou non le document est autonome. Il vaut `FALSE` si non spécifié.
xmlVersion | string | non | Un attribut spécifiant, en tant que partie de la déclaration XML, le numéro de version de ce document. S'il n'y a pas de déclaration et si le document supporte la fonctionnalité "XML", la valeur sera "1.0".

## DOMDocumentType

Étend DOMNode

Chaque DOMDocument a un attribut doctype de valeur soit `NULL`, soit un objet DOMDocumentType.

### Propriétés

Tableau 4.

Nom | Type | Lecture seule | Description
--- | --- | --- | ---
publicId | string | oui | L'identifiant public du sous-ensemble externe.
systemId | string | oui | L'identifiant système du sous-ensemble externe. Il peut être une URI absolue ou non.
name | string | oui | Le nom de la DTD ; i.e. le nom suivant immédiatement le mot clé DOCTYPE
entities | DOMNamedNodeMap | oui | Un DOMNamedNodeMap contenant les entités générales, externes et internes, déclarées dans la DTD.
notations | DOMNamedNodeMap | oui | Un DOMNamedNodeMap contenant les notations déclarées dans la DTD.
internalSubset | string | oui | Le sous-ensemble interne en tant que chaîne de caractères ou `NULL` s'il n'y en a pas. Ceci ne contient pas les crochets délimitants.

## DOMElement

Étend DOMNode.

### Constructeur

- DOMElement->__construct() - construit un nouvel objet DOMElement

### Méthodes

- DOMElement->getAttribute() - Retourne la valeur d'un attribut

- DOMElement->getAttributeNode() - Retourne le noeud d'un attribut

- DOMElement->getAttributeNodeNS() - Retourne le noeud d'un attribut

- DOMElement->getAttributeNS() - Retourne la valeur d'un attribut

- DOMElement->getElementsByTagName() - Récupère les éléments par le nom de leurs tags

- DOMElement->getElementsByTagNameNS() - Récupère les éléments par leur namespaceURI et leur localName

- DOMElement->hasAttribute() - Vérifie si un attribut existe

- DOMElement->hasAttributeNS() - Vérifie si un attribut existe

- DOMElement->removeAttribute() - Supprime un attribut

- DOMElement->removeAttributeNode() - Supprime un attribut

- DOMElement->removeAttributeNS() - Supprime un attribut

- DOMElement->setAttribute() - Ajoute un nouvel attribut

- DOMElement->setAttributeNode() - Ajoute un nouvel attribut à un élément

- DOMElement->setAttributeNodeNS() - Ajoute un nouvel attribut à un élément

- DOMElement->setAttributeNS() - Ajoute un nouvel attribut

### Propriétés

Tableau 5.

Nom | Type | Lecture seule | Description
--- | --- | --- | ---
schemaTypeInfo | bool | oui | Pas encore implémenté, retourne toujours `NULL`
tagName | string | oui | Le nom de l'élément

## DOMEntity

Étend DOMNode

Cette interface représente une entité connue, analysée ou non, du document XML.

### Propriétés

Tableau 6.

Nom | Type | Lecture seule | Description
--- | --- | --- | ---
publicId | string | oui | L'identifiant public associé à l'entité si spécifiée, `NULL` sinon.
systemId | string | oui | L'identifiant système associé à l'entité si spécifié, `NULL` sinon. Ceci peut être une URI absolue ou non.
notationName | string | oui | Pour les entités non-analysées, le nom de la notation pour cette entité. Pour les entités analysées, ceci vaut `NULL`.
actualEncoding | string | non | Un attribut spécifiant l'encodage utilisé pour cette entité au moment de l'analyse, lorsque c'est une entité analysée externe. Ceci vaut `NULL` si c'est une entité du sous-ensemble externe ou si elle n'est pas connue.
encoding | string | oui | Un attribut spécifiant, en tant que partie de la déclaration texte, l'encodage de cette entité, lorsque c'est une entité analysée externe. Ceci vaut `NULL` sinon.
version | string | oui | Un attribut spécifiant, en tant que partie de la déclaration texte, le numéro de version de cette entité, lorsque c'est une entité analysée externe. Ceci vaut `NULL` sinon.

## DOMEntityReference

Étend DOMNode.

### Constructeur

- DOMEntityReference->__construct() - construit un nouvel objet DOMEntityReference

## DOMException

Les opérations DOM lancent des exceptions sous des circonstances particulières, i.e., lorsqu'une opération est impossible à effectuer pour des raisons de logique.

Voir aussi Chapitre 20.

### Propriétés

Tableau 7.

Nom | Type | Lecture seule | Description
--- | --- | --- | ---
code | int | oui | Un entier indiquant le type d'erreur générée

## DOMImplementation

L'interface DOMImplementation fournit un nombre de méthodes pour effectuer des opérations qui sont indépendant de toute instance du model objet du document.

### Constructeur

- DOMImplementation->__construct() - construit un nouvel objet DOMImplementation

### Méthodes

- DOMImplementation->createDocument() - Crée un objet DOM Document du type spécifié avec ces éléments

- DOMImplementation->createDocumentType() - Crée un objet DOMDocumentType vide

- DOMImplementation->hasFeature() - Test si l'implémentation DOM implémente une fonctionnalité spécifique

## DOMNode

### Méthodes

- DOMNode->appendChild() - Ajoute un nouvel enfant à la fin des enfants

- DOMNode->cloneNode() - Clone un noeud

- DOMNode->hasAttributes() - Vérifie si un noeud possède des attributs

- DOMNode->hasChildNodes() - Vérifie si un noeud possède des enfants

- DOMNode->insertBefore() - Ajoute un nouvel enfant juste avant un noeud référencé

- DOMNode->isSameNode() - Indique si deux noeuds sont identiques

- DOMNode->isSupported() - Vérifie si une fonctionnalité est supporté par une version spécifique

- DOMNode->lookupNamespaceURI() - Retourne l'URI de l'espace de noms du noeud basé sur le préfixe

- DOMNode->lookupPrefix() - Retourne le préfixe de l'espace de noms d'un noeud, basé sur l'URI de l'espace de noms

- DOMNode->normalize() - Normalise le noeud

- DOMNode->removeChild() - Supprime un enfant de la liste des enfants

- DOMNode->replaceChild() - Remplace un enfant

### Propriétés

Tableau 8.

Nom | Type | Lecture seule | Description
--- | --- | --- | ---
nodeName | string | oui | Retourne le nom le plus précis possible pour le type de noeud courant
nodeValue | string | non | La valeur de ce noeud, dépendant de son type.
nodeType | int | oui | Récupère le type du noeud. Une des constantes XML_xxx_NODE prédéfinies
parentNode | DOMNode | oui | Le parent de ce noeud
childNodes | DOMNodeList | oui | Un DOMNodeList qui contient tous les enfants de ce noeud. S'il n'y a pas d'enfant, ce sera un DOMNodeList vide.
firstChild | DOMNode | oui | Le premier enfant de ce noeud. S'il n'y pas de tel noeud, ceci retourne `NULL`.
lastChild | DOMNode | oui | Le dernier enfant de ce noeud. S'il n'y a pas de tel noeud, ceci retourne `NULL`.
previousSibling | DOMNode | oui | Le noeud précédent immédiatement ce noeud. S'il n'y a pas de tel noeud, ceci retourne `NULL`.
nextSibling | DOMNode | oui | Le noeud suivant immédiatement ce noeud. S'il n'y a pas de tel noeud, ceci retourne `NULL`.
attributes | DOMNamedNodeMap | oui | Un DOMNamedNodeMap contenant les attributs de ce noeud (si c'est un DOMElement) ou `NULL` sinon.
ownerDocument | DOMDocument | oui | Un objet DOMDocument associé à ce noeud.
namespaceURI | string | oui | L'URI de l'espace de noms de ce noeud, ou `NULL` si non spécifié.
prefix | string | non | Le préfixe de l'espace de noms de ce noeud, ou `NULL` si non spécifié.
localName | string | oui | Retourne la partie locale du nom qualifié de ce noeud.
baseURI | string | oui | La base absolue de l'URI de ce noeud ou `NULL` si l'implémentation n'est pas arrivée à obtenir une URI absolue.
textContent | string | non | Cet attribut retourne le contenu texte de ce noeud et ces descendants.

## DOMNodeList

### Méthodes

- DOMNodelist->item() - Retrieves a node specified by index

### Propriétés

Tableau 9.

Nom | Type | Lecture seule | Description
--- | --- | --- | ---
length | int | oui | Le nombre de noeuds dans la liste. La plage des indices des noeuds enfants valides est de 0 à length - 1 inclusivement.

## DOMNotation

Étend DOMNode

### Propriétés

Tableau 10.

Nom | Type | Lecture seule | Description
--- | --- | --- | ---
publicId | string | oui |
systemId | string | oui |

## DOMProcessingInstruction

Étend DOMNode.

### Constructeur

- DOMProcessingInstruction->__construct() - construit un nouvel objet DOMProcessingInstruction

### Propriétés

Tableau 11.

Nom | Type | Lecture seule | Description
--- | --- | --- | ---
target | string | oui |
data | string | non |

## DOMText

Étend DOMCharacterData.

### Constructeur

- DOMText->__construct() - construit un nouvel objet DOMText

### Méthodes

- DOMText->isWhitespaceInElementContent() - Indique si ce noeud de texte contient des espaces

- DOMText->splitText() - Sépare le noeud en deux noeuds à une position spécifique

### Propriétés

Tableau 12.

Nom | Type | Lecture seule | Description
--- | --- | --- | ---
wholeText | string | oui |

## DOMXPath

### Constructeur

- DOMXPath->__construct() - Construit un nouvel objet DOMXPath

### Méthodes

- DOMXPath->registerNamespace() - Enregistre l'espace de noms avec l'objet DOMXpath

- DOMXPath->evaluate() - Évalue l'expression XPath donnée et retourne le résultat écrit

- DOMXPath->query() - Évalue l'expression XPath donnée

### Propriétés

Tableau 13.

Nom | Type | Lecture seule | Description
--- | --- | --- | ---
document | DOMDocument |  |

# Exemples

La plupart des exemples de cette référence requièrent un fichier XML. Nous utiliserons le fichier `book.xml` qui contient ce qui suit :

Exemple 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>

# Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

Tableau 14. Constantes XML

Constante | Valeur | Description
--- | --- | ---
`XML_ELEMENT_NODE` (entier) | 1 | Le noeud est un DOMElement
`XML_ATTRIBUTE_NODE` (entier) | 2 | Le noeud est un DOMAttr
`XML_TEXT_NODE` (entier) | 3 | Le noeud est un DOMText
`XML_CDATA_SECTION_NODE` (entier) | 4 | Le noeud est un DOMCharacterData
`XML_ENTITY_REF_NODE` (entier) | 5 | Le noeud est un DOMEntityReference
`XML_ENTITY_NODE` (entier) | 6 | Le noeud est un DOMEntity
`XML_PI_NODE` (entier) | 7 | Le noeud est un DOMProcessingInstruction
`XML_COMMENT_NODE` (entier) | 8 | Le noeud est un DOMComment
`XML_DOCUMENT_NODE` (entier) | 9 | Le noeud est un DOMDocument
`XML_DOCUMENT_TYPE_NODE` (entier) | 10 | Le noeud est un DOMDocumentType
`XML_DOCUMENT_FRAG_NODE` (entier) | 11 | Le noeud est un DOMDocumentFragment
`XML_NOTATION_NODE` (entier) | 12 | Le noeud est un DOMNotation
`XML_HTML_DOCUMENT_NODE` (entier) | 13 |
`XML_DTD_NODE` (entier) | 14 |
`XML_ELEMENT_DECL_NODE` (entier) | 15 |
`XML_ATTRIBUTE_DECL_NODE` (entier) | 16 |
`XML_ENTITY_DECL_NODE` (entier) | 17 |
`XML_NAMESPACE_DECL_NODE` (entier) | 18 |
`XML_ATTRIBUTE_CDATA` (entier) | 1 |
`XML_ATTRIBUTE_ID` (entier) | 2 |
`XML_ATTRIBUTE_IDREF` (entier) | 3 |
`XML_ATTRIBUTE_IDREFS` (entier) | 4 |
`XML_ATTRIBUTE_ENTITY` (entier) | 5 |
`XML_ATTRIBUTE_NMTOKEN` (entier) | 7 |
`XML_ATTRIBUTE_NMTOKENS` (entier) | 8 |
`XML_ATTRIBUTE_ENUMERATION` (entier) | 9 |
`XML_ATTRIBUTE_NOTATION` (entier) | 10 |

Tableau 15. Constantes DOMException

Constante | Valeur | Description
--- | --- | ---
`DOM_INDEX_SIZE_ERR` (entier) | 1 | Si l'index ou la taille est négatif ou plus grand que la valeur autorisée.
`DOMSTRING_SIZE_ERR` (entier) | 2 | Si la rangée spécifiée de texte ne tient pas dans le DOMString.
`DOM_HIERARCHY_REQUEST_ERR` (entier) | 3 | Si un noeud est inséré à un endroit non autorisé
`DOM_WRONG_DOCUMENT_ERR` (entier) | 4 | Si un noeud est utilisé dans un document autre que celui qui l'a créé.
`DOM_INVALID_CHARACTER_ERR` (entier) | 5 | Si un caractère invalide ou non autorisé est spécifié, par exemple, dans un nom.
`DOM_NO_DATA_ALLOWED_ERR` (entier) | 6 | Si des données sont spécifiées dans un noeud qui ne supporte pas les données.
`DOM_NO_MODIFICATION_ALLOWED_ERR` (entier) | 7 | Si une tentative est faite de modifier un objet où les modifications ne sont pas autorisées.
`DOM_NOT_FOUND_ERR` (entier) | 8 | Si une tentative est faite de référencer un noeud dans un contexte où il n'existe pas.
`DOM_NOT_SUPPORTED_ERR` (entier) | 9 | Si l'implémentation ne supporte pas le type requis de l'objet ou de l'opération.
`DOM_INUSE_ATTRIBUTE_ERR` (entier) | 10 | Si une tentative est faite d'ajouter un attribut qui est déjà utilisé autre part.
`DOM_INVALID_STATE_ERR` (entier) | 11 | Si une tentative est faITE D'UTIliser un objet qui n'est pas, ou n'est plus, utilisable.
`DOM_SYNTAX_ERR` (entier) | 12 | Si une chaîne de caractères invalide ou illégale est spécifiée.
`DOM_INVALID_MODIFICATION_ERR` (entier) | 13 | Si une tentative est faite de modifier le type d'un objet fondamental.
`DOM_NAMESPACE_ERR` (entier) | 14 | Si une tentative est faite de créer ou de modifier un objet dans un sens qui est incorrect au regard de l'espace de noms.
`DOM_INVALID_ACCESS_ERR` (entier) | 15 | Si un paramètre ou une opération n'est pas supporté par l'objet fondamental.
`DOM_VALIDATION_ERR` (entier) | 16 | Si un appel à une méthode tel que insertBefore ou removeChild voudrait rendre le noeud invalide avec le respect de la validation partielle, cette exception sera exécutée et l'opération ne sera pas effectuée.

Précédent | Sommaire | Suivant
scandir | Niveau supérieur | DOMAttr->__construct()