From 884259a7bcce9f5139069e52ff4da1d02ccf773d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ey=C3=BCp=20Can=20Akman?= <eyupcanakman@gmail.com>
Date: Sun, 15 Mar 2026 23:54:34 +0300
Subject: [PATCH] Fix template contents participating in the DOM tree

---
 README.md                                |  15 +-
 src/HTML5/HTML5DOMDocument.php           | 136 +++++++++
 src/HTML5/HTML5DOMDocument81.php         |  24 ++
 src/HTML5/HTML5DOMDocumentFragment.php   |  44 +++
 src/HTML5/HTML5DOMDocumentFragment81.php |  12 +
 src/HTML5/HTML5DOMElement.php            | 115 +++++++
 src/HTML5/HTML5DOMElement81.php          |  36 +++
 src/HTML5/Parser/DOMTreeBuilder.php      |  70 ++++-
 src/HTML5/Serializer/OutputRules.php     |   8 +
 src/HTML5/TemplateContents.php           | 206 +++++++++++++
 test/HTML5/Html5Test.php                 | 363 +++++++++++++++++++++++
 11 files changed, 1019 insertions(+), 10 deletions(-)
 create mode 100644 src/HTML5/HTML5DOMDocument.php
 create mode 100644 src/HTML5/HTML5DOMDocument81.php
 create mode 100644 src/HTML5/HTML5DOMDocumentFragment.php
 create mode 100644 src/HTML5/HTML5DOMDocumentFragment81.php
 create mode 100644 src/HTML5/HTML5DOMElement.php
 create mode 100644 src/HTML5/HTML5DOMElement81.php
 create mode 100644 src/HTML5/TemplateContents.php

diff --git a/README.md b/README.md
index 8487811..5e8b995 100644
--- a/README.md
+++ b/README.md
@@ -122,7 +122,20 @@ The following options are supported:
   assigning the HTML5 namespace to the DOM document. This is for
   non-namespace aware DOM tools.
 * `target_document` (\DOMDocument): A DOM document that will be used as the
-  destination for the parsed nodes.
+  destination for the parsed nodes. When parsing `<template>` contents into a
+  caller-supplied document, use `HTML5::save()` or `HTML5::saveHTML()` for
+  serialization, since native `DOMDocument::saveHTML()` cannot preserve the
+  detached template subtree on a plain `DOMDocument`. The detached subtree is
+  preserved for documents parsed by HTML5-PHP, including `cloneNode(true)` on
+  caller-supplied target documents and `importNode(true)` on HTML5-PHP-created
+  documents. When a parsed document contains `<template>` elements, HTML5-PHP
+  registers template-aware DOM node wrappers on that document if it is still
+  using the native `DOMElement` and `DOMDocumentFragment` classes, so detached
+  contents can follow `cloneNode(true)`. If a caller-supplied target document
+  already uses custom node classes, HTML5-PHP leaves them in place and detached
+  template contents are still preserved by `HTML5::save()` / `HTML5::saveHTML()`.
+  Native `importNode()` into a plain external `DOMDocument` cannot carry
+  detached template contents.
 * `implicit_namespaces` (array): An assoc array of namespaces that should be
   used by the parser. Name is tag prefix, value is NS URI.
 
diff --git a/src/HTML5/HTML5DOMDocument.php b/src/HTML5/HTML5DOMDocument.php
new file mode 100644
index 0000000..a44ed2b
--- /dev/null
+++ b/src/HTML5/HTML5DOMDocument.php
@@ -0,0 +1,136 @@
+<?php
+
+namespace Masterminds\HTML5;
+
+use Masterminds\HTML5\Serializer\OutputRules;
+use Masterminds\HTML5\Serializer\Traverser;
+
+/**
+ * Shared serializer logic for template-aware DOMDocument implementations.
+ */
+class HTML5DOMDocumentBase extends \DOMDocument
+{
+    /**
+     * @var \SplObjectStorage|null
+     */
+    protected $templateContents;
+
+    /**
+     * @param bool $create
+     *
+     * @return \SplObjectStorage|null
+     */
+    public function html5PhpTemplateContentsStorage($create = true)
+    {
+        if (null === $this->templateContents && $create) {
+            $this->templateContents = new \SplObjectStorage();
+        }
+
+        return $this->templateContents;
+    }
+
+    protected function html5PhpSaveHTML($node = null)
+    {
+        $target = null === $node ? $this : $node;
+        if (!$this->containsDetachedTemplateContents($target)) {
+            return parent::saveHTML($node);
+        }
+
+        $stream = fopen('php://temp', 'wb');
+        $rules = new OutputRules($stream);
+        $traverser = new Traverser($target, $stream, $rules);
+        $traverser->walk();
+        $rules->unsetTraverser();
+
+        $html = stream_get_contents($stream, -1, 0);
+        fclose($stream);
+
+        return $html;
+    }
+
+    protected function html5PhpImportNode($node, $deep = false)
+    {
+        $imported = parent::importNode($node, $deep);
+
+        // Before PHP 8.4 importNode() returns false for a node it cannot import,
+        // a doctype being the case reached here.
+        if (!$imported instanceof \DOMNode) {
+            return $imported;
+        }
+
+        TemplateContents::copySubtree($node, $imported, $deep);
+
+        return $imported;
+    }
+
+    protected function html5PhpCloneNode($deep = false)
+    {
+        $class = get_class($this);
+        $clone = new $class($this->xmlVersion, $this->encoding);
+        TemplateContents::registerNodeClasses($clone);
+
+        $clone->encoding = $this->encoding;
+        $clone->formatOutput = $this->formatOutput;
+        $clone->preserveWhiteSpace = $this->preserveWhiteSpace;
+        $clone->recover = $this->recover;
+        $clone->resolveExternals = $this->resolveExternals;
+        $clone->strictErrorChecking = $this->strictErrorChecking;
+        $clone->substituteEntities = $this->substituteEntities;
+        $clone->validateOnParse = $this->validateOnParse;
+
+        if (!$deep) {
+            return $clone;
+        }
+
+        foreach ($this->childNodes as $child) {
+            $imported = $clone->importNode($child, true);
+            if ($imported instanceof \DOMNode) {
+                $clone->appendChild($imported);
+            }
+        }
+
+        return $clone;
+    }
+
+    /**
+     * @return bool
+     */
+    protected function containsDetachedTemplateContents(\DOMNode $node)
+    {
+        if ($node instanceof \DOMElement && 'template' === strtolower($node->tagName)) {
+            return null !== TemplateContents::find($node);
+        }
+
+        if ($node->hasChildNodes()) {
+            foreach ($node->childNodes as $child) {
+                if ($this->containsDetachedTemplateContents($child)) {
+                    return true;
+                }
+            }
+        }
+
+        return false;
+    }
+}
+
+if (PHP_VERSION_ID >= 80100) {
+    require __DIR__ . '/HTML5DOMDocument81.php';
+} else {
+    class HTML5DOMDocument extends HTML5DOMDocumentBase
+    {
+        public function saveHTML($node = null)
+        {
+            return $this->html5PhpSaveHTML($node);
+        }
+
+        public function importNode($node, $deep = false)
+        {
+            return $this->html5PhpImportNode($node, $deep);
+        }
+
+        public function cloneNode($deep = false)
+        {
+            return $this->html5PhpCloneNode($deep);
+        }
+    }
+}
diff --git a/src/HTML5/HTML5DOMDocument81.php b/src/HTML5/HTML5DOMDocument81.php
new file mode 100644
index 0000000..d36921d
--- /dev/null
+++ b/src/HTML5/HTML5DOMDocument81.php
@@ -0,0 +1,24 @@
+<?php
+
+namespace Masterminds\HTML5;
+
+class HTML5DOMDocument extends HTML5DOMDocumentBase
+{
+    #[\ReturnTypeWillChange]
+    public function saveHTML($node = null)
+    {
+        return $this->html5PhpSaveHTML($node);
+    }
+
+    #[\ReturnTypeWillChange]
+    public function importNode($node, $deep = false)
+    {
+        return $this->html5PhpImportNode($node, $deep);
+    }
+
+    #[\ReturnTypeWillChange]
+    public function cloneNode($deep = false)
+    {
+        return $this->html5PhpCloneNode($deep);
+    }
+}
diff --git a/src/HTML5/HTML5DOMDocumentFragment.php b/src/HTML5/HTML5DOMDocumentFragment.php
new file mode 100644
index 0000000..0880529
--- /dev/null
+++ b/src/HTML5/HTML5DOMDocumentFragment.php
@@ -0,0 +1,44 @@
+<?php
+
+namespace Masterminds\HTML5;
+
+/**
+ * Keep the template-aware owner document alive for detached fragments.
+ */
+class HTML5DOMDocumentFragmentBase extends \DOMDocumentFragment
+{
+    /**
+     * @var \DOMDocument|null
+     */
+    protected $templateOwnerDocument;
+
+    public function html5PhpKeepTemplateOwnerDocument(\DOMDocument $document)
+    {
+        $this->templateOwnerDocument = $document;
+    }
+
+    protected function html5PhpCloneNode($deep = false)
+    {
+        $clone = parent::cloneNode($deep);
+
+        if ($this->templateOwnerDocument instanceof \DOMDocument && method_exists($clone, 'html5PhpKeepTemplateOwnerDocument')) {
+            $clone->html5PhpKeepTemplateOwnerDocument($this->templateOwnerDocument);
+        }
+
+        TemplateContents::copySubtree($this, $clone, $deep);
+
+        return $clone;
+    }
+}
+
+if (PHP_VERSION_ID >= 80100) {
+    require __DIR__ . '/HTML5DOMDocumentFragment81.php';
+} else {
+    class HTML5DOMDocumentFragment extends HTML5DOMDocumentFragmentBase
+    {
+        public function cloneNode($deep = false)
+        {
+            return $this->html5PhpCloneNode($deep);
+        }
+    }
+}
diff --git a/src/HTML5/HTML5DOMDocumentFragment81.php b/src/HTML5/HTML5DOMDocumentFragment81.php
new file mode 100644
index 0000000..491576a
--- /dev/null
+++ b/src/HTML5/HTML5DOMDocumentFragment81.php
@@ -0,0 +1,12 @@
+<?php
+
+namespace Masterminds\HTML5;
+
+class HTML5DOMDocumentFragment extends HTML5DOMDocumentFragmentBase
+{
+    #[\ReturnTypeWillChange]
+    public function cloneNode($deep = false)
+    {
+        return $this->html5PhpCloneNode($deep);
+    }
+}
diff --git a/src/HTML5/HTML5DOMElement.php b/src/HTML5/HTML5DOMElement.php
new file mode 100644
index 0000000..3eb9e11
--- /dev/null
+++ b/src/HTML5/HTML5DOMElement.php
@@ -0,0 +1,115 @@
+<?php
+
+namespace Masterminds\HTML5;
+
+/**
+ * Shared template-aware behavior for DOMElement implementations.
+ */
+class HTML5DOMElementBase extends \DOMElement
+{
+    /**
+     * @var \DOMDocumentFragment|null
+     */
+    protected $templateContents;
+
+    /**
+     * @param \DOMDocumentFragment|null $fragment
+     */
+    public function html5PhpSetTemplateContents($fragment)
+    {
+        $this->templateContents = $fragment;
+    }
+
+    /**
+     * @return \DOMDocumentFragment|null
+     */
+    public function html5PhpTemplateContents()
+    {
+        return $this->templateContents;
+    }
+
+    protected function html5PhpHasDetachedTemplateContents()
+    {
+        return 'template' === strtolower($this->tagName) && $this->templateContents instanceof \DOMDocumentFragment;
+    }
+
+    protected function html5PhpCloneNode($deep = false)
+    {
+        $clone = parent::cloneNode($deep);
+        TemplateContents::copySubtree($this, $clone, $deep);
+
+        return $clone;
+    }
+
+    protected function html5PhpAppendChild($node)
+    {
+        if ($this->html5PhpHasDetachedTemplateContents()) {
+            return $this->templateContents->appendChild($node);
+        }
+
+        return parent::appendChild($node);
+    }
+
+    protected function html5PhpInsertBefore($newnode, $refnode = null)
+    {
+        if ($this->html5PhpHasDetachedTemplateContents()) {
+            if (null === $refnode) {
+                return $this->templateContents->appendChild($newnode);
+            }
+
+            return $this->templateContents->insertBefore($newnode, $refnode);
+        }
+
+        return parent::insertBefore($newnode, $refnode);
+    }
+
+    protected function html5PhpReplaceChild($newnode, $oldnode)
+    {
+        if ($this->html5PhpHasDetachedTemplateContents()) {
+            return $this->templateContents->replaceChild($newnode, $oldnode);
+        }
+
+        return parent::replaceChild($newnode, $oldnode);
+    }
+
+    protected function html5PhpRemoveChild($oldnode)
+    {
+        if ($this->html5PhpHasDetachedTemplateContents()) {
+            return $this->templateContents->removeChild($oldnode);
+        }
+
+        return parent::removeChild($oldnode);
+    }
+}
+
+if (PHP_VERSION_ID >= 80100) {
+    require __DIR__ . '/HTML5DOMElement81.php';
+} else {
+    class HTML5DOMElement extends HTML5DOMElementBase
+    {
+        public function cloneNode($deep = false)
+        {
+            return $this->html5PhpCloneNode($deep);
+        }
+
+        public function appendChild($node)
+        {
+            return $this->html5PhpAppendChild($node);
+        }
+
+        public function insertBefore($newnode, $refnode = null)
+        {
+            return $this->html5PhpInsertBefore($newnode, $refnode);
+        }
+
+        public function replaceChild($newnode, $oldnode)
+        {
+            return $this->html5PhpReplaceChild($newnode, $oldnode);
+        }
+
+        public function removeChild($oldnode)
+        {
+            return $this->html5PhpRemoveChild($oldnode);
+        }
+    }
+}
diff --git a/src/HTML5/HTML5DOMElement81.php b/src/HTML5/HTML5DOMElement81.php
new file mode 100644
index 0000000..e220ee5
--- /dev/null
+++ b/src/HTML5/HTML5DOMElement81.php
@@ -0,0 +1,36 @@
+<?php
+
+namespace Masterminds\HTML5;
+
+class HTML5DOMElement extends HTML5DOMElementBase
+{
+    #[\ReturnTypeWillChange]
+    public function cloneNode($deep = false)
+    {
+        return $this->html5PhpCloneNode($deep);
+    }
+
+    #[\ReturnTypeWillChange]
+    public function appendChild($node)
+    {
+        return $this->html5PhpAppendChild($node);
+    }
+
+    #[\ReturnTypeWillChange]
+    public function insertBefore($newnode, $refnode = null)
+    {
+        return $this->html5PhpInsertBefore($newnode, $refnode);
+    }
+
+    #[\ReturnTypeWillChange]
+    public function replaceChild($newnode, $oldnode)
+    {
+        return $this->html5PhpReplaceChild($newnode, $oldnode);
+    }
+
+    #[\ReturnTypeWillChange]
+    public function removeChild($oldnode)
+    {
+        return $this->html5PhpRemoveChild($oldnode);
+    }
+}
diff --git a/src/HTML5/Parser/DOMTreeBuilder.php b/src/HTML5/Parser/DOMTreeBuilder.php
index 588c8e7..66a0618 100644
--- a/src/HTML5/Parser/DOMTreeBuilder.php
+++ b/src/HTML5/Parser/DOMTreeBuilder.php
@@ -3,7 +3,9 @@
 namespace Masterminds\HTML5\Parser;
 
 use Masterminds\HTML5\Elements;
+use Masterminds\HTML5\HTML5DOMDocument;
 use Masterminds\HTML5\InstructionProcessor;
+use Masterminds\HTML5\TemplateContents;
 
 /**
  * Create an HTML5 DOM tree from events.
@@ -147,6 +149,10 @@ class DOMTreeBuilder implements EventHandler
 
     protected $insertMode = 0;
 
+    protected $templateStack = array();
+
+    protected $templateNodeClassesResolved = false;
+
     /**
      * Track if we are in an element that allows only inline child nodes.
      *
@@ -174,11 +180,15 @@ public function __construct($isFragment = false, array $options = array())
             // Create the doctype. For now, we are always creating HTML5
             // documents, and attempting to up-convert any older DTDs to HTML5.
             $dt = $impl->createDocumentType('html');
-            // $this->doc = \DOMImplementation::createDocument(NULL, 'html', $dt);
-            $this->doc = $impl->createDocument(null, '', $dt);
+            $this->doc = new HTML5DOMDocument('1.0', !empty($options['encoding']) ? $options['encoding'] : 'UTF-8');
+            $this->doc->appendChild($dt);
             $this->doc->encoding = !empty($options['encoding']) ? $options['encoding'] : 'UTF-8';
         }
 
+        if (!isset($options[self::OPT_TARGET_DOC]) || $isFragment) {
+            TemplateContents::registerNodeClasses($this->doc);
+            $this->templateNodeClassesResolved = true;
+        }
         $this->errors = array();
 
         $this->current = $this->doc; // ->documentElement;
@@ -199,6 +209,9 @@ public function __construct($isFragment = false, array $options = array())
         if ($isFragment) {
             $this->insertMode = static::IM_IN_BODY;
             $this->frag = $this->doc->createDocumentFragment();
+            if (method_exists($this->frag, 'html5PhpKeepTemplateOwnerDocument')) {
+                $this->frag->html5PhpKeepTemplateOwnerDocument($this->doc);
+            }
             $this->current = $this->frag;
         }
     }
@@ -325,6 +338,11 @@ public function startTag($name, $attributes = array(), $selfClosing = false)
             $lname = Elements::normalizeSvgElement($lname);
         }
 
+        if ('template' === $lname && !$this->templateNodeClassesResolved) {
+            TemplateContents::registerNodeClasses($this->doc);
+            $this->templateNodeClassesResolved = true;
+        }
+
         $pushes = 0;
         // when we found a tag thats appears inside $nsRoots, we have to switch the defalut namespace
         if (isset($this->nsRoots[$lname]) && $this->nsStack[0][''] !== $this->nsRoots[$lname]) {
@@ -437,6 +455,11 @@ public function startTag($name, $attributes = array(), $selfClosing = false)
             }
         }
 
+        $templateContents = null;
+        if ('template' === $lname) {
+            $templateContents = $this->doc->createDocumentFragment();
+        }
+
         if ($this->frag !== $this->current && $this->rules->hasRules($name)) {
             // Some elements have special processing rules. Handle those separately.
             $this->current = $this->rules->evaluate($ele, $this->current);
@@ -445,7 +468,13 @@ public function startTag($name, $attributes = array(), $selfClosing = false)
             $this->current->appendChild($ele);
 
             if (!Elements::isA($name, Elements::VOID_TAG)) {
-                $this->current = $ele;
+                if ($templateContents) {
+                    TemplateContents::store($ele, $templateContents);
+                    $this->templateStack[] = array($ele, $this->current, $templateContents);
+                    $this->current = $templateContents;
+                } else {
+                    $this->current = $ele;
+                }
             }
 
             // Self-closing tags should only be respected on foreign elements
@@ -516,6 +545,18 @@ public function endTag($name)
             return;
         }
 
+        if ('template' === $lname && !empty($this->templateStack)) {
+            $templateState = array_pop($this->templateStack);
+            while ($this->current !== $templateState[2]) {
+                $this->popNamespaces($this->current);
+                $this->current = $this->current->parentNode;
+            }
+            $this->popNamespaces($templateState[0]);
+            $this->current = $templateState[1];
+
+            return;
+        }
+
         // Special case handling for SVG.
         if ($this->insertMode === static::IM_IN_SVG) {
             $lname = Elements::normalizeSvgElement($lname);
@@ -530,12 +571,7 @@ public function endTag($name)
         }
 
         // remove the namespaced definded by current node
-        if (isset($this->pushes[$cid])) {
-            for ($i = 0; $i < $this->pushes[$cid][0]; ++$i) {
-                array_shift($this->nsStack);
-            }
-            unset($this->pushes[$cid]);
-        }
+        $this->popNamespaces($this->current);
 
         if (!$this->autoclose($lname)) {
             $this->parseError('Could not find closing tag for ' . $lname);
@@ -676,6 +712,22 @@ protected function autoclose($tagName)
         return false;
     }
 
+    /**
+     * Remove the namespaces declared by a node from the active namespace stack.
+     */
+    protected function popNamespaces(\DOMNode $node)
+    {
+        $cid = spl_object_id($node);
+        if (!isset($this->pushes[$cid])) {
+            return;
+        }
+
+        for ($i = 0; $i < $this->pushes[$cid][0]; ++$i) {
+            array_shift($this->nsStack);
+        }
+        unset($this->pushes[$cid]);
+    }
+
     /**
      * Checks if the given tagname is an ancestor of the present candidate.
      *
diff --git a/src/HTML5/Serializer/OutputRules.php b/src/HTML5/Serializer/OutputRules.php
index a7aa8fc..4d0db4b 100644
--- a/src/HTML5/Serializer/OutputRules.php
+++ b/src/HTML5/Serializer/OutputRules.php
@@ -10,6 +10,7 @@
 namespace Masterminds\HTML5\Serializer;
 
 use Masterminds\HTML5\Elements;
+use Masterminds\HTML5\TemplateContents;
 
 /**
  * Generate the output html5 based on element rules.
@@ -201,6 +202,7 @@ protected function doctype()
     public function element($ele)
     {
         $name = $ele->tagName;
+        $templateContents = null;
 
         // Per spec:
         // If the element has a declared namespace in the HTML, MathML or
@@ -209,6 +211,10 @@ public function element($ele)
             $name = $ele->localName;
         }
 
+        if ('template' === $name) {
+            $templateContents = TemplateContents::find($ele);
+        }
+
         // If we are in SVG or MathML there is special handling.
         // Using if/elseif instead of switch because it's faster in PHP.
         if ('svg' == $name) {
@@ -234,6 +240,8 @@ public function element($ele)
             // Handle children.
             if ($ele->hasChildNodes()) {
                 $this->traverser->children($ele->childNodes);
+            } elseif ($templateContents instanceof \DOMDocumentFragment && $templateContents->hasChildNodes()) {
+                $this->traverser->children($templateContents->childNodes);
             }
 
             // Close out the SVG or MathML special handling.
diff --git a/src/HTML5/TemplateContents.php b/src/HTML5/TemplateContents.php
new file mode 100644
index 0000000..9d7cc98
--- /dev/null
+++ b/src/HTML5/TemplateContents.php
@@ -0,0 +1,206 @@
+<?php
+
+namespace Masterminds\HTML5;
+
+/**
+ * Access detached template contents stored on HTML5-aware DOM nodes.
+ */
+class TemplateContents
+{
+    /**
+     * Fallback storage for caller-supplied plain DOMDocument instances on
+     * runtimes without WeakMap support.
+     *
+     * @var array
+     */
+    private static $storage = array();
+
+    /**
+     * Weakly-keyed storage for caller-supplied plain DOMDocument instances.
+     *
+     * @var object|null
+     */
+    private static $weakStorage;
+
+    /**
+     * @return bool
+     */
+    public static function registerNodeClasses(\DOMDocument $document)
+    {
+        class_exists('Masterminds\\HTML5\\HTML5DOMElement');
+        class_exists('Masterminds\\HTML5\\HTML5DOMDocumentFragment');
+
+        $elementClass = ltrim(get_class($document->createElement('html5-php-probe')), '\\');
+        if (!in_array($elementClass, array('DOMElement', 'Masterminds\\HTML5\\HTML5DOMElement'), true)) {
+            return false;
+        }
+
+        $fragmentClass = ltrim(get_class($document->createDocumentFragment()), '\\');
+        if (!in_array($fragmentClass, array('DOMDocumentFragment', 'Masterminds\\HTML5\\HTML5DOMDocumentFragment'), true)) {
+            return false;
+        }
+
+        if ('Masterminds\\HTML5\\HTML5DOMElement' !== $elementClass) {
+            $document->registerNodeClass('DOMElement', 'Masterminds\\HTML5\\HTML5DOMElement');
+        }
+
+        if ('Masterminds\\HTML5\\HTML5DOMDocumentFragment' !== $fragmentClass) {
+            $document->registerNodeClass('DOMDocumentFragment', 'Masterminds\\HTML5\\HTML5DOMDocumentFragment');
+        }
+
+        return true;
+    }
+
+    /**
+     * @return bool
+     */
+    public static function store(\DOMElement $element, \DOMDocumentFragment $fragment)
+    {
+        if (method_exists($element, 'html5PhpSetTemplateContents')) {
+            $element->html5PhpSetTemplateContents($fragment);
+        }
+
+        $storage = self::storage($element->ownerDocument, true);
+        $storage[$element] = $fragment;
+
+        return true;
+    }
+
+    /**
+     * @return \DOMDocumentFragment|null
+     */
+    public static function find(\DOMElement $element)
+    {
+        if (method_exists($element, 'html5PhpTemplateContents')) {
+            $fragment = $element->html5PhpTemplateContents();
+            if ($fragment instanceof \DOMDocumentFragment) {
+                return $fragment;
+            }
+        }
+
+        $storage = self::storage($element->ownerDocument, false);
+        if (!$storage || !$storage->offsetExists($element)) {
+            return null;
+        }
+
+        return $storage[$element];
+    }
+
+    public static function forget(\DOMElement $element)
+    {
+        if (method_exists($element, 'html5PhpSetTemplateContents')) {
+            $element->html5PhpSetTemplateContents(null);
+        }
+
+        $storage = self::storage($element->ownerDocument, false);
+        if ($storage && $storage->offsetExists($element)) {
+            $storage->offsetUnset($element);
+        }
+    }
+
+    /**
+     * Copy detached template contents from one DOM subtree to another.
+     *
+     * @param bool $deep
+     *
+     * @return \DOMNode
+     */
+    public static function copySubtree(\DOMNode $source, \DOMNode $target, $deep)
+    {
+        if (!$deep) {
+            return $target;
+        }
+
+        if ($source instanceof \DOMElement && $target instanceof \DOMElement) {
+            $contents = self::find($source);
+            if ($contents instanceof \DOMDocumentFragment) {
+                self::store($target, self::cloneFragment($contents, $target->ownerDocument));
+            }
+        }
+
+        $sourceChildren = self::nodeListToArray($source->childNodes);
+        $targetChildren = self::nodeListToArray($target->childNodes);
+        $length = count($sourceChildren);
+        if ($length > count($targetChildren)) {
+            $length = count($targetChildren);
+        }
+
+        for ($i = 0; $i < $length; ++$i) {
+            self::copySubtree($sourceChildren[$i], $targetChildren[$i], true);
+        }
+
+        return $target;
+    }
+
+    /**
+     * @param bool $create
+     *
+     * @return \SplObjectStorage|null
+     */
+    protected static function storage(\DOMDocument $document, $create)
+    {
+        if (method_exists($document, 'html5PhpTemplateContentsStorage')) {
+            return $document->html5PhpTemplateContentsStorage($create);
+        }
+
+        if (class_exists('WeakMap')) {
+            if (null === self::$weakStorage) {
+                self::$weakStorage = new \WeakMap();
+            }
+
+            if (!isset(self::$weakStorage[$document])) {
+                if (!$create) {
+                    return null;
+                }
+
+                self::$weakStorage[$document] = new \SplObjectStorage();
+            }
+
+            return self::$weakStorage[$document];
+        }
+
+        $key = spl_object_hash($document);
+        if (!isset(self::$storage[$key])) {
+            if (!$create) {
+                return null;
+            }
+
+            self::$storage[$key] = new \SplObjectStorage();
+        }
+
+        return self::$storage[$key];
+    }
+
+    /**
+     * @return \DOMDocumentFragment
+     */
+    protected static function cloneFragment(\DOMDocumentFragment $fragment, \DOMDocument $document)
+    {
+        $clone = $document->createDocumentFragment();
+
+        foreach (self::nodeListToArray($fragment->childNodes) as $child) {
+            if ($document === $child->ownerDocument) {
+                $copy = $child->cloneNode(true);
+            } else {
+                $copy = $document->importNode($child, true);
+            }
+            $clone->appendChild($copy);
+            self::copySubtree($child, $copy, true);
+        }
+
+        return $clone;
+    }
+
+    /**
+     * @return array
+     */
+    protected static function nodeListToArray(\DOMNodeList $nodes)
+    {
+        $items = array();
+        foreach ($nodes as $node) {
+            $items[] = $node;
+        }
+
+        return $items;
+    }
+}
diff --git a/test/HTML5/Html5Test.php b/test/HTML5/Html5Test.php
index 0fd307e..93aafba 100644
--- a/test/HTML5/Html5Test.php
+++ b/test/HTML5/Html5Test.php
@@ -4,6 +4,14 @@
 
 use Masterminds\HTML5;
 
+class Html5TestTemplateElement extends \DOMElement
+{
+}
+
+class Html5TestTemplateFragment extends \DOMDocumentFragment
+{
+}
+
 class Html5Test extends TestCase
 {
     /**
@@ -38,6 +46,32 @@ protected function cycleFragment($fragment)
         return $out;
     }
 
+    protected function assertStringContainsCompat($needle, $haystack)
+    {
+        if (method_exists($this, 'assertStringContainsString')) {
+            $this->assertStringContainsString($needle, $haystack);
+        } else {
+            $this->assertContains($needle, $haystack);
+        }
+    }
+
+    protected function assertStringNotContainsCompat($needle, $haystack)
+    {
+        if (method_exists($this, 'assertStringNotContainsString')) {
+            $this->assertStringNotContainsString($needle, $haystack);
+        } else {
+            $this->assertFalse(false !== strpos($haystack, $needle));
+        }
+    }
+
+    protected function assertStringContainsNormalized($needle, $haystack)
+    {
+        $this->assertStringContainsCompat(
+            preg_replace('/\s+/', '', $needle),
+            preg_replace('/\s+/', '', $haystack)
+        );
+    }
+
     public function testImageTagsInSvg()
     {
         $html = '<!DOCTYPE html>
@@ -229,6 +263,335 @@ public function testLoadHTMLFragment()
         $this->assertEmpty($this->html5->getErrors());
     }
 
+    public function testTemplateContentsDoNotParticipateInDomTree()
+    {
+        $dom = $this->html5->loadHTML(
+            '<!DOCTYPE html>
+            <html>
+                <body>
+                    <template><div>foo</div></template>
+                </body>
+            </html>'
+        );
+
+        $this->assertEmpty($this->html5->getErrors());
+
+        $xpath = new \DOMXPath($dom);
+        $xpath->registerNamespace('html', 'http://www.w3.org/1999/xhtml');
+
+        $this->assertNull($dom->getElementsByTagName('template')->item(0)->firstChild);
+        $this->assertFalse($dom->getElementsByTagName('template')->item(0)->hasAttribute('__html5_php_template_contents'));
+        $this->assertEquals(0, $xpath->query('//html:div')->length);
+        $saved = $this->html5->saveHTML($dom);
+        $this->assertStringContainsCompat('<template><div>foo</div></template>', $dom->saveHTML());
+        $this->assertStringContainsCompat('<template><div>foo</div></template>', $saved);
+    }
+
+    public function testTemplateContentsWorkInHtmlFragments()
+    {
+        $fragment = $this->html5->loadHTMLFragment('<template><div>foo</div></template>');
+
+        $this->assertEmpty($this->html5->getErrors());
+        $this->assertEquals('template', $fragment->firstChild->nodeName);
+        $this->assertNull($fragment->firstChild->firstChild);
+        $this->assertEquals('<template><div>foo</div></template>', $this->html5->saveHTML($fragment));
+    }
+
+    public function testNestedTemplateContentsRoundTrip()
+    {
+        $dom = $this->html5->loadHTML(
+            '<!DOCTYPE html>
+            <html>
+                <body>
+                    <template><template><div>foo</div></template></template>
+                </body>
+            </html>'
+        );
+
+        $this->assertEmpty($this->html5->getErrors());
+
+        $this->assertStringContainsCompat(
+            '<template><template><div>foo</div></template></template>',
+            $this->html5->saveHTML($dom)
+        );
+    }
+
+    public function testTemplateContentsStayWithTheSameElementWhenSiblingOrderChanges()
+    {
+        $dom = $this->html5->loadHTML(
+            '<!DOCTYPE html>
+            <html>
+                <body>
+                    <template id="source"><div>foo</div></template>
+                </body>
+            </html>'
+        );
+
+        $template = $dom->getElementsByTagName('template')->item(0);
+        $before = $dom->createElement('template');
+        $before->setAttribute('id', 'before');
+        $template->parentNode->insertBefore($before, $template);
+
+        $this->assertStringContainsNormalized(
+            '<template id="before"></template><template id="source"><div>foo</div></template>',
+            $this->html5->saveHTML($dom)
+        );
+    }
+
+    public function testTemplateCloneNodeDeepKeepsDetachedContents()
+    {
+        $dom = $this->html5->loadHTML(
+            '<!DOCTYPE html>
+            <html>
+                <body>
+                    <template id="source"><div>foo</div></template>
+                </body>
+            </html>'
+        );
+
+        $template = $dom->getElementsByTagName('template')->item(0);
+        $clone = $template->cloneNode(true);
+        $clone->setAttribute('id', 'clone');
+        $template->parentNode->appendChild($clone);
+
+        $this->assertStringContainsNormalized(
+            '<template id="source"><div>foo</div></template><template id="clone"><div>foo</div></template>',
+            $this->html5->saveHTML($dom)
+        );
+    }
+
+    public function testTemplateImportNodeDeepKeepsDetachedContents()
+    {
+        $source = $this->html5->loadHTML(
+            '<!DOCTYPE html>
+            <html>
+                <body>
+                    <template id="source"><div>foo</div></template>
+                </body>
+            </html>'
+        );
+        $target = $this->html5->loadHTML('<!DOCTYPE html><html><body></body></html>');
+
+        $imported = $target->importNode($source->getElementsByTagName('template')->item(0), true);
+        $imported->setAttribute('id', 'imported');
+        $target->getElementsByTagName('body')->item(0)->appendChild($imported);
+
+        $this->assertStringContainsNormalized(
+            '<template id="imported"><div>foo</div></template>',
+            $this->html5->saveHTML($target)
+        );
+    }
+
+    public function testTemplateDocumentCloneNodeDeepKeepsDetachedContents()
+    {
+        $dom = $this->html5->loadHTML(
+            '<!DOCTYPE html>
+            <html>
+                <body>
+                    <template><div>foo</div></template>
+                </body>
+            </html>'
+        );
+
+        $clone = $dom->cloneNode(true);
+
+        $this->assertInstanceOf('Masterminds\\HTML5\\HTML5DOMDocument', $clone);
+        $this->assertStringContainsCompat('<template><div>foo</div></template>', $this->html5->saveHTML($clone));
+    }
+
+    public function testTemplateFragmentCloneNodeDeepKeepsDetachedContents()
+    {
+        $fragment = $this->html5->loadHTMLFragment('<template><div>foo</div></template>');
+        $clone = $fragment->cloneNode(true);
+
+        $this->assertInstanceOf('Masterminds\\HTML5\\HTML5DOMDocumentFragment', $clone);
+        $this->assertEquals('<template><div>foo</div></template>', $this->html5->saveHTML($clone));
+    }
+
+    public function testTemplateSerializationKeepsDetachedContentsAfterMutation()
+    {
+        $dom = $this->html5->loadHTML(
+            '<!DOCTYPE html>
+            <html>
+                <body>
+                    <template><div>foo</div></template>
+                </body>
+            </html>'
+        );
+
+        $template = $dom->getElementsByTagName('template')->item(0);
+        $template->appendChild($dom->createElement('span', 'bar'));
+
+        $this->assertStringContainsNormalized(
+            '<template><div>foo</div><span>bar</span></template>',
+            $this->html5->saveHTML($dom)
+        );
+    }
+
+    public function testTemplateMutationProxiesKeepDetachedContents()
+    {
+        $dom = $this->html5->loadHTML(
+            '<!DOCTYPE html>
+            <html>
+                <body>
+                    <template><span>two</span><em>three</em></template>
+                </body>
+            </html>'
+        );
+
+        $template = $dom->getElementsByTagName('template')->item(0);
+        $contents = \Masterminds\HTML5\TemplateContents::find($template);
+
+        $template->insertBefore($dom->createElement('strong', 'one'), $contents->firstChild);
+        $template->replaceChild($dom->createElement('b', 'TWO'), $contents->childNodes->item(1));
+        $template->removeChild($contents->lastChild);
+
+        $this->assertStringContainsNormalized(
+            '<template><strong>one</strong><b>TWO</b></template>',
+            $this->html5->saveHTML($dom)
+        );
+    }
+
+    public function testTemplateSaveHtmlSubtreeKeepsDetachedContents()
+    {
+        $dom = $this->html5->loadHTML(
+            '<!DOCTYPE html>
+            <html>
+                <body>
+                    <template><div>foo</div></template>
+                </body>
+            </html>'
+        );
+
+        $template = $dom->getElementsByTagName('template')->item(0);
+        $this->assertEquals('<template><div>foo</div></template>', $dom->saveHTML($template));
+    }
+
+    public function testTemplateContentsDoNotLeakNamespaces()
+    {
+        $dom = $this->html5->loadHTML(
+            '<!DOCTYPE html>
+            <html xmlns="http://www.w3.org/1999/xhtml">
+                <body>
+                    <template xmlns="urn:template"><div>foo</div></template>
+                    <div>bar</div>
+                </body>
+            </html>',
+            array('xmlNamespaces' => true)
+        );
+
+        $this->assertEmpty($this->html5->getErrors());
+
+        $xpath = new \DOMXPath($dom);
+        $xpath->registerNamespace('html', 'http://www.w3.org/1999/xhtml');
+
+        $this->assertEquals(1, $xpath->query('//html:body/html:div')->length);
+        $this->assertEquals('http://www.w3.org/1999/xhtml', $xpath->query('//html:body/html:div')->item(0)->namespaceURI);
+    }
+
+    public function testTemplateContentsKeepTargetDocumentBehavior()
+    {
+        $targetDocument = new \DOMDocument();
+        $dom = $this->html5->loadHTML(
+            '<!DOCTYPE html>
+            <html>
+                <body>
+                    <template><div>foo</div></template>
+                </body>
+            </html>',
+            array('target_document' => $targetDocument)
+        );
+
+        $this->assertSame($targetDocument, $dom);
+
+        $xpath = new \DOMXPath($dom);
+        $xpath->registerNamespace('html', 'http://www.w3.org/1999/xhtml');
+
+        $this->assertNull($dom->getElementsByTagName('template')->item(0)->firstChild);
+        $this->assertEquals(0, $xpath->query('//html:div')->length);
+        $html = $dom->saveHTML();
+        $this->assertStringNotContainsCompat('__html5_php_template_contents', $html);
+        $this->assertStringContainsCompat('<template><div>foo</div></template>', $this->html5->saveHTML($dom));
+    }
+
+    public function testTemplateContentsKeepTargetDocumentCustomNodeClasses()
+    {
+        $targetDocument = new \DOMDocument();
+        $targetDocument->registerNodeClass('DOMElement', 'Masterminds\\HTML5\\Tests\\Html5TestTemplateElement');
+        $targetDocument->registerNodeClass('DOMDocumentFragment', 'Masterminds\\HTML5\\Tests\\Html5TestTemplateFragment');
+
+        $dom = $this->html5->loadHTML(
+            '<!DOCTYPE html>
+            <html>
+                <body>
+                    <template><div>foo</div></template>
+                </body>
+            </html>',
+            array('target_document' => $targetDocument)
+        );
+
+        $template = $dom->getElementsByTagName('template')->item(0);
+
+        $this->assertInstanceOf('Masterminds\\HTML5\\Tests\\Html5TestTemplateElement', $template);
+        $this->assertInstanceOf('Masterminds\\HTML5\\Tests\\Html5TestTemplateFragment', $dom->createDocumentFragment());
+        $this->assertNull($template->firstChild);
+        $this->assertStringContainsCompat('<template><div>foo</div></template>', $this->html5->saveHTML($dom));
+    }
+
+    public function testTemplateCloneNodeDeepKeepsDetachedContentsOnTargetDocument()
+    {
+        $targetDocument = new \DOMDocument();
+        $dom = $this->html5->loadHTML(
+            '<!DOCTYPE html>
+            <html>
+                <body>
+                    <template id="source"><div>foo</div></template>
+                </body>
+            </html>',
+            array('target_document' => $targetDocument)
+        );
+
+        $template = $dom->getElementsByTagName('template')->item(0);
+        $clone = $template->cloneNode(true);
+        $clone->setAttribute('id', 'clone');
+        $template->parentNode->appendChild($clone);
+
+        $this->assertStringContainsNormalized(
+            '<template id="source"><div>foo</div></template><template id="clone"><div>foo</div></template>',
+            $this->html5->saveHTML($dom)
+        );
+    }
+
+    public function testTemplateContentsInternalIdDoesNotLeakWhenImported()
+    {
+        $dom = $this->html5->loadHTML(
+            '<!DOCTYPE html>
+            <html>
+                <body>
+                    <template><div>foo</div></template>
+                </body>
+            </html>'
+        );
+
+        $targetDocument = new \DOMDocument();
+        $targetDocument->appendChild($targetDocument->importNode($dom->getElementsByTagName('template')->item(0), false));
+        unset($dom);
+
+        $html = $this->html5->saveHTML($targetDocument);
+        $this->assertStringContainsCompat('<template></template>', $html);
+        $this->assertStringNotContainsCompat('__html5_php_template_contents', $html);
+    }
+
+    public function testTemplateContentsAreNotPreservedByNativeImportIntoPlainDomDocument()
+    {
+        $fragment = $this->html5->loadHTMLFragment('<template><div>foo</div></template>');
+
+        $targetDocument = new \DOMDocument();
+        $targetDocument->appendChild($targetDocument->importNode($fragment->firstChild, true));
+
+        $this->assertStringContainsCompat('<template></template>', $this->html5->saveHTML($targetDocument));
+    }
+
     public function testSaveHTML()
     {
         $dom = $this->html5->load(__DIR__ . '/Html5Test.html');