From b4d8191469d1bc8147e56b8a173414966a987762 Mon Sep 17 00:00:00 2001
From: Markus Staab <markus.staab@redaxo.de>
Date: Tue, 25 Feb 2025 15:32:58 +0100
Subject: [PATCH] docs

---
 doc/component/FAQ.markdown                         | 14 ++++++++++++++
 .../NodeVisitor/NodeConnectingVisitor.php          |  4 +++-
 .../NodeVisitor/ParentConnectingVisitor.php        |  4 +++-
 3 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/doc/component/FAQ.markdown b/doc/component/FAQ.markdown
index 62c0970c31..4ef1691bb7 100644
--- a/doc/component/FAQ.markdown
+++ b/doc/component/FAQ.markdown
@@ -51,3 +51,17 @@ obtained through `$node->getAttribute('next')`.
 
 `ParentConnectingVisitor` and `NodeConnectingVisitor` should not be used at the same time. The latter
 includes the functionality of the former.
+
+
+How can I limit the impact of cyclic references in the AST?
+-----
+
+NodeConnectingVisitor adds a parent reference, which introduces a cycle. This means that the AST can now only be collected by cycle garbage collector.
+This in turn can lead to performance and/or memory issues. 
+
+To break the cyclic references between AST nodes `NodeConnectingVisitor` supports a boolean `$weakReferences` constructor parameter.
+When set to `true`, all attributes added by `NodeConnectingVisitor` will be wrapped into a `WeakReference` object.
+
+After enabling this parameter, the parent node can be obtained through `$node->getAttribute('weak_parent')`,
+the previous node can be obtained through `$node->getAttribute('weak_previous')`, and the next node can be
+obtained through `$node->getAttribute('weak_next')`.
\ No newline at end of file
diff --git a/lib/PhpParser/NodeVisitor/NodeConnectingVisitor.php b/lib/PhpParser/NodeVisitor/NodeConnectingVisitor.php
index fd83e8e84b..70e051e2d9 100644
--- a/lib/PhpParser/NodeVisitor/NodeConnectingVisitor.php
+++ b/lib/PhpParser/NodeVisitor/NodeConnectingVisitor.php
@@ -9,10 +9,12 @@
  * Visitor that connects a child node to its parent node
  * as well as its sibling nodes.
  *
- * On the child node, the parent node can be accessed through
+ * With <code>$weakReferences=false</code> on the child node, the parent node can be accessed through
  * <code>$node->getAttribute('parent')</code>, the previous
  * node can be accessed through <code>$node->getAttribute('previous')</code>,
  * and the next node can be accessed through <code>$node->getAttribute('next')</code>.
+ *
+ * With <code>$weakReferences=true</code> attribute names are prefixed by "weak_", e.g. "weak_parent".
  */
 final class NodeConnectingVisitor extends NodeVisitorAbstract {
     /**
diff --git a/lib/PhpParser/NodeVisitor/ParentConnectingVisitor.php b/lib/PhpParser/NodeVisitor/ParentConnectingVisitor.php
index dc322528b5..abf6e37d2e 100644
--- a/lib/PhpParser/NodeVisitor/ParentConnectingVisitor.php
+++ b/lib/PhpParser/NodeVisitor/ParentConnectingVisitor.php
@@ -11,8 +11,10 @@
 /**
  * Visitor that connects a child node to its parent node.
  *
- * On the child node, the parent node can be accessed through
+ * With <code>$weakReferences=false</code> on the child node, the parent node can be accessed through
  * <code>$node->getAttribute('parent')</code>.
+ *
+ * With <code>$weakReferences=true</code> the attribute name is "weak_parent" instead.
  */
 final class ParentConnectingVisitor extends NodeVisitorAbstract {
     /**