Swapped the Node's constructor parameters

children links are (arguably) more important than the parent link

src/Node.php

@@ -10,27 +10,28 @@
 use JsonSerializable;
 
 /**
- * Basic data node implementation.
+ * Flexible data node implementation.
+ *
+ * Note: Iterating over a node will iterate over the whole subtree in pre-order DFS.
  *
  * @author Andrej Rypak <[email protected]>
  */
 class Node implements TreeNodeContract, DataNodeContract, MovableNodeContract, IteratorAggregate, JsonSerializable
 {
+    /**
+     * Create a data node.
+     *
+     * Note that passing children or parent here does NOT make a link the other way around. Use the Tree utility for that.
+     * @see Tree::link()
+     * @see Tree::linkChildren()
+     */
     public function __construct(
         protected mixed $data,
-        protected ?TreeNodeContract $parent = null,
         protected array $children = [],
+        protected ?TreeNodeContract $parent = null,
     ) {
     }
 
-    /**
-     * Get the node's parent, if any.
-     */
-    public function parent(): ?TreeNodeContract
-    {
-        return $this->parent;
-    }
-
     /**
      * Get the node's children.
      *
@@ -41,6 +42,14 @@ public function children(): array
         return $this->children;
     }
 
+    /**
+     * Get the node's parent, if any.
+     */
+    public function parent(): ?TreeNodeContract
+    {
+        return $this->parent;
+    }
+
     /**
      * Discover whether the given node is one of this node's children (or the given key points to one of them).
      */

src/TreeNodeContract.php

@@ -11,11 +11,6 @@
  */
 interface TreeNodeContract
 {
-    /**
-     * Get the node's parent, if any.
-     */
-    public function parent(): ?TreeNodeContract;
-
     /**
      * Get the node's children.
      *
@@ -25,6 +20,11 @@ public function parent(): ?TreeNodeContract;
      */
     public function children(): iterable;
 
+    /**
+     * Get the node's parent, if any.
+     */
+    public function parent(): ?TreeNodeContract;
+
     /**
      * Discover whether the given node is one of this node's children (or the given key points to one of them).
      */