XXX. DOM Functions

Introduzione

L'estensione DOM è la sostituzione dell'estensione DOM XML del PHP 4. Questo modulo continua a contenere diverse vecchie funzioni, ma non dovrebbereo essere più utilizzate. In particolar modo si dovrebbe evitare le funzioni che non sono orientate agli oggetti.

L'estensione permette di lavorare su un documento XML con le API DOM.

Installazione

Non è necessaria nessuna installazione per usare queste funzioni, esse fanno parte del core di PHP.

Classi predefinite

Le APi del modulo seguono lo standard DOM Level 2 il più fedelmente possibile. Di conseguenza la API sono completamente ad oggetti. E' consigliabile avere a portata di mano lo standard DOM quando si utilizza questo modulo.

Questo modulo definisce diverse classi, che sono illustrate nelle seguenti tabelle. Quelle con una corrispondente classe nello standard DOM sono chia,ate DOMxxx.

DOMAttr

Estende DOMNode. L'interfaccia DOMAttr rappresenta un attributo dell'oggetto DOMElement.

Costruttori

Metodi

Proprietà

Tabella 1.

NomeTipoSola letturaDescrizione
namestringsiNome dell'attributo
ownerElementDOMElementElemento che contiene l'attributo
schemaTypeInfoboolNon ancora impementato, ritorna sempre NULL
specifiedboolNon ancora impementato, ritorna sempre NULL
valuestringnoValore dell'attributo

DOMCharacterData

Espande DOMNode.

Metodi

Proprietà

Tabella 2.

NomeTipoSola letturaDescrizione
datastringnoContenuto del nodo
lengthintLunghezza del contenuto

DOMComment

Espande DOMCharacterData.

Costruttori

DOMDocument

Espande DOMNode.

Costruttori

Metodi

Proprietà

Tabella 3.

NomeTipoSola letturaDescrizione
actualEncodingstring 
configDOMConfiguration 
doctypeDOMDocumentType Dichiarazione del tipo documento associato al docuemnto.
documentElementDOMElement Attributo di convenienza per accedere direttamente al nodo figlio, che è l'elemento del documento.
documentURIstringno Luogo del documento oppure NULL se indefinito.
encodingstringno 
formatOutputboolno 
implementationDOMImplementation L'oggetto DOMImplementation che gestisce questo documento.
preserveWhiteSpaceboolnoNon rimuovere gli spazi ridondanti. Default TRUE.
recoverboolno 
resolveExternalsboolno Impostare a TRUE per caricare le entità esterne dalla dichiarazione doctype. Questo è utile per includere entità di caratteri nel documento XML.
standaloneboolno 
strictErrorCheckingboolnoGenera un DOMException in caso di errore. Default TRUE.
substituteEntitiesboolno 
validateOnParseboolnoCarica e valida nei confronti della DTD. Default FALSE.
versionstringno 
xmlEncodingstring L'attributo specifica, come parte della dichiarazione XML, la codifica del docuemnto. Vale NULL se non specificato oppure quando non è noto, come quando il documento è creato in memoria.
xmlStandaloneboolno Attributo che specifica, come parte della dichiarazione XML, se il documento è standalone. Vale FALSE se non specificato.
xmlVersionstringno Attributo che specifica, come parte della dichiarazione XML, il numero di versione del documento. Se non viè una dichiarazione e se il documento supporta le spcifiche "XML", vale "1.0".

DOMDocumentType

Espande DOMNode

Ciascun DOMDocument possiede un attributo doctype il cui valore può essere o NULL o un oggetto DOMDocumentType.

Proprietà

Tabella 4.

NomeTipoSola letturaDescrizione
publicIdstringIdentificatore pubblico del subset esterno.
systemIdstringIdentificatore di sistema del subset esterno. Può essere un URI assoluto o meno.
namestringIl nome della DTD; ad esempio il nome che segue immediatamente la parola chiave DOCTYPE.
entitiesDOMNamedNodeMap Un oggetto DOMNamedNodeMap che contiene le entità generali, sia interne che esterne, dichiarate nella DTD.
notationsDOMNamedNodeMap Un oggetto DOMNamedNodeMap contenente le notazioni dichiarate nella DTD.
internalSubsetstring SubSet interno definito come stringa, oppure null se non vi è nulla. Questo non contiene le parentesi quadre di delimitazione.

DOMElement

Espande DOMNode.

Costruttori

Metodi

Proprietà

Tabella 5.

NomeTipoSola letturaDescrizione
schemaTypeInfoboolNon ancora implementato, restituisce sempre NULL
tagNamestringNome dell'elemento

DOMEntity

Espande DOMNode

Questa interfaccia rappresenta una entità nota, sia interpretata che no, in un documento XML.

Proprietà

Tabella 6.

NomeTipoSola letturaDescrizione
publicIdstring Identificatore pubblico associato all'entità, se indicato, altrimenti NULL.
systemIdstring Identificatore di sistema associato all'entità, se indicato, altrimenti NULL. Può essere un URI assoluto.
notationNamestring Per le entità non interpretate, il nome della notazione dell'entità. Per le entità interpretate vale NULL.
actualEncodingstringno Attributo che indica la codifica utilizzata per questa entità al momento dell'intepretazione, in caso di interpretazione di entità esterne. Vale NULL se si tratta di un'entità interna, o se non è noto.
encodingstring Attributo che indica, come parte del testo di dichiarazione, la codifica dell'entità, in caso di entità esterna. Negli altri casi vale NULL.
versionstring Attributo che indica, come parte del testo di dichiarazione, il numero di versione di questa entità, in caso di entità esterna. Altrimenti NULL.

DOMEntityReference

Espande DOMNode.

Costruttori

DOMException

Le funzioni DOM, in casi particolari, generano delle eccezioni, ad esempio quando un'operazione non può essere eseguita per motivi logici.

Vedere anche Capitolo 20.

Proprietà

Tabella 7.

NomeTipoSola letturaDescrizione
codeintIntero indicante il tipo di errore generato

DOMImplementation

L'interfaccia DOMImplementation fornisce diversi metodi per eseguire operazioni che sono indipendenti da qualsiasi istanza del modello ad oggetti del documento.

Costruttori

Metodi

DOMNode

Metodi

Proprietà

Tabella 8.

NomeTipoSola letturaDescrizione
nodeNamestringRestituisce un nome più accurato per il tipo di nodo.
nodeValuestringnoValore di questo nodo, dipende dal tipo.
nodeTypeintTipo di nodo. Una delle costanti XML_xxx_NODE predefinite.
parentNodeDOMNodeNodo genitore di questo nodo.
childNodesDOMNodeList Un oggetto DOMNodeList che contiene tutti i nodi figli di questo nodo. Se non vi sono nodi figli, questa è un DOMNodeList vuoto.
firstChildDOMNode Il primo figlio di questo nodo. Se tale nodo non esiste, restituisce NULL.
lastChildDOMNode L'ultimo figlio di questo nodo. Se tale nodo non esiste, restituisce NULL.
previousSiblingDOMNode Il nodo immediatamente precedente a questo. Se tale nodo non esiste, restituisce NULL.
nextSiblingDOMNode Il nodo immediatamente seguente a questo. Se tale nodo non esiste, restituisce NULL.
attributesDOMNamedNodeMap Un oggetto DOMNamedNodeMap contenente gli attributi di questo nodo (se si tratta di un DOMElement) oppure NULL.
ownerDocumentDOMDocument L'oggetto DOMDocument associato a questo nodo.
namespaceURIstring L'URI dello spazio dei nomi di questo nodo, oppure NULL se non specificato.
prefixstringno Prefisso dello spazio dei nomi del nodo, oppure NULL se non specificato.
localNamestring Restituisce la parte locale del nome qualificato del nodo.
baseURIstring L'URI assoluto del nodo oppure NULL se l'implementazione non è in grado di ottenere l'URI assoluto.
textContentstringno Questo attributo restituisce il testo contenuto nel nodo e nei suoi discendenti.

DOMNodeList

Metodi

Proprietà

Tabella 9.

NomeTipoSola letturaDescrizione
lengthint Numero di nodi nella lista. Il range valido per l'indice varia tra 0 e length - 1 compresi.

DOMNotation

Espande DOMNode

Proprietà

Tabella 10.

NomeTipoSola letturaDescrizione
publicIdstring 
systemIdstring 

DOMProcessingInstruction

Espande DOMNode.

Costruttori

Proprietà

Tabella 11.

NomeTipoSola letturaDescrizione
targetstring 
datastringno 

DOMText

Espande DOMCharacterData.

Costruttori

Metodi

Proprietà

Tabella 12.

NomeTipoSola letturaDescrizione
wholeTextstring 

DOMXPath

Costruttori

Metodi

Proprietà

Tabella 13.

NomeTipoSola letturaDescrizione
documentDOMDocument  

Esempi

Many examples in this reference require an XML file. We will use book.xml that contains the following:

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

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

Tabella 14. Costanti XML

CostanteValoreDescrizione
XML_ELEMENT_NODE (integer) 1Il nodo è un DOMElement
XML_ATTRIBUTE_NODE (integer) 2Il nodo è un DOMAttr
XML_TEXT_NODE (integer) 3Il nodo è un DOMText
XML_CDATA_SECTION_NODE (integer) 4Il nodo è un oggetto DOMCharacterData
XML_ENTITY_REF_NODE (integer) 5Il nodo è un oggetto DOMEntityReference
XML_ENTITY_NODE (integer) 6Il nodo è un DOMEntity
XML_PI_NODE (integer) 7Il nodo è un DOMProcessingInstruction
XML_COMMENT_NODE (integer) 8Il nodo è un DOMComment
XML_DOCUMENT_NODE (integer) 9Il nodo è un DOMDocument
XML_DOCUMENT_TYPE_NODE (integer) 10Il nodo è un oggetto DOMDocumentType
XML_DOCUMENT_FRAG_NODE (integer) 11Il nodo è un oggetto DOMDocumentFragment
XML_NOTATION_NODE (integer) 12Il nodo è un oggetto 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 

Tabella 15. Costanti DOMException

CostanteValoreDescrizione
DOM_INDEX_SIZE_ERR (integer) 1 Se l'indice o la dimensione sono negativi, o maagiori del valore ammesso.
DOMSTRING_SIZE_ERR (integer) 2 Se il range di testo indicato non rientra nell'oggetto DOMString.
DOM_HIERARCHY_REQUEST_ERR (integer) 3Se il nodo è inserito in posti non attesi
DOM_WRONG_DOCUMENT_ERR (integer) 4 Se il nodo viene utilizzato in documenti differenti rispetto a quello che lo ha creato.
DOM_INVALID_CHARACTER_ERR (integer) 5 Carattere invalido o illegale.
DOM_NO_DATA_ALLOWED_ERR (integer) 6 Dati indicati per un nodo che non gestisce i dati.
DOM_NO_MODIFICATION_ALLOWED_ERR (integer) 7 Tentativo di modifica di un oggetto che non permette modifiche.
DOM_NOT_FOUND_ERR (integer) 8 Riferimento ad un nodo in un contesto in cui non esiste.
DOM_NOT_SUPPORTED_ERR (integer) 9 Tipo di oggetto oppure operazione non supportata dall'implementazione.
DOM_INUSE_ATTRIBUTE_ERR (integer) 10 Tentativo di aggiungere un attributo già in uso altrove.
DOM_INVALID_STATE_ERR (integer) 11 Utilizzo di un oggetto che non è più utilizzabile.
DOM_SYNTAX_ERR (integer) 12Stringa non valida o illegale.
DOM_INVALID_MODIFICATION_ERR (integer) 13Tentativo di modificare il tipo dell'oggetto sottostante.
DOM_NAMESPACE_ERR (integer) 14 Tentativo di creare o modficiare un oggetto in un modo che non è corretto rispetto allo spazio dei nomi.
DOM_INVALID_ACCESS_ERR (integer) 15Parametro od operazione non supportati dall'oggetto.
DOM_VALIDATION_ERR (integer) 16 Chiamata ad un metodo tipo insertBefore oppure removeChild che renda il nodo invalido ripetto ad una 'validazione parziale'; questa eccezione comporta la mancata esecuzione dell'operazione.
Sommario
DOMAttr->__construct() --  Crea un nuovo oggetto DOMAttr
DOMAttr->isId() --  Verifica se l'attributo è un ID definito
DOMCharacterData->appendData() --  Aggiunge una stringa alla fine del testo di un nodo
DOMCharacterData->deleteData() --  Rimuove un range di caratteri da un nodo
DOMCharacterData->insertData() --  Inserisce una stringa all'offset di 16 bit indicato
DOMCharacterData->replaceData() --  Sostituisce una stringa all'interno di un nodo DOMCharacterData
DOMCharacterData->substringData() --  Estrae un tange di dati da un nodo
DOMComment->__construct() --  Crea un nuovo oggetto DOMComment
DOMDocument->__construct() --  Crea un nuovo oggetto DOMDocument
DOMDocument->createAttribute() -- Crea un nuovo attributo
DOMDocument->createAttributeNS() --  Crea un nuovo nodo attributo con associato lo spazio dei nomi
DOMDocument->createCDATASection() -- Crea un nuovo nodo cdata
DOMDocument->createComment() -- Crea un nuovo nodo di commento
DOMDocument->createDocumentFragment() -- Crea un nuovo frammento di documento
DOMDocument->createElement() -- Crea un nuovo nodo elemento
DOMDocument->createElementNS() --  Crea un nuovo nodo elemento con associato lo spazio dei nomi
DOMDocument->createEntityReference() -- Crea un nuovo nodo riferimento ad entità
DOMDocument->createProcessingInstruction() -- Crea un nuovo nodo PI
DOMDocument->createTextNode() -- Crea un nuovo nodo di testo
DOMDocument->getElementById() -- Cerca un elemento con un certo id
DOMDocument->getElementsByTagName() -- Cerca tutti gli eleemnti per un dato nome di tag
DOMDocument->getElementsByTagNameNS() --  Ricerca tutti gli elementi per un dato nome tag nello spazio dei nomi indicato.
DOMDocument->importNode() -- Importa un nodo nel documento corrente
DOMDocument->load() --  Carica un documento XML da un file
DOMDocument->loadHTML() --  Carica una pagina HTML da una stringa
DOMDocument->loadHTMLFile() --  Carica un file HTML
DOMDocument->loadXML() --  Carica un documento XML da una stringa
DOMDocument->normalizeDocument() -- Normalizes the document
DOMDocument->registerNodeClass() -- Register extended class used to create base node type
DOMDocument->relaxNGValidate() --  Esegue una validazione relaxNG sul documento
DOMDocument->relaxNGValidateSource() --  Esegue una validazione relaxNG sul documento
DOMDocument->save() --  Scarica l'albero XML interno in un file
DOMDocument->saveHTML() --  Dumps the internal document into a string using HTML formatting
DOMDocument->saveHTMLFile() --  Dumps the internal document into a file using HTML formatting
DOMDocument->saveXML() --  Dumps the internal XML tree back into a string
DOMDocument->schemaValidate() --  Validates a document based on a schema
DOMDocument->schemaValidateSource() --  Validates a document based on a schema
DOMDocument->validate() --  Valida il documento in base alla sua DTD
DOMDocument->xinclude() --  Sostituisce gli XIncludes in un oggetto DOMDocument
DOMDocumentFragment->appendXML() -- Append raw XML data
DOMElement->__construct() --  Crea un nuovo oggetto DOMElement
DOMElement->getAttribute() -- Restituisce il valore di un attributo
DOMElement->getAttributeNode() -- Restituisce il nodo attributo
DOMElement->getAttributeNodeNS() --  Restituisce un nodo attributo
DOMElement->getAttributeNS() -- Restituisce il valore di un attributo
DOMElement->getElementsByTagName() -- Restituisce gli elementi in base al nome del tag
DOMElement->getElementsByTagNameNS() -- Restituisce gli elementi per spazio dei nomi e nome locale
DOMElement->hasAttribute() -- Verifica se l'attributo esiste
DOMElement->hasAttributeNS() --  Verifica se esiste l'attributo
DOMElement->removeAttribute() -- Rimuove l'attributo
DOMElement->removeAttributeNode() -- Rimuove gli attributi
DOMElement->removeAttributeNS() -- Rimuove gli attributi
DOMElement->setAttribute() -- Aggiunge un nuovo attributo
DOMElement->setAttributeNode() -- Aggiunge un nuovo nodo attributo all'elemento
DOMElement->setAttributeNodeNS() -- Aggiunge un nuovo nodo attributo all'elemento
DOMElement->setAttributeNS() -- Aggiunge un nuovo attributo
DOMElement->setIdAttribute() -- Declares the attribute specified by name to be of type ID
DOMElement->setIdAttributeNode() -- Declares the attribute specified by node to be of type ID
DOMElement->setIdAttributeNS() -- Declares the attribute specified by local name and namespace URI to be of type ID
DOMAttr->__construct() --  Crea un nuovo oggetto DOMEntityReference
DOMImplementation->__construct() --  Crea un nuovo oggetto DOMImplementation
DOMImplementation->createDocument() --  Crea un oggetto DOMDocument del tipo indicato con il suo elemento documento
DOMImplementation->createDocumentType() --  Crea un oggetto DOMDocumentType vuoto
DOMImplementation->hasFeature() --  Verifica se l'implementazione DOM ha una specifica caratteristica
DOMNamedNodeMap->getNamedItem() --  Recupera un nodo indicandone il nome
DOMNamedNodeMap->getNamedItemNS() --  Recupera un nodo indicando il nome locale e l'URI dello spazio dei nomi
DOMNamedNodeMap->item() -- Recupera un nodo tramite il suo indice
DOMNode->appendChild() --  Aggiunge un nuovo nodo figlio alla fine dei nodi figli
DOMNode->cloneNode() --  Clona un nodo
DOMNode->hasAttributes() --  Verifica se un nodo ha degli attributi
DOMNode->hasChildNodes() --  Verifica se un nodo ha nodi figli
DOMNode->insertBefore() --  Aggiunge un nuovo nodo figlio prima del riferimento
DOMNode->isDefaultNamespace() -- Checks if the specified namespaceURI is the default namespace or not
DOMNode->isSameNode() --  Indica se due nodi sono il medesimo nodo
DOMNode->isSupported() --  Verifica se una caratteristica è supportata dalla versione indicata
DOMNode->lookupNamespaceURI() --  Restituisce l'URI dello spazio dei nomi in base al prefisso
DOMNode->lookupPrefix() --  Resituisce il prefisso dello spazio dei nomi in base all'URI dello spazio dei nomi
DOMNode->normalize() --  Normalizza un nodo
DOMNode->removeChild() --  Rimuove un nodo figlio dalla lista dei nodi figli
DOMNode->replaceChild() --  Sostituisce un nodo figlio
DOMNodelist->item() --  Recupera il nodo indicato dall'indice
DOMProcessingInstruction->__construct() --  Crea un nuovo oggetto DOMProcessingInstruction
DOMText->__construct() --  Crea un nuovo oggetto DOMText
DOMText->isWhitespaceInElementContent() --  Indica se questo nodo di testo contiene spazi
DOMText->splitText() --  Spezza il nodo in due all'offset specificato
DOMXPath->__construct() --  Crea un nuovo oggetto DOMXPath
DOMXPath->evaluate() --  Valuta l'espressione XPath data e restituisce un risultato se possibile
DOMXPath->query() --  Valuta l'espressione XPath
DOMXPath->registerNamespace() --  Registra lo spazio dei nomi nell'oggetto DOMXpath
dom_import_simplexml --  Ottiene un'oggetto DOMElement da un'oggetto SimpleXMLElement