Manuale PHP
Indietro |  | Avanti

# 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

- DOMAttr->__construct() - costruisce un nuovo oggetto DOMAttr

### Metodi

- DOMAttr->isId() - Verifica se l'attributo è un ID definito

### Proprietà

Tabella 1.

Nome | Tipo | Sola lettura | Descrizione
--- | --- | --- | ---
name | string | si | Nome dell'attributo
ownerElement | DOMElement | sì | Elemento che contiene l'attributo
schemaTypeInfo | bool | sì | Non ancora impementato, ritorna sempre `NULL`
specified | bool | sì | Non ancora impementato, ritorna sempre `NULL`
value | string | no | Valore dell'attributo

## DOMCharacterData

Espande DOMNode.

### Metodi

- DOMCharacterData->appendData() - Aggiunge un testo alla fine dei dati di un nodo

- DOMCharacterData->deleteData() - Rimuove un range di caratteri dal nodo

- DOMCharacterData->insertData() - Inserisce una stringa alla posizione indicata

- DOMCharacterData->replaceData() - Sostituisce una posizione di testo nel nodo DOMCharacterData

- DOMCharacterData->substringData() - Estrai una porzione di dati dal nodo

### Proprietà

Tabella 2.

Nome | Tipo | Sola lettura | Descrizione
--- | --- | --- | ---
data | string | no | Contenuto del nodo
length | int | sì | Lunghezza del contenuto

## DOMComment

Espande DOMCharacterData.

### Costruttori

- DOMComment->__construct() - costruisce un nuovo oggetto DOMComment

## DOMDocument

Espande DOMNode.

### Costruttori

- DOMDocument->__construct() - costruisce un nuovo oggetto DOMDocument

### Metodi

- DOMDocument->createAttribute() - Crea un nuovo attributo

- DOMDocument->createAttributeNS() - Crea un nuovo nodo attributo con associato uno spazio dei nomi

- DOMDocument->createCDATASection() - Crea un nuovo nodo cdata

- DOMDocument->createComment() - Crea un nuovo nodo commento

- DOMDocument->createDocumentFragment() - Crea un nuovo nodo frammento

- DOMDocument->createElement() - Crea un nuovo nodo elemento

- DOMDocument->createElementNS() - Crea un nuovo nodo elemento con associato uno spazio dei nomi

- DOMDocument->createEntityReference() - Crea un nuovo nodo entità

- DOMDocument->createProcessingInstruction() - CRea un nuovo nodo PI

- DOMDocument->createTextNode() - Crea un nuovo nodo testo

- DOMDocument->getElementById() - Cerca un elemento con un certo ID

- DOMDocument->getElementsByTagName() - Cerca tutti gli elementi per un dato tag

- DOMDocument->getElementsByTagNameNS() - Cerca tutti gli elementi per un dato tag in un specifico spazio dei nomi

- DOMDocument->importNode() - Importa il nodo nel documento corrente

- DOMDocument->load() - Carica un file XML

- DOMDocument->loadHTML() - Carica un documento HTML da una stringa

- DOMDocument->loadHTMLFile() - Carica un file HTML

- DOMDocument->loadXML() - Carica un documento XML da una stringa

- DOMDocument->normalize() - Normalizza il documento

- DOMDocument->relaxNGValidate() - Esegue una validazione relaxNG sul documento

- DOMDocument->relaxNGValidateSource() - Esegue una validazione relaxNG sul documento

- DOMDocument->save() - Scrive l'albero XML in un file

- DOMDocument->saveHTML() - Scarica il docuemnto interno in una stringa formattato in HTML

- DOMDocument->saveHTMLFile() - Scarica il docuemnto interno in un file formattato in HTML

- DOMDocument->saveXML() - Scrive l'albero XML in un file in una stringa

- DOMDocument->schemaValidate() - Valida il documento in base ad uno schema

- DOMDocument->schemaValidateSource() - Valida il documento in base ad uno schema

- DOMDocument->validate() - Valida il documento in base ad al suo DTD

- DOMDocument->xinclude() - Sostituisce gli XIncludes in un oggetto DOMDocument

### Proprietà

Tabella 3.

Nome | Tipo | Sola lettura | Descrizione
--- | --- | --- | ---
actualEncoding | string | sì |
config | DOMConfiguration | sì |
doctype | DOMDocumentType | sì | Dichiarazione del tipo documento associato al docuemnto.
documentElement | DOMElement | sì | Attributo di convenienza per accedere direttamente al nodo figlio, che è l'elemento del documento.
documentURI | string | no | Luogo del documento oppure `NULL` se indefinito.
encoding | string | no |
formatOutput | bool | no |
implementation | DOMImplementation | sì | L'oggetto DOMImplementation che gestisce questo documento.
preserveWhiteSpace | bool | no | Non rimuovere gli spazi ridondanti. Default `TRUE`.
recover | bool | no |
resolveExternals | bool | no | Impostare a `TRUE` per caricare le entità esterne dalla dichiarazione doctype. Questo è utile per includere entità di caratteri nel documento XML.
standalone | bool | no |
strictErrorChecking | bool | no | Genera un DOMException in caso di errore. Default `TRUE`.
substituteEntities | bool | no |
validateOnParse | bool | no | Carica e valida nei confronti della DTD. Default `FALSE`.
version | string | no |
xmlEncoding | string | sì | 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.
xmlStandalone | bool | no | Attributo che specifica, come parte della dichiarazione XML, se il documento è standalone. Vale `FALSE` se non specificato.
xmlVersion | string | no | 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.

Nome | Tipo | Sola lettura | Descrizione
--- | --- | --- | ---
publicId | string | sì | Identificatore pubblico del subset esterno.
systemId | string | sì | Identificatore di sistema del subset esterno. Può essere un URI assoluto o meno.
name | string | sì | Il nome della DTD; ad esempio il nome che segue immediatamente la parola chiave DOCTYPE.
entities | DOMNamedNodeMap | sì | Un oggetto DOMNamedNodeMap che contiene le entità generali, sia interne che esterne, dichiarate nella DTD.
notations | DOMNamedNodeMap | sì | Un oggetto DOMNamedNodeMap contenente le notazioni dichiarate nella DTD.
internalSubset | string | sì | SubSet interno definito come stringa, oppure null se non vi è nulla. Questo non contiene le parentesi quadre di delimitazione.

## DOMElement

Espande DOMNode.

### Costruttori

- DOMElement->__construct() - costruisce un nuovo oggetto DOMElement

### Metodi

- DOMElement->getAttribute() - Restituisce il valore di un attributo

- DOMElement->getAttributeNode() - Restituisce il nodo attributo

- DOMElement->getAttributeNodeNS() - Restituisce il nodo attributo

- DOMElement->getAttributeNS() - Restituisce il valore di un attributo

- DOMElement->getElementsByTagName() - Restituisce gli elementi in base al nome tag

- DOMElement->getElementsByTagNameNS() - Restituisce gli elementi in base all UTRI dello spazio dei nomi ed il nome locale

- DOMElement->hasAttribute() - Verifica se l'attributo esiste

- DOMElement->hasAttributeNS() - Verifica se l'attributo esiste

- DOMElement->removeAttribute() - Rimuove l'attributo

- DOMElement->removeAttributeNode() - Rimuove l'attributo

- DOMElement->removeAttributeNS() - Rimuove l'attributo

- 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

### Proprietà

Tabella 5.

Nome | Tipo | Sola lettura | Descrizione
--- | --- | --- | ---
schemaTypeInfo | bool | sì | Non ancora implementato, restituisce sempre `NULL`
tagName | string | sì | Nome dell'elemento

## DOMEntity

Espande DOMNode

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

### Proprietà

Tabella 6.

Nome | Tipo | Sola lettura | Descrizione
--- | --- | --- | ---
publicId | string | sì | Identificatore pubblico associato all'entità, se indicato, altrimenti `NULL`.
systemId | string | sì | Identificatore di sistema associato all'entità, se indicato, altrimenti `NULL`. Può essere un URI assoluto.
notationName | string | sì | Per le entità non interpretate, il nome della notazione dell'entità. Per le entità interpretate vale `NULL`.
actualEncoding | string | no | 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.
encoding | string | sì | Attributo che indica, come parte del testo di dichiarazione, la codifica dell'entità, in caso di entità esterna. Negli altri casi vale `NULL`.
version | string | sì | 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

- DOMAttr->__construct() - costruisce un nuovo oggetto DOMEntityReference

## 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.

Nome | Tipo | Sola lettura | Descrizione
--- | --- | --- | ---
code | int | sì | Intero 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

- DOMImplementation->__construct() - costruisce un nuovo oggetto DOMImplementation

### Metodi

- DOMImplementation->createDocument() - Crea un nuovo oggetto DOM Document del tipo specificato con il suo elemento documento

- DOMImplementation->createDocumentType() - Crea un oggetto DOMDocumentType vuoto

- DOMImplementation->hasFeature() - Verifica se l'implementazione DOM supporta specifiche caratteristiche

## DOMNode

### Metodi

- DOMNode->appendChild() - Aggiunge un nuovo nodo figlio alla fine dei nodi figli

- DOMNode->cloneNode() - Clona un nodo

- DOMNode->hasAttributes() - Verifica se il nodo ha attributi

- DOMNode->hasChildNodes() - Verifica se il nodo ha figli

- DOMNode->insertBefore() - Aggiunge un nuovo figlio prima del nodo indicato

- DOMNode->isSameNode() - Indica se due nodi sono lo stesso nodo

- DOMNode->isSupported() - Verifica se la caratteristica chiesta è supportata dalla versione

- DOMNode->lookupNamespaceURI() - Restituisce l'URI dello spazio dei nomi del nodo in base al suo prefisso

- DOMNode->lookupPrefix() - Restituisce il prefisso dello spazio dei nomi del nodo in base all'URI dello spazio dei nomi

- DOMNode->normalize() - Normalizza il nodo

- DOMNode->removeChild() - Rimuove un nodo figlio dall'elenco dei nodi figli

- DOMNode->replaceChild() - Sostituisce un nodo figlio

### Proprietà

Tabella 8.

Nome | Tipo | Sola lettura | Descrizione
--- | --- | --- | ---
nodeName | string | sì | Restituisce un nome più accurato per il tipo di nodo.
nodeValue | string | no | Valore di questo nodo, dipende dal tipo.
nodeType | int | sì | Tipo di nodo. Una delle costanti XML_xxx_NODE predefinite.
parentNode | DOMNode | sì | Nodo genitore di questo nodo.
childNodes | DOMNodeList | sì | Un oggetto DOMNodeList che contiene tutti i nodi figli di questo nodo. Se non vi sono nodi figli, questa è un DOMNodeList vuoto.
firstChild | DOMNode | sì | Il primo figlio di questo nodo. Se tale nodo non esiste, restituisce `NULL`.
lastChild | DOMNode | sì | L'ultimo figlio di questo nodo. Se tale nodo non esiste, restituisce `NULL`.
previousSibling | DOMNode | sì | Il nodo immediatamente precedente a questo. Se tale nodo non esiste, restituisce `NULL`.
nextSibling | DOMNode | sì | Il nodo immediatamente seguente a questo. Se tale nodo non esiste, restituisce `NULL`.
attributes | DOMNamedNodeMap | sì | Un oggetto DOMNamedNodeMap contenente gli attributi di questo nodo (se si tratta di un DOMElement) oppure `NULL`.
ownerDocument | DOMDocument | sì | L'oggetto DOMDocument associato a questo nodo.
namespaceURI | string | sì | L'URI dello spazio dei nomi di questo nodo, oppure `NULL` se non specificato.
prefix | string | no | Prefisso dello spazio dei nomi del nodo, oppure `NULL` se non specificato.
localName | string | sì | Restituisce la parte locale del nome qualificato del nodo.
baseURI | string | sì | L'URI assoluto del nodo oppure `NULL` se l'implementazione non è in grado di ottenere l'URI assoluto.
textContent | string | no | Questo attributo restituisce il testo contenuto nel nodo e nei suoi discendenti.

## DOMNodeList

### Metodi

- DOMNodelist->item() - Recupera il nodo indicato dall'indice

### Proprietà

Tabella 9.

Nome | Tipo | Sola lettura | Descrizione
--- | --- | --- | ---
length | int | sì | Numero di nodi nella lista. Il range valido per l'indice varia tra 0 e length - 1 compresi.

## DOMNotation

Espande DOMNode

### Proprietà

Tabella 10.

Nome | Tipo | Sola lettura | Descrizione
--- | --- | --- | ---
publicId | string | sì |
systemId | string | sì |

## DOMProcessingInstruction

Espande DOMNode.

### Costruttori

- DOMProcessingInstruction->__construct() - costruisce un nuovo oggetto DOMProcessingInstruction

### Proprietà

Tabella 11.

Nome | Tipo | Sola lettura | Descrizione
--- | --- | --- | ---
target | string | sì |
data | string | no |

## DOMText

Espande DOMCharacterData.

### Costruttori

- DOMText->__construct() - costruisce un nuovo oggetto DOMText

### Metodi

- DOMText->isWhitespaceInElementContent() - Indica se questo nodo contiene degli spazi

- DOMText->splitText() - Divide il nodo in due alla posizione indicata

### Proprietà

Tabella 12.

Nome | Tipo | Sola lettura | Descrizione
--- | --- | --- | ---
wholeText | string | sì |

## DOMXPath

### Costruttori

- DOMXPath->__construct() - construct a new DOMXPath object

### Metodi

- DOMXPath->registerNamespace() - Registers the namespace with the DOMXpath object

- DOMXPath->evaluate() - Evaluates the given XPath expression and returns a typed result if possible

- DOMXPath->query() - Evaluates the given XPath expression

### Proprietà

Tabella 13.

Nome | Tipo | Sola lettura | Descrizione
--- | --- | --- | ---
document | DOMDocument |  |

# 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

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

Costante | Valore | Descrizione
--- | --- | ---
`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) | 3 | Se 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) | 12 | Stringa non valida o illegale.
`DOM_INVALID_MODIFICATION_ERR` (integer) | 13 | Tentativo 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) | 15 | Parametro 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.

Indietro | Partenza | Avanti
scandir | Risali | DOMAttr->__construct()