PHP RFC: Implement Current DOM Living Standard API

• Version: 0.2
• Date: 2019-04-06
• Author: Benjamin Eberlei (beberlei@php.net), Thomas Weinert
• Status: Under Discussion
• First Published at: http://wiki.php.net/rfc/dom_living_standard_api

Working with XML (HTML) documents is a necessary task for many web applications and the dom extension implements a standardized API that was previously specified by a w3 group into 3 DOM Levels. Since then the standard has evolved and is now a Living Standard similar to HTML 5 and continously evolving and maintained by the Web Hypertext Application Technology Working Group (WHATWG).

- https://dom.spec.whatwg.org

Because the new API provides much improved traversal and manipulation APIs than the old API we propose to add the new methods to the existing ext/dom API.

Specifically we think this is a better solution to providing them in userland, because

1. ext/dom + DOMDocument represents the DOM Standard, so we should continue to support the evolving versions.
2. the added methods are a huge value add to users and fix a lot of more complicated approaches that were previously required by users. The search or re-implementation costs are high for users.

This RFC proposes to adapt the current DOM standard changes to the PHP langauge by introducing new interfaces and public properties that simplify traversal and manipulation of DOM elements.

<?php
interface DOMParentNode
{
    public readonly DOMNode? $previousElementNode;
    public readonly DOMNode? $nextElementNode;
    public readonly int $childElementCount;
 
    public function append(...DOMNode|string|null $nodes) : void;
    public function prepend(...DOMNode|string|null $nodes) : void;
}
 
class DOMDocument implements DOMParentNode {}
class DOMElement implements DOMParentNode {}
class DOMDocumentFragment implements DOMParentNode {}
 
interface DOMChildNode
{
    public readonly DOMNode? $previousElementSibling;
    public readonly DOMNode? $nextElementSibling;
 
    public function remove() : void;
    public function before(...DOMNode|string|null $nodes) : void;
    public function after(...DOMNode|string|null $nodes) : void;
    public function replaceWith(...DOMNode|string|null $nodes) : void;
}
 
class DOMElement implements DOMChildNode {}
class DOMCharacterData implements DOMChildNode {}
class DOMDocumentType implements DOMChildNode {}

Implementation choices:

The standard implements these interfaces as “traits” and doesn't provide interfaces for them. This might make more sense with the primary language target (JavaScript), but for PHP it makes more sense to have the functionality available through an interface.

The standard contains an intermediate interface DOMNonDocumentTypeChildNode that contains the previousElementSibling and nextElementSibling properties. This is introduced to provide backwards compatibility with browser/web implementations, which are not our concern. In addition PHP interfaces cannot have properties, so it wouldn't make sense to add this empty interface. For this reason this class was not introduced, but the properties are instead on DOMChildNode directly.

The querySelector and querySelectorAll methods defined on the DOMParentNode interface are omitted, because of their complexity we recommend to leave comparable implementations of these methods to userland libraries such as PhpCss or Symfony CSS Selector.

The DOM Specification Level 2-3 introduced DOMImplementation::hasFeature() that were supposed to be used by clients to check for the version of a specification. The living documentation has the following to say about this:

hasFeature() originally would report whether the user agent claimed to support a given DOM feature, but experience proved it was not nearly as reliable or granular as simply checking whether the desired objects, attributes, or methods existed. As such, it is no longer to be used, but continues to exist (and simply returns true) so that old pages don’t stop working.

Changing this would constitute a small BC break, given that this is probably not used by anyone.

Currently DOMImplementation::hasFeature only returns true for “Core” and “1.0” (and for “XML” versions), since 2.0 and 3.0 levels were never fully implemented for ext/dom. However most of the important level 2+3 features have always been implemented. As such users cannot rely on this API anyways.

We propose to keep this method untouched and recommend users to use instanceof, property_exists, or method_exists to test for existance of features as proposed by the DOM Standard documentation.

1. removing the classes that are undocumented, unimplemented and contain dummy data.
2. Code using registerNodeClass to overwrite DOM classes can be affected IF they already implement the new functionality in a way that doesn't satisfy the behavior or signature of this proposed code changes.

PHP 7.4

No effect on SAPIs.

The dom extensions API is changed in a backwards compatible way (only adding new properties/methods).

The new functionality can all be implemented entirely using the already available libxml2 datastructures, so no changes to the libxml2 dependency is nceessary.

No effect on Opcache.

In the future this RFC seeks approval to add more functionality of the DOM Living Standard to ext/dom as long as no backwards incompatible changes are introduced.

https://github.com/beberlei/php-src/pull/1

This pull request is still work in progress.

tbd

- DOM Living Standard Document https://dom.spec.whatwg.org