DOMDocument::registerNodeClass

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DOMDocument::registerNodeClass — Enregistre la classe étendue utilisée pour créer un type de base de nœud

Description

public DOMDocument::registerNodeClass(string $baseClass, ?string $extendedClass): true

Cette méthode permet d'enregistrer sa propre classe étendue DOM à utiliser ensuite dans l'extension DOM de PHP.

Cette méthode ne fait pas partie du standard DOM.

Attention

Le constructeur des objets des classes de nœuds enregistrées n'est pas appelé.

Liste de paramètres

baseClass: La classe DOM que l'on veut étendre. Il est possible de trouver une liste de ces classes dans l'introduction du chapitre.
extendedClass: Le nom de la classe étendue. Si la valeur null est fournie, toutes les classes enregistrées précédemment étendant baseClass seront supprimées.

Valeurs de retour

Retourne toujours true.

Historique

Version	Description
8.4.0	DOMDocument::registerNodeClass() a désormais un type de retour provisoire de type true.

Exemples

Exemple #1 Ajout d'une nouvelle méthode à DOMElement

<?php

class myElement extends DOMElement {
   function appendElement($name) { 
      return $this->appendChild(new myElement($name));
   }
}

class myDocument extends DOMDocument {
   function setRoot($name) { 
      return $this->appendChild(new myElement($name));
   }
}

$doc = new myDocument();
$doc->registerNodeClass('DOMElement', 'myElement');

// À partir d'ici, l'ajout d'un élément à un autre se fait en un seul appel !
$root = $doc->setRoot('root');
$child = $root->appendElement('child');
$child->setAttribute('foo', 'bar');

echo $doc->saveXML();

?>

L'exemple ci-dessus va afficher :

<?xml version="1.0"?>
<root><child foo="bar"/></root>

Exemple #2 Récupération d'éléments sous la forme d'une classe personnalisée

<?php
class myElement extends DOMElement {
    public function __toString() {
        return $this->nodeValue;
    }
}

$doc = new DOMDocument;
$doc->loadXML("<root><element><child>Text dans un fils</child></element></root>");
$doc->registerNodeClass("DOMElement", "myElement");

$element = $doc->getElementsByTagName("child")->item(0);
var_dump(get_class($element));

// Et utilisons les avantages de la méthode __toString..
echo $element;
?>

L'exemple ci-dessus va afficher :

string(9) "myElement"
Text dans un fils

Exemple #3 Récupération du propriétaire du document

Lors de l'instanciation d'un DOMDocument personnalisé, la propriété ownerDocument se réfère à la classe instanciée. Cependant, si toutes les références à cette classe sont supprimées, elle sera détruite et une nouvelle instance de DOMDocument sera créée à la place. Pour cette raison, il est possible d'utiliser la méthode DOMDocument::registerNodeClass() avec DOMDocument

<?php
class MyDOMDocument extends DOMDocument {
}

class MyOtherDOMDocument extends DOMDocument {
}

// Création d'un document MyDOMDocument avec quelques fragments XML
$doc = new MyDOMDocument;
$doc->loadXML("<root><element><child>texte dans un fils</child></element></root>");

$child = $doc->getElementsByTagName("child")->item(0);

// Le propriétaire courant du nœud est MyDOMDocument
var_dump(get_class($child->ownerDocument));
// MyDOMDocument est détruit
unset($doc);
// Et une nouvelle instance de DOMDocument est créée
var_dump(get_class($child->ownerDocument));

// Importation d'un nœud depuis MyDOMDocument
$newdoc = new MyOtherDOMDocument;
$child = $newdoc->importNode($child);

// Enregistre un DOMDocument personnalisé
$newdoc->registerNodeClass("DOMDocument", "MyOtherDOMDocument");

var_dump(get_class($child->ownerDocument));
unset($doc);
// Un nouveau MyOtherDOMDocument est créé
var_dump(get_class($child->ownerDocument));
?>

L'exemple ci-dessus va afficher :

string(13) "MyDOMDocument"
string(11) "DOMDocument"
string(18) "MyOtherDOMDocument"
string(18) "MyOtherDOMDocument"

Exemple #4 Les objets personnalisés sont éphémères

Attention

Les objets des classes de nœuds enregistrées sont éphémères, c.-à-d. ils sont détruits quand ils ne sont plus référencés depuis du code PHP, et recréés quand ils sont de nouveau récupérés. Ceci implique que les valeurs de propriétés personnalisées seront perdues après la recréation.

<?php
class MyDOMElement extends DOMElement
{
    public $myProp = 'default value';
}

$doc = new DOMDocument();
$doc->registerNodeClass('DOMElement', 'MyDOMElement');

$node = $doc->createElement('a');
$node->myProp = 'modified value';
$doc->appendChild($node);

echo $doc->childNodes[0]->myProp, PHP_EOL;
unset($node);
echo $doc->childNodes[0]->myProp, PHP_EOL;
?>

L'exemple ci-dessus va afficher :

modified value
default value