Add support for ParentNode::$children (php#18908)

ParentNode::$children returns a HTMLCollection of all directly
descendant child elements of a container.

I had to move around some properties such that the ParentNode property
offsets are always at a fixed offset, to simplify the code.
This also adds the necessary code to deal with GC cycles in
HTMLCollections.
Furthermore, we also disable cloning a HTMLCollection as that never
worked and furthermore it also conflicts with the [[SameObject]] WebIDL
requirement of $children.

Author: ndossche

NEWS

@@ -74,6 +74,7 @@ PHP                                                                        NEWS
 - DOM:
   . Added Dom\Element::$outerHTML. (nielsdos)
   . Added Dom\Element::insertAdjacentHTML(). (nielsdos)
+  . Added $children property to ParentNode implementations. (nielsdos)
 
 - Enchant:
   . Added enchant_dict_remove_from_session(). (nielsdos)

UPGRADING

@@ -185,6 +185,7 @@ PHP 8.5 UPGRADE NOTES
 
 - DOM:
   . Added Dom\Element::$outerHTML.
+  . Added $children property to Dom\ParentNode implementations.
 
 - EXIF:
   . Add OffsetTime* Exif tags.

ext/dom/dom_properties.h

@@ -109,6 +109,7 @@ zend_result dom_entity_reference_child_nodes_read(dom_object *obj, zval *retval)
 zend_result dom_namednodemap_length_read(dom_object *obj, zval *retval);
 
 /* parent node properties */
+zend_result dom_parent_node_children_read(dom_object *obj, zval *retval);
 zend_result dom_parent_node_first_element_child_read(dom_object *obj, zval *retval);
 zend_result dom_parent_node_last_element_child_read(dom_object *obj, zval *retval);
 zend_result dom_parent_node_child_element_count(dom_object *obj, zval *retval);

ext/dom/element.c

@@ -177,18 +177,21 @@ zend_result dom_element_class_name_write(dom_object *obj, zval *newval)
 }
 /* }}} */
 
-zval *dom_element_class_list_zval(dom_object *obj)
+zval *dom_get_prop_checked_offset(dom_object *obj, uint32_t offset, const char *name)
 {
-	const uint32_t PROP_INDEX = 0;
-
 #if ZEND_DEBUG
-	zend_string *class_list_str = ZSTR_INIT_LITERAL("classList", false);
-	const zend_property_info *prop_info = zend_get_property_info(dom_modern_element_class_entry, class_list_str, 0);
-	zend_string_release_ex(class_list_str, false);
-	ZEND_ASSERT(OBJ_PROP_TO_NUM(prop_info->offset) == PROP_INDEX);
+	zend_string *name_zstr = ZSTR_INIT_LITERAL(name, false);
+	const zend_property_info *prop_info = zend_get_property_info(obj->std.ce, name_zstr, 0);
+	zend_string_release_ex(name_zstr, false);
+	ZEND_ASSERT(OBJ_PROP_TO_NUM(prop_info->offset) == offset);
 #endif
 
-	return OBJ_PROP_NUM(&obj->std, PROP_INDEX);
+	return OBJ_PROP_NUM(&obj->std, offset);
+}
+
+zval *dom_element_class_list_zval(dom_object *obj)
+{
+	return dom_get_prop_checked_offset(obj, 1, "classList");
 }
 
 /* {{{ classList	TokenList

ext/dom/html_collection.c

@@ -50,12 +50,23 @@ static dom_named_item dom_html_collection_named_item(zend_string *key, zend_obje
 		zend_long cur = 0;
 		zend_long next = cur; /* not +1, otherwise we skip the first candidate */
 		xmlNodePtr candidate = basep->children;
+		bool iterate_tag_name = objmap->handler == &php_dom_obj_map_by_tag_name;
 		while (candidate != NULL) {
-			candidate = dom_get_elements_by_tag_name_ns_raw(basep, candidate, objmap->ns, objmap->local, objmap->local_lower, &cur, next);
-			if (candidate == NULL) {
-				break;
+			if (iterate_tag_name) {
+				candidate = dom_get_elements_by_tag_name_ns_raw(basep, candidate, objmap->ns, objmap->local, objmap->local_lower, &cur, next);
+				if (candidate == NULL) {
+					break;
+				}
+				next = cur + 1;
+			} else {
+				if (candidate->type != XML_ELEMENT_NODE) {
+					candidate = candidate->next;
+					continue;
+				}
 			}
 
+			ZEND_ASSERT(candidate->type == XML_ELEMENT_NODE);
+
 			xmlAttrPtr attr;
 
 			/* it has an ID which is key; */
@@ -73,7 +84,9 @@ static dom_named_item dom_html_collection_named_item(zend_string *key, zend_obje
 				}
 			}
 
-			next = cur + 1;
+			if (!iterate_tag_name) {
+				candidate = candidate->next;
+			}
 		}
 	}
 
@@ -141,4 +154,23 @@ int dom_html_collection_has_dimension(zend_object *object, zval *member, int che
 	}
 }
 
+HashTable *dom_html_collection_get_gc(zend_object *object, zval **table, int *n)
+{
+	dom_nnodemap_object *objmap = php_dom_obj_from_obj(object)->ptr;
+
+	if (objmap->baseobj) {
+		zend_get_gc_buffer *gc_buffer = zend_get_gc_buffer_create();
+		zend_get_gc_buffer_add_obj(gc_buffer, &objmap->baseobj->std);
+		zend_get_gc_buffer_use(gc_buffer, table, n);
+
+		if (object->properties == NULL && object->ce->default_properties_count == 0) {
+			return NULL;
+		} else {
+			return zend_std_get_properties(object);
+		}
+	} else {
+		return zend_std_get_gc(object, table, n);
+	}
+}
+
 #endif

ext/dom/html_collection.h

@@ -19,5 +19,6 @@
 
 zval *dom_html_collection_read_dimension(zend_object *object, zval *offset, int type, zval *rv);
 int dom_html_collection_has_dimension(zend_object *object, zval *member, int check_empty);
+HashTable *dom_html_collection_get_gc(zend_object *object, zval **table, int *n);
 
 #endif

ext/dom/html_document.c

@@ -84,16 +84,7 @@ typedef struct dom_decoding_encoding_ctx {
 /* https://dom.spec.whatwg.org/#dom-document-implementation */
 zend_result dom_modern_document_implementation_read(dom_object *obj, zval *retval)
 {
-	const uint32_t PROP_INDEX = 0;
-
-#if ZEND_DEBUG
-	zend_string *implementation_str = ZSTR_INIT_LITERAL("implementation", false);
-	const zend_property_info *prop_info = zend_get_property_info(dom_abstract_base_document_class_entry, implementation_str, 0);
-	zend_string_release_ex(implementation_str, false);
-	ZEND_ASSERT(OBJ_PROP_TO_NUM(prop_info->offset) == PROP_INDEX);
-#endif
-
-	zval *cached_implementation = OBJ_PROP_NUM(&obj->std, PROP_INDEX);
+	zval *cached_implementation = dom_get_prop_checked_offset(obj, 1, "implementation");
 	if (Z_ISUNDEF_P(cached_implementation)) {
 		php_dom_create_implementation(cached_implementation, true);
 	}

ext/dom/obj_map.c

@@ -28,10 +28,7 @@
 static zend_always_inline void objmap_cache_release_cached_obj(dom_nnodemap_object *objmap)
 {
 	if (objmap->cached_obj) {
-		/* Since the DOM is a tree there can be no cycles. */
-		if (GC_DELREF(&objmap->cached_obj->std) == 0) {
-			zend_objects_store_del(&objmap->cached_obj->std);
-		}
+		OBJ_RELEASE(&objmap->cached_obj->std);
 		objmap->cached_obj = NULL;
 		objmap->cached_obj_index = 0;
 	}
@@ -82,6 +79,20 @@ static zend_long dom_map_get_nodes_length(dom_nnodemap_object *map)
 	return count;
 }
 
+static zend_long dom_map_get_elements_length(dom_nnodemap_object *map)
+{
+	zend_long count = 0;
+	xmlNodePtr nodep = dom_object_get_node(map->baseobj);
+	if (nodep) {
+		for (xmlNodePtr curnode = dom_nodelist_iter_start_first_child(nodep); curnode; curnode = curnode->next) {
+			if (curnode->type == XML_ELEMENT_NODE) {
+				count++;
+			}
+		}
+	}
+	return count;
+}
+
 static zend_long dom_map_get_by_tag_name_length(dom_nnodemap_object *map)
 {
 	xmlNodePtr nodep = dom_object_get_node(map->baseobj);
@@ -223,6 +234,38 @@ static void dom_map_get_nodes_item(dom_nnodemap_object *map, zend_long index, zv
 	}
 }
 
+static void dom_map_get_elements_item(dom_nnodemap_object *map, zend_long index, zval *return_value)
+{
+	xmlNodePtr nodep = dom_object_get_node(map->baseobj);
+	xmlNodePtr itemnode = NULL;
+	if (nodep && index >= 0) {
+		dom_node_idx_pair start_point = dom_obj_map_get_start_point(map, nodep, index);
+		if (start_point.node) {
+			/* Guaranteed to be an element */
+			itemnode = start_point.node;
+		} else {
+			/* Fetch first element child */
+			itemnode = nodep->children;
+			while (itemnode && itemnode->type != XML_ELEMENT_NODE) {
+				itemnode = itemnode->next;
+			}
+		}
+
+		for (; start_point.index > 0 && itemnode; --start_point.index) {
+			do {
+				itemnode = itemnode->next;
+			} while (itemnode && itemnode->type != XML_ELEMENT_NODE);
+		}
+		if (itemnode && itemnode->type != XML_ELEMENT_NODE) {
+			itemnode = NULL;
+		}
+	}
+	dom_ret_node_to_zobj(map, itemnode, return_value);
+	if (itemnode) {
+		dom_map_cache_obj(map, itemnode, index, return_value);
+	}
+}
+
 static void dom_map_get_by_tag_name_item(dom_nnodemap_object *map, zend_long index, zval *return_value)
 {
 	xmlNodePtr nodep = dom_object_get_node(map->baseobj);
@@ -456,6 +499,15 @@ const php_dom_obj_map_handler php_dom_obj_map_notations = {
 	.nameless = false,
 };
 
+const php_dom_obj_map_handler php_dom_obj_map_child_elements = {
+	.length = dom_map_get_elements_length,
+	.get_item = dom_map_get_elements_item,
+	.get_named_item = dom_map_get_named_item_null,
+	.has_named_item = dom_map_has_named_item_null,
+	.use_cache = true,
+	.nameless = true,
+};
+
 const php_dom_obj_map_handler php_dom_obj_map_noop = {
 	.length = dom_map_get_zero_length,
 	.get_item = dom_map_get_null_item,

ext/dom/obj_map.h

@@ -57,6 +57,7 @@ zend_long php_dom_get_nodelist_length(dom_object *obj);
 
 extern const php_dom_obj_map_handler php_dom_obj_map_attributes;
 extern const php_dom_obj_map_handler php_dom_obj_map_by_tag_name;
+extern const php_dom_obj_map_handler php_dom_obj_map_child_elements;
 extern const php_dom_obj_map_handler php_dom_obj_map_child_nodes;
 extern const php_dom_obj_map_handler php_dom_obj_map_nodeset;
 extern const php_dom_obj_map_handler php_dom_obj_map_entities;

ext/dom/parentnode/tree.c

@@ -22,9 +22,34 @@
 #include "php.h"
 #if defined(HAVE_LIBXML) && defined(HAVE_DOM)
 #include "../php_dom.h"
+#include "../obj_map.h"
 #include "../internal_helpers.h"
 #include "../dom_properties.h"
 
+zval *dom_parent_node_children(dom_object *obj)
+{
+	return dom_get_prop_checked_offset(obj, 0, "children");
+}
+
+zend_result dom_parent_node_children_read(dom_object *obj, zval *retval)
+{
+	zval *cached_children = dom_parent_node_children(obj);
+	if (Z_ISUNDEF_P(cached_children)) {
+		object_init_ex(cached_children, dom_html_collection_class_entry);
+		php_dom_create_obj_map(obj, Z_DOMOBJ_P(cached_children), NULL, NULL, NULL, &php_dom_obj_map_child_elements);
+
+		/* Handle cycles for potential TMPVARs (could also be CV but we can't differentiate).
+		 * RC == 2 because of 1 TMPVAR and 1 in HTMLCollection. */
+		if (GC_REFCOUNT(&obj->std) == 2) {
+			gc_possible_root(Z_COUNTED_P(cached_children));
+		}
+	}
+
+	ZVAL_OBJ_COPY(retval, Z_OBJ_P(cached_children));
+
+	return SUCCESS;
+}
+
 /* {{{ firstElementChild DomParentNode
 readonly=yes
 URL: https://www.w3.org/TR/dom/#dom-parentnode-firstelementchild