XXV. Funciones DOM XML

Introducción

Aviso

Esta extensión es EXPERIMENTAL. Esto significa que el comportamiento de esta extensión, los nombre de sus funciones y en definitiva TODO lo documentado sobre esta extensión, puede cambiar en una futura versión de PHP SIN AVISO. La advertencia queda hecha, y utilizar esta extensión queda bajo su propia responsabilidad.

La extensión DOM XML ha sido re-estructurada en PHP 4.3.0 para mayor compatibilidad con el estándar DOM. La extensión aun contiene varias funciones viejas, pero ellas ya no deben ser usadas. En particular, las funciones que no son orientadas a objetos deben evitarse.

La extensión le permite operar sobre un documento XML con la API DOM. También ofrece una función domxml_xmltree() para convertir el documento XML completo en un árbol de objetos PHP. Actualmente, este árbol debe ser considerado como de sólo-escritura - es posible modificarlo, pero tal cosa no tendría sentido ya que DomDocument_dump_mem() no puede aplicarse sobre él. Por lo tanto, si desea leer un archivo XML y escribir una versión modificada, use DomDocument_create_element(), DomDocument_create_text_node(), set_attribute(), etc. y finalmente la función DomDocument_dump_mem().

Requirimientos

Esta extensión hace uso de la biblioteca GNOME XML. Descargue e instale esta biblioteca. Necesita por lo menos libxml-2.4.14. Para usar las características DOM XSLT, puede usar la biblioteca libxslt y las adiciones EXSLT de http://www.exslt.org/. Descargue e instale estas bibliotecas si planea usar las características XSLT (y las mejoras). Necesita por lo menos libxslt-1.0.18.

Instalación

Esta extensión se encuentra disponible únicamente si PHP fue configurado con --with-dom[=DIR]. Agregue --with-dom-xslt[=DIR] para incluir soporte para DOM XSLT. DIR es el directorio de instalación de libxslt. Agregue --with-dom-exslt[=DIR] para incluir soporte para DOM EXSLT, en donde DIR es el directorio de instalación de libexslt.

Nota para Usuarios de Win32: Para habilitar este módulo en un entorno Windows, debe copiar un archivo adicional desde el directorio de archivos DLL del paquete binario de PHP/Win32 a la carpeta SYSTEM32 en su máquina Windows (Ej: C:\WINNT\SYSTEM32 o C:\WINDOWS\SYSTEM32). Para PHP <= 4.2.0, copie libxml2.dll, para PHP >= 4.3.0 copie iconv.dll desde el directorio de archivos DLL a su directorio SYSTEM32.

Funciones obsoletas

Existen varias funciones que no tienen lugar en el estándar DOM y no deberían seguir siendo usadas. Estas funciones son listadas en la siguiente tabla. La función DomNode_append_child() ha cambiado su comportamiento. Ahora agrega un hijo y no un hermano. Si esto afecta su aplicación, use la función DomNode_append_sibling(), la cual no hace parte del conjunto DOM.

Tabla 1. Funciones obsoletas y sus reemplazos

Función antiguaFunción nueva
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() seguido por DomNode_append_child()
DomDocument_dtdDomDocument_doctype()
DomDocument_rootDomDocument_document_element()
DomDocument_childrenDomNode_child_nodes()
DomDocument_imported_nodeNo hay reemplazo.
DomNode_add_childCrear un nuevo nodo, p.ej. con DomDocument_create_element() y agregarlo con DomNode_append_child().
DomNode_childrenDomNode_child_nodes()
DomNode_parentDomNode_parent_node()
DomNode_new_childCrear un nuevo nodo, p.ej. con DomDocument_create_element() y agregarlo con DomNode_append_child().
DomNode_set_contentCrear un nuevo nodo, p.ej. con DomDocument_create_text_node() y agregarlo con DomNode_append_child().
DomNode_get_contentEl contenido es solo un nodo de texto y puede consultarse con DomNode_child_nodes().
DomNode_set_contentEl contenido es solo un nodo de texto y puede ser agregado con DomNode_append_child().

Constantes predefinidas

Estas constantes están definidas por esta extensión y estarán disponibles solamente cuando la extensión ha sido o bien compilada dentro de PHP o grabada dinámicamente en tiempo de ejecución.

Tabla 2. Constantes XML

ConstanteValorDescripción
XML_ELEMENT_NODE (integer) 1El nodo es un elemento
XML_ATTRIBUTE_NODE (integer) 2El nodo es un atributo
XML_TEXT_NODE (integer) 3El nodo es un segmento de texto
XML_CDATA_SECTION_NODE (integer) 4 
XML_ENTITY_REF_NODE (integer) 5 
XML_ENTITY_NODE (integer) 6El nodo es una entidad como &nbsp;
XML_PI_NODE (integer) 7El nodo es una instrucción de procesamiento
XML_COMMENT_NODE (integer) 8El nodo es un comentario
XML_DOCUMENT_NODE (integer) 9El nodo es un documento
XML_DOCUMENT_TYPE_NODE (integer) 10 
XML_DOCUMENT_FRAG_NODE (integer) 11 
XML_NOTATION_NODE (integer) 12 
XML_GLOBAL_NAMESPACE (integer) 1 
XML_LOCAL_NAMESPACE (integer) 2 
XML_HTML_DOCUMENT_NODE (integer)   
XML_DTD_NODE (integer)   
XML_ELEMENT_DECL_NODE (integer)   
XML_ATTRIBUTE_DECL_NODE (integer)   
XML_ENTITY_DECL_NODE (integer)   
XML_NAMESPACE_DECL_NODE (integer)   
XML_ATTRIBUTE_CDATA (integer)   
XML_ATTRIBUTE_ID (integer)   
XML_ATTRIBUTE_IDREF (integer)   
XML_ATTRIBUTE_IDREFS (integer)   
XML_ATTRIBUTE_ENTITY (integer)   
XML_ATTRIBUTE_NMTOKEN (integer)   
XML_ATTRIBUTE_NMTOKENS (integer)   
XML_ATTRIBUTE_ENUMERATION (integer)   
XML_ATTRIBUTE_NOTATION (integer)   
XPATH_UNDEFINED (integer)   
XPATH_NODESET (integer)   
XPATH_BOOLEAN (integer)   
XPATH_NUMBER (integer)   
XPATH_STRING (integer)   
XPATH_POINT (integer)   
XPATH_RANGE (integer)   
XPATH_LOCATIONSET (integer)   
XPATH_USERS (integer)   
XPATH_NUMBER (integer)   

Clases

La API del módulo sigue el estándar DOM de Nivel 2 tan fielmente como es posible. Por consiguiente, la API es completamente orientada a objetos. Es una buena idea tener el estándar DOM a la mano cuando se usa este módulo. Aunque la API es orientada a objetos, existen varias funciones que pueden ser llamadas en una forma no orientada a objetos, pasando el objeto sobre el que debe operarse como primer argumento. Estas funciones existen principalmente para conservar la compatibilidad con versiones anteriores de esta extensión, y no deberían ser usadas cuando se creen nuevos scripts.

Esta API difiere de la API DOM oficial en dos formas. Primero, todos los atributos de clase son implementados como funciones con el mismo nombre. En segundo lugar, los nombres de funciones siguen la convención de nombres de PHP. esto quiere decir que una función DOM llamada lastChild() será escrita como last_child().

Este módulo define un número de clases, que son listados - incluyendo sus métodos - en las siguientes tablas. Las clases con un equivalente en el estándar DOM son llamadas DOMxxx.

Tabla 3. Lista de clases

Nombre de claseClases padre
DomAttributeDomNode
DomCDataDomNode
DomCommentDomCData : DomNode
DomDocumentDomNode
DomDocumentTypeDomNode
DomElementDomNode
DomEntityDomNode
DomEntityReferenceDomNode
DomProcessingInstructionDomNode
DomTextDomCData : DomNode
ParserPor el momento aun se llama DomParser
XPathContext 

Tabla 4. Clase DomDocument (DomDocument : DomNode)

Nombre de métodoNombre de funciónAnotación
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()no hace parte del estándar DOM
dump_fileDomDocument_dump_file()no hace parte del estándar DOM
html_dump_memDomDocument_html_dump_mem()no hace parte del estándar DOM
xpath_initxpath_initno hace parte del estándar DOM
xpath_new_contextxpath_new_contextno hace parte del estándar DOM
xptr_new_contextxptr_new_contextno hace parte del estándar DOM

Tabla 5. Clase DomElement (DomElement : DomNode)

Nombre de métodoNombre de funciónAnotación
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() 

Tabla 6. DomNode class

Nombre de métodoAnotación
DomNode_node_name() 
DomNode_node_value() 
DomNode_node_type() 
DomNode_last_child() 
DomNode_first_child() 
DomNode_child_nodes() 
DomNode_previous_sibling() 
DomNode_next_sibling() 
DomNode_parent_node() 
DomNode_owner_document() 
DomNode_insert_before() 
DomNode_append_child() 
DomNode_append_sibling()No se encuentra en el estándar DOM. Esta función emula el comportamiento antiguo de DomNode_append_child().
DomNode_remove_child() 
DomNode_has_child_nodes() 
DomNode_has_attributes() 
DomNode_clone_node() 
DomNode_attributes() 
DomNode_unlink_node()No se encuentra en el estándar DOM
DomNode_replace_node()No se encuentra en el estándar DOM
DomNode_set_content()No se encuentra en el estándar DOM, obsoleta
DomNode_get_content()No se encuentra en el estándar DOM, obsoleta
DomNode_dump_node()No se encuentra en el estándar DOM
DomNode_is_blank_node()No se encuentra en el estándar DOM

Tabla 7. Clase DomAttribute (DomAttribute : DomNode)

Nombre de método Anotación
nameDomAttribute_name() 
valueDomAttribute_value() 
specifiedDomAttribute_specified() 

Tabla 8. Clase DomProcessingInstruction (DomProcessingInstruction : DomNode)

Nombre de métodoNombre de funciónAnotación
targetDomProcessingInstruction_target() 
dataDomProcessingInstruction_data() 

Tabla 9. Clase Parser

Nombre de métodoNombre de funciónAnotación
add_chunkParser_add_chunk() 
endParser_end() 

Tabla 10. Clase XPathContext

Nombre de métodoNombre de funciónAnotación
evalXPathContext_eval() 
eval_expressionXPathContext_eval_expression() 
register_nsXPathContext_register_ns() 

Tabla 11. Clase DomDocumentType (DomDocumentType : DomNode)

Nombre de métodoNombre de funciónAnotación
nameDomDocumentType_name() 
entitiesDomDocumentType_entities() 
notationsDomDocumentType_notations() 
public_idDomDocumentType_public_id() 
system_idDomDocumentType_system_id() 
internal_subsetDomDocumentType_internal_subset() 

La clase DomDtd es derivada de DomNode. DomComment es derivada de DomCData.

Ejemplos

Varios ejemplos en esta referencia requieren una cadena XML. En lugar de repetir esta cadena en cada ejemplo, será puesta en un archivo el cual será incluido en cada ejemplo. Este archivo de inclusión es mostrado en la siguiente sección de ejemplo. Alternativamente, es posible crear un documento XML y leerlo con DomDocument_open_file().

Ejemplo 1. Archivo de inclusión ejemplo.inc con una cadena XML

<?php
$cadena_xml
= "<?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'>
  &amp;sp;
  <!-- comment -->
  <informaltable ID='findme' language='&amp;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>"
;
?>

Tabla de contenidos
DomAttribute->name --  Devuelve el nombre de un atributo
DomAttribute->specified --  Revisa si el atributo está especificado
DomAttribute->value --  Devuelve el valor del atributo
DomDocument->add_root --  Agrega un nodo raíz [obsoleto]
DomDocument->create_attribute -- Crear un nuevo atributo
DomDocument->create_cdata_section -- Crear un nuevo nodo cdata
DomDocument->create_comment -- Crea un nuevo nodo de comentario
DomDocument->create_element_ns --  Crea un nuevo nodo tipo elemento con un espacio de nombres asociado
DomDocument->create_element -- Crear un nuevo nodo de tipo elemento
DomDocument->create_entity_reference -- 
DomDocument->create_processing_instruction -- Crea un nuevo nodo PI
DomDocument->create_text_node -- Crear un nuevo nodo de texto
DomDocument->doctype --  Devuelve el tipo de documento
DomDocument->document_element --  Devuelve el nodo del elemento raíz
DomDocument->dump_file --  Vuelca el árbol XML interno de vuelta a un archivo
DomDocument->dump_mem --  Vuelca el árbol XML interno de vuelta a una cadena
DomDocument->get_element_by_id --  Busca un elemento con cierto id
DomDocument->get_elements_by_tagname -- 
DomDocument->html_dump_mem --  Vuelca el árbol XML interno de vuelta a una cadena como HTML
DomDocument->xinclude --  Reemplaza sentencias XInclude en un Objeto DomDocument.
DomDocumentType->entities --  Devuelve una lista de entidades
DomDocumentType->internal_subset --  Devuelve el sub-conjunto interno
DomDocumentType->name --  Devuelve el nombre del tipo de documento
DomDocumentType->notations --  Devuelve una lista de notaciones
DomDocumentType->public_id --  Devuelve el id público del tipo de documento
DomDocumentType->system_id --  Devuelve el id de sistema del tipo de documento
DomElement->get_attribute_node --  Devuelve el valor del atributo
DomElement->get_attribute --  Devuelve el valor del atributo
DomElement->get_elements_by_tagname --  Obtiene elementos por el nombre de etiqueta
DomElement->has_attribute --  Verifica si un atributo existe
DomElement->remove_attribute --  Elimina un atributo
DomElement->set_attribute --  Agrega un nuevo atributo
DomElement->tagname --  Devuelve el nombre del elemento
DomNode->add_namespace --  Agrega una declaración de espacio de nombres a un nodo.
DomNode->append_child --  Agrega un nuevo hijo al final del grupo de hijos
DomNode->append_sibling --  Agrega un nuevo hermano a un nodo
DomNode->attributes --  Devuelve la lista de atributos
DomNode->child_nodes --  Devuelve los hijos del nodo
DomNode->clone_node --  Clona un nodo
DomNode->dump_node --  Vuelca un nodo único
DomNode->first_child --  Devuelve el primer hijo del nodo
DomNode->get_content --  Obtiene el contenido del nodo
DomNode->has_attributes --  Verifica si un nodo tiene atributos
DomNode->has_child_nodes --  Verifica si el nodo tiene hijos
DomNode->insert_before --  Inserta un nodo nuevo como hijo
DomNode->is_blank_node --  Verifica si el nodo está en blanco
DomNode->last_child --  Devuelve el último hijo del nodo
DomNode->next_sibling --  Devuelve el siguiente hermano del nodo
DomNode->node_name --  Devuelve el nombre del nodo
DomNode->node_type --  Devuelve el tipo de nodo
DomNode->node_value --  Devuelve el valor de un nodo
DomNode->owner_document --  Devuelve el documento al que este nodo pertenece
DomNode->parent_node --  Devuelve el padre del nodo
DomNode->prefix --  Devuelve el prefijo de espacio de nombres del nodo
DomNode->previous_sibling --  Devuelve el hermano anterior del nodo
DomNode->remove_child --  Elimina un hijo de una lista de hijos
DomNode->replace_child --  Reemplaza un hijo
DomNode->replace_node --  Reemplaza el nodo
DomNode->set_content --  Define el contenido del nodo
DomNode->set_name --  Define el nombre del nodo
DomNode->set_namespace --  Define el espacio de nombres de un nodo.
DomNode->unlink_node --  Elimina el nodo
DomProcessingInstruction->data --  Devuelve los datos de un nodo pi
DomProcessingInstruction->target --  Devuelve el destino de un nodo pi
DomXsltStylesheet->process --  Aplica la Transformación XSLT sobre un objeto DomDocument.
DomXsltStylesheet->result_dump_file --  Vuelca el resultado de una Transformación XSLT a un archivo
DomXsltStylesheet->result_dump_mem --  Vuelca el resultado de una Transformación XSLT de vuelta a una cadena
domxml_new_doc --  Crea un nuevo documento XML vacío
domxml_open_file -- Crea un objeto DOM a partir de un archivo XML
domxml_open_mem -- Crea un objeto DOM desde un documento XML
domxml_version --  Obtener la versión de la biblioteca XML
domxml_xmltree --  Crea un árbol de objetos PHP a partir de un documento XML
domxml_xslt_stylesheet_doc --  Crea un Objeto DomXsltStylesheet a partir de un Objeto DomDocument.
domxml_xslt_stylesheet_file --  Crea un Objeto DomXsltStylesheet a partir de un documento XSL en un archivo.
domxml_xslt_stylesheet --  Crea un Objeto DomXsltStylesheet desde un documento XML en una cadena.
xpath_eval_expression --  Evalúa la Ruta de Ubicación XPath en la cadena entregada
xpath_eval --  Evalúa la Ruta de Ubicación XPatch en la cadena dada
xpath_new_context --  Crea un nuevo contexto xpath
xptr_eval --  Evalúa la Ruta de Ubicación XPtr en la cadena dada
xptr_new_context --  Crea un nuevo Contexto XPath