Introduce Dom\AdjacentPosition and use it in the insert adjacent methods

See https://wiki.php.net/rfc/dom_additions_84#allowing_php-specific_developer_experience_improvements

ext/dom/dom_ce.h

@@ -66,5 +66,6 @@ extern PHP_DOM_EXPORT zend_class_entry *dom_xpath_class_entry;
 extern PHP_DOM_EXPORT zend_class_entry *dom_modern_xpath_class_entry;
 #endif
 extern PHP_DOM_EXPORT zend_class_entry *dom_namespace_node_class_entry;
+extern PHP_DOM_EXPORT zend_class_entry *dom_adjacent_position_class_entry;
 
 #endif /* DOM_CE_H */

ext/dom/element.c

@@ -21,6 +21,7 @@
 
 #include "php.h"
 #if defined(HAVE_LIBXML) && defined(HAVE_DOM)
+#include "zend_enum.h"
 #include "php_dom.h"
 #include "namespace_compat.h"
 #include "internal_helpers.h"
@@ -1573,17 +1574,12 @@ static xmlNodePtr dom_insert_adjacent(const zend_string *where, xmlNodePtr thisp
 /* {{{ URL: https://dom.spec.whatwg.org/#dom-element-insertadjacentelement
 Since:
 */
-static void dom_element_insert_adjacent_element(INTERNAL_FUNCTION_PARAMETERS, zend_class_entry *element_ce)
+static void dom_element_insert_adjacent_element(INTERNAL_FUNCTION_PARAMETERS, const zend_string *where, zval *element_zval)
 {
-	zend_string *where;
-	zval *element_zval, *id;
+	zval *id;
 	xmlNodePtr thisp, otherp;
 	dom_object *this_intern, *other_intern;
 
-	if (zend_parse_parameters(ZEND_NUM_ARGS(), "SO", &where, &element_zval, element_ce) != SUCCESS) {
-		RETURN_THROWS();
-	}
-
 	DOM_GET_THIS_OBJ(thisp, id, xmlNodePtr, this_intern);
 	DOM_GET_OBJ(otherp, element_zval, xmlNodePtr, other_intern);
 
@@ -1599,29 +1595,39 @@ static void dom_element_insert_adjacent_element(INTERNAL_FUNCTION_PARAMETERS, ze
 
 PHP_METHOD(DOMElement, insertAdjacentElement)
 {
-	dom_element_insert_adjacent_element(INTERNAL_FUNCTION_PARAM_PASSTHRU, dom_element_class_entry);
+	zend_string *where;
+	zval *element_zval;
+
+	if (zend_parse_parameters(ZEND_NUM_ARGS(), "SO", &where, &element_zval, dom_element_class_entry) != SUCCESS) {
+		RETURN_THROWS();
+	}
+
+	dom_element_insert_adjacent_element(INTERNAL_FUNCTION_PARAM_PASSTHRU, where, element_zval);
 }
 
 PHP_METHOD(Dom_Element, insertAdjacentElement)
 {
-	dom_element_insert_adjacent_element(INTERNAL_FUNCTION_PARAM_PASSTHRU, dom_modern_element_class_entry);
+	zval *element_zval, *where_zv;
+
+	ZEND_PARSE_PARAMETERS_START(2, 2)
+		Z_PARAM_OBJECT_OF_CLASS(where_zv, dom_adjacent_position_class_entry)
+		Z_PARAM_OBJECT_OF_CLASS(element_zval, dom_modern_element_class_entry)
+	ZEND_PARSE_PARAMETERS_END();
+
+	const zend_string *where = Z_STR_P(zend_enum_fetch_case_name(Z_OBJ_P(where_zv)));
+	dom_element_insert_adjacent_element(INTERNAL_FUNCTION_PARAM_PASSTHRU, where, element_zval);
 }
 /* }}} end DOMElement::insertAdjacentElement */
 
 /* {{{ URL: https://dom.spec.whatwg.org/#dom-element-insertadjacenttext
 Since:
 */
-PHP_METHOD(DOMElement, insertAdjacentText)
+static void dom_element_insert_adjacent_text(INTERNAL_FUNCTION_PARAMETERS, const zend_string *where, const zend_string *data)
 {
-	zend_string *where, *data;
 	dom_object *this_intern;
 	zval *id;
 	xmlNodePtr thisp;
 
-	if (zend_parse_parameters(ZEND_NUM_ARGS(), "SS", &where, &data) == FAILURE) {
-		RETURN_THROWS();
-	}
-
 	DOM_GET_THIS_OBJ(thisp, id, xmlNodePtr, this_intern);
 
 	if (UNEXPECTED(ZEND_SIZE_T_INT_OVFL(ZSTR_LEN(data)))) {
@@ -1635,6 +1641,31 @@ PHP_METHOD(DOMElement, insertAdjacentText)
 		xmlFreeNode(otherp);
 	}
 }
+
+PHP_METHOD(DOMElement, insertAdjacentText)
+{
+	zend_string *where, *data;
+
+	if (zend_parse_parameters(ZEND_NUM_ARGS(), "SS", &where, &data) == FAILURE) {
+		RETURN_THROWS();
+	}
+
+	dom_element_insert_adjacent_text(INTERNAL_FUNCTION_PARAM_PASSTHRU, where, data);
+}
+
+PHP_METHOD(Dom_Element, insertAdjacentText)
+{
+	zval *where_zv;
+	zend_string *data;
+
+	ZEND_PARSE_PARAMETERS_START(2, 2)
+		Z_PARAM_OBJECT_OF_CLASS(where_zv, dom_adjacent_position_class_entry)
+		Z_PARAM_STR(data)
+	ZEND_PARSE_PARAMETERS_END();
+
+	const zend_string *where = Z_STR_P(zend_enum_fetch_case_name(Z_OBJ_P(where_zv)));
+	dom_element_insert_adjacent_text(INTERNAL_FUNCTION_PARAM_PASSTHRU, where, data);
+}
 /* }}} end DOMElement::insertAdjacentText */
 
 /* {{{ URL: https://dom.spec.whatwg.org/#dom-element-toggleattribute

ext/dom/php_dom.c

@@ -22,6 +22,7 @@
 
 #include "php.h"
 #if defined(HAVE_LIBXML) && defined(HAVE_DOM)
+#include "zend_enum.h"
 #include "php_dom.h"
 #include "nodelist.h"
 #include "html_collection.h"
@@ -84,6 +85,7 @@ PHP_DOM_EXPORT zend_class_entry *dom_xpath_class_entry;
 PHP_DOM_EXPORT zend_class_entry *dom_modern_xpath_class_entry;
 #endif
 PHP_DOM_EXPORT zend_class_entry *dom_namespace_node_class_entry;
+PHP_DOM_EXPORT zend_class_entry *dom_adjacent_position_class_entry;
 /* }}} */
 
 static zend_object_handlers dom_object_handlers;
@@ -729,6 +731,8 @@ PHP_MINIT_FUNCTION(dom)
 
 	zend_hash_init(&classes, 0, NULL, NULL, true);
 
+	dom_adjacent_position_class_entry = register_class_Dom_AdjacentPosition();
+
 	dom_domexception_class_entry = register_class_DOMException(zend_ce_exception);
 
 	dom_parentnode_class_entry = register_class_DOMParentNode();

ext/dom/php_dom.stub.php

@@ -1280,6 +1280,14 @@ public function count(): int {}
         public function getIterator(): \Iterator {}
     }
 
+    enum AdjacentPosition : string
+    {
+        case BeforeBegin = "beforebegin";
+        case AfterBegin = "afterbegin";
+        case BeforeEnd = "beforeend";
+        case AfterEnd = "afterend";
+    }
+
     class Element extends Node implements ParentNode, ChildNode
     {
         /** @readonly */
@@ -1330,9 +1338,8 @@ public function removeAttributeNode(Attr $attr) : Attr {}
         public function getElementsByTagName(string $qualifiedName): HTMLCollection {}
         public function getElementsByTagNameNS(?string $namespace, string $localName): HTMLCollection {}
 
-        public function insertAdjacentElement(string $where, Element $element): ?Element {}
-        /** @implementation-alias DOMElement::insertAdjacentText */
-        public function insertAdjacentText(string $where, string $data): void {}
+        public function insertAdjacentElement(AdjacentPosition $where, Element $element): ?Element {}
+        public function insertAdjacentText(AdjacentPosition $where, string $data): void {}
 
         /** @readonly */
         public ?Element $firstElementChild;

ext/dom/tests/modern/common/Element_insertAdjacentElement.phpt

@@ -0,0 +1,37 @@
+--TEST--
+Element::insertAdjacentElement()
+--EXTENSIONS--
+dom
+--FILE--
+<?php
+
+$dom = Dom\XMLDocument::createFromString('<?xml version="1.0"?><container><p>foo</p></container>');
+$container = $dom->documentElement;
+$p = $container->firstElementChild;
+
+var_dump($p->insertAdjacentElement(Dom\AdjacentPosition::BeforeBegin, $dom->createElement('A'))->tagName);
+echo $dom->saveXML(), "\n";
+
+var_dump($p->insertAdjacentElement(Dom\AdjacentPosition::AfterBegin, $dom->createElement('B'))->tagName);
+echo $dom->saveXML(), "\n";
+
+var_dump($p->insertAdjacentElement(Dom\AdjacentPosition::BeforeEnd, $dom->createElement('C'))->tagName);
+echo $dom->saveXML(), "\n";
+
+var_dump($p->insertAdjacentElement(Dom\AdjacentPosition::AfterEnd, $dom->createElement('D'))->tagName);
+echo $dom->saveXML(), "\n";
+
+?>
+--EXPECT--
+string(1) "A"
+<?xml version="1.0" encoding="UTF-8"?>
+<container><A/><p>foo</p></container>
+string(1) "B"
+<?xml version="1.0" encoding="UTF-8"?>
+<container><A/><p><B/>foo</p></container>
+string(1) "C"
+<?xml version="1.0" encoding="UTF-8"?>
+<container><A/><p><B/>foo<C/></p></container>
+string(1) "D"
+<?xml version="1.0" encoding="UTF-8"?>
+<container><A/><p><B/>foo<C/></p><D/></container>

ext/dom/tests/modern/spec/Element_insertAdjacentText.phpt

@@ -8,13 +8,13 @@ dom
 $dom = Dom\HTMLDocument::createEmpty();
 $foo = $dom->appendChild($dom->createElement("foo"));
 try {
-    $foo->insertAdjacentText("beforebegin", "bar");
+    $foo->insertAdjacentText(Dom\AdjacentPosition::BeforeBegin, "bar");
 } catch (DOMException $e) {
     echo $e->getMessage(), "\n";
 }
 
-$foo->insertAdjacentText("afterbegin", "bar");
-$foo->insertAdjacentText("beforeend", "baz");
+$foo->insertAdjacentText(Dom\AdjacentPosition::AfterBegin, "bar");
+$foo->insertAdjacentText(Dom\AdjacentPosition::BeforeEnd, "baz");
 
 echo $dom->saveHtml(), "\n";