PHP RFC: New ext-dom features in PHP 8.4

• Version: 0.1
• Date: 2024-04-12
• Author: Niels Dossche, nielsdos@php.net
• Status: Draft
• First Published at: http://wiki.php.net/rfc/dom_additions_84

The PHP 8.4 development cycle has seen two major improvements to the ext-dom extension already: HTML 5 support, and opt-in spec compliance. This RFC is the final improvement to ext-dom for PHP 8.4: it proposes to add new features to the extension. In particular, we'll be focussing on CSS selector support, filling in feature holes, and adding new properties.

The proposal consists of multiple sub-proposals bundled together under one RFC to minimize overhead. In this section, we'll discuss each feature separately.

DOM functions like Element::insertAdjacentElement(string $where, Element $element) and Element::insertAdjacentText(string $where, string $data) have a first “where” argument. There are only four valid values for “where”: “beforebegin”, “afterbegin”, “beforeend”, “afterend”. So that's actually an enum in disguise. I propose to make use of the PHP enum feature. This would prevent programming mistakes and make IDE hints much nicer, contributing to a better developer experience. Strictly speaking, this deviates from the DOM spec, but we already model the DOM classes in a way that fits PHP's OOP model. In fact, I'd propose to allow the use of enums where it makes sense in the extension for new APIs. Since the Element class didn't exist prior to the opt-in spec compliance RFC, we can change the signature without affecting users as no releases of PHP 8.4 have been made so far.

In particular, this will result in the following enum and function signatures:

namespace DOM {
  enum AdjacentPosition {
    BeforeBegin,
    AfterBegin,
    BeforeEnd,
    AfterEnd,
  }
 
  Element::insertAdjacentElement(string $where, Element $element): ?Element;
  Element::insertAdjacentText(string $where, string $data): void;
}

None.

PHP 8.4.

Only ext-dom is affected.

None yet.

Everything outside ext-dom.

I initially planned on including properties like innerHTML, and outerHTML too. This is very feasible with all the internal DOM work that happened during the PHP 8.4 development cycle. However, I do not feel sufficiently motivated to sink even more hours into new feature work again for 8.4. If someone really wants this in 8.4, feel free to make a PoC implementation, should be fairly doable using Lexbor.

Include these so readers know where you are heading and can discuss the proposed voting options.

Links to any external patches and tests go here.

If there is no patch, make it clear who will create a patch, or whether a volunteer to help with implementation is needed.

Make it clear if the patch is intended to be the final patch, or is just a prototype.

For changes affecting the core language, you should also provide a patch for the language specification.

After the project is implemented, this section should contain

1. the version(s) it was merged into
2. a link to the git commit(s)
3. a link to the PHP manual entry for the feature
4. a link to the language specification section (if any)

Links to external references, discussions or RFCs