XXVIII. Fonctions DOM XML

Introduction

L'extension DOM XML a été reprise en main en PHP 4.3.0 pour être mieux compatible avec les standards DOM. L'extension contient encore de vieilles fonctions, mais elles ne sont plus utilisées. En particulier, les fonctions qui ne sont pas orientées objets ne doivent pas être utilisées.

Cette extension vous permet de générer des documents XML avec les API DOM. Elle fournit aussi une fonction domxml_xmltree() qui transforme un fichier XML en tableau PHP. Actuellement, ce tableau est accessible uniquement en lecture. Cela ne siginifie pas que vous ne pouvez pas le modifier, mais cela n'aurait aucun sens car DomDocument_dump_mem() ne pourra pas prendre ces modifications en considération. Par conséquent, si vous voulez lire un fichier XML et écrire sa version modifiée, utilisez les fonctions DomDocument_create_text_node(), set_attribute(), etc. et finalement DomDocument_dump_mem().

Note : Cette extension a été déplacée dans le module PECL et ne sera plus intégrée PHP.5.0.0.

Note : Cette extension n'est plus considérée comme expérimental. Néanmoins, elle ne sera jamais distribuée avec PHP 5 mais uniquement avec PHP 4. Si vous avez besoin du support DOM XML avec PHP 5, vous pouvez utiliser l'extension DOM. domxml n'est pas compatible avec l'extension DOM.

Pré-requis

Cette extension utilise la bibliothèque GNOME XML. Téléchargez là, puis installez là. Vous aurez besoin de la version libxml-2.4.14 ou plus récent. Pour utiliser les fonctionnalités DOM XSLT vous pouvez utiliser la bibliothèque libxslt et les progrès des EXSLT (http://www.exslt.org/). Téléchargez et installez ces bibliothèques si vous envisagez d'exploiter ces fonctionnalités. Vous aurez besoin d'au moins libxslt-1.0.18.

Installation

Cette extension PECL n'est pas intégrée à PHP. Des informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : http://pecl.php.net/package/domxml.

En PHP 4, les sources de cette extension PECL peuvent être trouvées dans le dossier ext/ avec les sources de PHP ou sur le lien PECL ci-dessous. Cette extension est uniquement disponible si PHP a été configuré lors de la compilation avec l'option --with-dom=[DIR]. Ajoutez --with-dom-xslt[=DIR] pour inclure le support DOM XSLT. DIR est le dossier d'installatoin de libxslt. Ajoutez --with-dom-exslt[=DIR] pour inclure le support DOM EXSLT. DIR est le dossier d'installation de libxsl.

Les utilisateurs de Windows doivent activer la bibliothèque php_domxml.dll dans le php.ini pour pouvoir utiliser ces fonctions. En PHP 4, cette bibliothèque DLL se trouve dans le dossier extensions/ avec les binaires PHP pour Windows téléchargées. Vous pouvez télécharger ces bibliothèques DLL pour ces extensions PECL depuis la page de téléchargement de PHP sous sur la page http://snaps.php.net/. En outre, il y a une DLL additionnelle qui doit être disponible à votre PATH système pour faire fonctionner cette extension. En PHP 4, elle se trouve dans le dossier dlls/. Son nom : Pour PHP <= 4.2.0, c'est libxml2.dll. Pour PHP >= 4.3.0, c'est iconv.dll. Et depuis PHP 5.0.0, iconv est compilé dans les binaires PHP pour Windows par défaut, donc, aucune bibliothèque supplémentaire n'est nécessaire.

Fonctions dépréciées

Il y a un groupe de fonctions qui ne sont pas compatibles avec les standards DOM et qui ne devraient plus être utilisées. Ces fonctions sont listées dans la table ci-dessous. La fonction DomNode_append_child() a vu son comportement changer. Désormais, elle ajoute un fils et non pas un frère. Si cela casse votre application, utilisez plutôt la fonction DomNode_append_sibling(), qui ne fait pas partie des standards.

Tableau 1. Fonctions abandonnées et leur remplacement

Ancienne fonctionNouvelle fonction
xmldocdomxml_open_mem()
xmldocfiledomxml_open_file()
domxml_new_xmldocdomxml_new_doc()
domxml_dump_memDomDocument_dump_mem()
domxml_dump_mem_fileDomDocument_dump_file()
DomDocument_dump_mem_fileDomDocument_dump_file()
DomDocument_add_rootDomDocument_create_element() suivie de DomNode_append_child()
DomDocument_dtdDomDocument_doctype()
DomDocument_rootDomDocument_document_element()
DomDocument_childrenDomNode_child_nodes()
DomDocument_imported_nodePas de remplacement.
DomNode_add_childCréez un nouveau noeud avec DomDocument_create_element() puis ajoutez-le avec DomNode_append_child().
DomNode_childrenDomNode_child_nodes()
DomNode_parentDomNode_parent_node()
DomNode_new_childCréez un nouveau noeud avec DomDocument_create_element() puis ajoutez-le avec DomNode_append_child().
DomNode_set_contentCréez un nouveau noeud avec DomDocument_create_text_node() puis ajoutez-le avec DomNode_append_child().
DomNode_get_contentLe contenu est juste un noeud de texte, et est accessible via DomNode_child_nodes().
DomNode_set_contentLe contenu est juste un noeud de texte, et peut être ajouté avec DomNode_append_child().

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 2. Constantes XML

ConstantValueDescription
XML_ELEMENT_NODE (entier) 1Node est un élément
XML_ATTRIBUTE_NODE (entier) 2Node est un attribut
XML_TEXT_NODE (entier) 3Node est un texte
XML_CDATA_SECTION_NODE (entier) 4 
XML_ENTITY_REF_NODE (entier) 5 
XML_ENTITY_NODE (entier) 6Node est une entité comme  
XML_PI_NODE (entier) 7Node est une instruction de script
XML_COMMENT_NODE (entier) 8Node est un commentaire
XML_DOCUMENT_NODE (entier) 9Node est un document
XML_DOCUMENT_TYPE_NODE (entier) 10 
XML_DOCUMENT_FRAG_NODE (entier) 11 
XML_NOTATION_NODE (entier) 12 
XML_GLOBAL_NAMESPACE (entier) 1 
XML_LOCAL_NAMESPACE (entier) 2 
XML_HTML_DOCUMENT_NODE (entier)   
XML_DTD_NODE (entier)   
XML_ELEMENT_DECL_NODE (entier)   
XML_ATTRIBUTE_DECL_NODE (entier)   
XML_ENTITY_DECL_NODE (entier)   
XML_NAMESPACE_DECL_NODE (entier)   
XML_ATTRIBUTE_CDATA (entier)   
XML_ATTRIBUTE_ID (entier)   
XML_ATTRIBUTE_IDREF (entier)   
XML_ATTRIBUTE_IDREFS (entier)   
XML_ATTRIBUTE_ENTITY (entier)   
XML_ATTRIBUTE_NMTOKEN (entier)   
XML_ATTRIBUTE_NMTOKENS (entier)   
XML_ATTRIBUTE_ENUMERATION (entier)   
XML_ATTRIBUTE_NOTATION (entier)   
XPATH_UNDEFINED (entier)   
XPATH_NODESET (entier)   
XPATH_BOOLEAN (entier)   
XPATH_NUMBER (entier)   
XPATH_STRING (entier)   
XPATH_POINT (entier)   
XPATH_RANGE (entier)   
XPATH_LOCATIONSET (entier)   
XPATH_USERS (entier)   
XPATH_NUMBER (entier)   

Classes

L'API de ce module suit le standard DOM niveau 2 aussi fidèlement que possible. Par conséquent, l'API est totalement orientée objet. C'est une bonne idée d'avoir les standards DOM disponibles sous la main, lorsque vous utilisez ce module. Bien que cette API soit orientée objet, il existe de nombreuses fonctions qui peuvent être appelées d'une manière non objet, en passant l'objet à utiliser comme premier argument de la fonction. Cest fonctions sont essentiellement conservées pour assurer la compatibilité avec les extensions plus anciennes, et ne doivent pas être utilisées.

Cette API diffère de l'API officielle DOM en deux points. Le premier est que tous les attributs des classes sont implémentés comme des fonctions du même nom. Le second est que les noms des fonctions suivent les standards PHP. Cela signifie que la fonction DOM lastChild() s'écrit en PHP last_child().

Ce module définit un grand nombre de classe, qui sont listés en incluant leur méthodes dans les tables suivantes. Les classes ayant un équivalent DOM sont nommées DOMxxx.

Tableau 3. Liste de classes

Nom de la classeClasse parente
DomAttributeDomNode
DomCDataDomNode
DomCommentDomCData : DomNode
DomDocumentDomNode
DomDocumentTypeDomNode
DomElementDomNode
DomEntityDomNode
DomEntityReferenceDomNode
DomProcessingInstructionDomNode
DomTextDomCData : DomNode
ParserActuellement, toujours appelée DomParser
XPathContext 

Tableau 4. DomDocument class (DomDocument : DomNode)

Nom de la méthodeNom de la fonctionRemarques
doctypeDomDocument_doctype() 
document_elementDomDocument_document_element() 
create_elementDomDocument_create_element() 
create_text_nodeDomDocument_create_text_node() 
create_commentDomDocument_create_comment() 
create_cdata_sectionDomDocument_create_cdata_section() 
create_processing_instructionDomDocument_create_processing_instruction() 
create_attributeDomDocument_create_attribute() 
create_entity_referenceDomDocument_create_entity_reference() 
get_elements_by_tagnameDomDocument_get_elements_by_tagname() 
get_element_by_idDomDocument_get_element_by_id() 
dump_memDomDocument_dump_mem()Non standard DOM
dump_fileDomDocument_dump_file()Non standard DOM
html_dump_memDomDocument_html_dump_mem()Non standard DOM
xpath_initxpath_initNon standard DOM
xpath_new_contextxpath_new_contextNon standard DOM
xptr_new_contextxptr_new_contextNon standard DOM

Tableau 5. Classe DomElement (DomElement : DomNode)

Nom de la méthodeNom de la fonctionRemarques
tagnameDomElement_tagname() 
get_attributeDomElement_get_attribute() 
set_attributeDomElement_set_attribute() 
remove_attributeDomElement_remove_attribute() 
get_attribute_nodeDomElement_get_attribute_node() 
get_elements_by_tagnameDomElement_get_elements_by_tagname() 
has_attributeDomElement_has_attribute() 

Tableau 7. Classe DomAttribute (DomAttribute : DomNode)

Nom de la méthode Remarques
nameDomAttribute_name() 
valueDomAttribute_value() 
specifiedDomAttribute_specified() 

Tableau 8. Classe DomProcessingInstruction (DomProcessingInstruction : DomNode)

Nom de la méthodeNom de la fonctionRemarques
targetDomProcessingInstruction_target() 
dataDomProcessingInstruction_data() 

Tableau 9. Classe Parser

Nom de la méthodeNom de la fonctionRemarques
add_chunkParser_add_chunk() 
endParser_end() 

Tableau 10. Classe XPathContext

Nom de la méthodeNom de la fonctionRemarques
evalXPathContext_eval() 
eval_expressionXPathContext_eval_expression() 
register_nsXPathContext_register_ns() 

Tableau 11. Classe DomDocumentType (DomDocumentType : DomNode)

Nom de la méthodeNom de la fonctionRemarques
nameDomDocumentType_name() 
entitiesDomDocumentType_entities() 
notationsDomDocumentType_notations() 
public_idDomDocumentType_public_id() 
system_idDomDocumentType_system_id() 
internal_subsetDomDocumentType_internal_subset() 

Les classes DomDtd sont dérivées de DomNode. DomComment est dérivée de DomCData.

Exemples

De nombreux exemples de cette partie requièrent une chaîne XML. Au lieu de répéter la chaîne dans tous les exemples, elle sera mise dans un fichier, qui sera inclus dans tous les exemples. Ce fichier inclus sera utilisé dans les exemples suivants dans cette section. Alternativement, vous pouvez créer un document XML et le lire avec la fonction DomDocument_open_file().

Exemple 1. Fichier d'inclusion example.inc pour la chaîne XML d'exemple

<?php
$xmlstr
= "<?xml version='1.0' standalone='yes'?>
<!DOCTYPE chapter SYSTEM '/share/sgml/Norman_Walsh/db3xml10/db3xml10.dtd'
[ <!ENTITY sp \"spanish\">
]>
<!-- lsfj  -->
<chapter language='en'><title language='en'>Title</title>
<para language='ge'>
  &sp;
  <!-- comment -->
  <informaltable ID='findme' language='&sp;'>
   <tgroup cols='3'>
    <tbody>
     <row><entry>a1</entry><entry
morerows='1'>b1</entry><entry>c1</entry></row>
<row><entry>a2</entry><entry>c2</entry></row>
     <row><entry>a3</entry><entry>b3</entry><entry>c3</entry></row>
    </tbody>
   </tgroup>
  </informaltable>
</para>
</chapter>"
;
?>

Table des matières
DomAttribute->name --  Retourne le nom de l'attribut
DomAttribute->specified --  Vérifie si un attribut est spécifié
DomAttribute->value --  Retourne la valeur d'un attribut
DomDocument->add_root -- Ajoute un noeud
DomDocument->create_attribute --  Crée un nouvel attribut
DomDocument->create_cdata_section --  Crée un nouveau noeud CDATA
DomDocument->create_comment --  Crée un nouveau noeud de commentaire
DomDocument->create_element_ns --  Crée un nouvel élément avec un espace de noms associé
DomDocument->create_element --  Crée un nouveau noeud élément
DomDocument->create_entity_reference --  Crée un objet DomEntityReference
DomDocument->create_processing_instruction --  Crée un nouveau noeud de traitement d'insctructions (PI)
DomDocument->create_text_node --  Crée un nouveau noeud de texte
DomDocument->doctype --  Retourne le type de document
DomDocument->document_element --  Retourne le noeud racine d'un document DOM XML
DomDocument->dump_file --  Convertit un document DOM XML en fichier
DomDocument->dump_mem --  Convertit l'arbre XML interne en une chaîne de caractères
DomDocument->get_element_by_id --  Recherche un élément avec son identifiant
DomDocument->get_elements_by_tagname -- 
DomDocument->html_dump_mem --  Convertit l'arbre XML interne en une chaîne de caractères au format HTML
DomDocument->xinclude -- Remplace XIncludes dans un objet DomDocument
DomDocumentType->entities --  Retourne la liste des entitées
DomDocumentType->internal_subset --  Retourne le sous ensemble interne (internal subset)
DomDocumentType->name --  Retourne le nom du type de document
DomDocumentType->notations --  Retourne la liste des notations
DomDocumentType->public_id --  Retourne l'identifiant public du type de document
DomDocumentType->system_id --  Retourne l'identifiant système du type de document
DomElement->get_attribute_node --  Retourne la valeur d'un attribut
DomElement->get_attribute --  Retourne la valeur d'un attribut
DomElement->get_elements_by_tagname --  Lit les éléments par nom de balise
DomElement->has_attribute -- Vérifie si un attribut existe
DomElement->remove_attribute -- Supprime un attribut
DomElement->set_attribute --  Définie la valeur d'un attribut
DomElement->tagname --  Retourne le nom de l'élément courant
DomNode->add_namespace -- Ajoute une déclaration d'espace de nom à un noeud
DomNode->append_child --  Ajoute un nouveau fils à la fin des enfants
DomNode->append_sibling --  Ajoute un frère à un noeud
DomNode->attributes -- Retourne la liste des attributs
DomNode->child_nodes --  Retourne les fils d'un noeud
DomNode->clone_node --  Clone un noeud
DomNode->dump_node --  Convertit un noeud en chaîne
DomNode->first_child --  Retourne le premier fils du noeud
DomNode->get_content --  Retourne le contenu du noeud
DomNode->has_attributes --  Vérifie si un noeud a des attributs
DomNode->has_child_nodes --  Vérifie si un noeud a des fils
DomNode->insert_before --  Insère un nouveau noeud fils
DomNode->is_blank_node --  Vérifie si un noeud est blanc
DomNode->last_child --  Retourne le dernier fils du noeud
DomNode->next_sibling --  Retourne le noeud frère suivant
DomNode->node_name --  Retourne le nom du noeud
DomNode->node_type --  Retourne le type de noeud
DomNode->node_value --  Retourne la valeur d'un noeud
DomNode->owner_document --  Retourne le document auquel appartient ce noeud DOM XML
DomNode->parent_node --  Retourne le père d'un noeud DOM XML
DomNode->prefix --  Retourne le préfixe d'espace de nom d'un noeud
DomNode->previous_sibling --  Retourne le frère précédent d'un noeud
DomNode->remove_child --  Supprime un fils de la liste des noeuds fils
DomNode->replace_child --  Remplace un noeud fils
DomNode->replace_node --  Remplace un noeud DomXML
DomNode->set_content --  Modifie le contenu d'un noeud
DomNode->set_name --  Modifie le nom d'un noeud
DomNode->set_namespace -- Modifie l'espace de noms d'un noeud
DomNode->unlink_node --  Efface un noeud
DomProcessingInstruction->data --  Retourne les données du script
DomProcessingInstruction->target --  Retourne la cible du script
DomXsltStylesheet->process -- Applique une transformation XSLT à un objet domdocument
DomXsltStylesheet->result_dump_file --  Ecrit le résultat d'un transformation XSLT dans un fichier
DomXsltStylesheet->result_dump_mem --  Ecrit le résultat d'un transformation XSLT dans une chaîne
domxml_new_doc --  Crée un document XML vide
domxml_open_file -- Crée un objet DOM à partir d'un fichier XML
domxml_open_mem -- Crée un objet DOM pour un document XML
domxml_version --  Lit le numéro de version de la bibliothèque XML
domxml_xmltree --  Crée un arbre d'objets PHP à partir d'un document XML
domxml_xslt_stylesheet_doc --  Crée un objet domssltstylesheet à partir d'un objet domdocument
domxml_xslt_stylesheet_file --  Crée un objet domssltstylesheet à partir d'un document xsl dans un fichier
domxml_xslt_stylesheet --  Crée un objet domssltstylesheet à partir d'un document xml
xpath_eval_expression --  Calcule un chemin XPath à partir d'une chaîne
xpath_eval --  Calcule un chemin XPath à partir d'une chaîne
xpath_new_context --  Crée un nouveau contexte xpath
xptr_eval --  Calcul un chemin XPtr à partir d'une chaîne
xptr_new_context --  Crée un nouveau contexte XPath