Extendable compiler context

composer.json

@@ -36,6 +36,7 @@
         "php": "^8.1",
         "ext-json": "*",
         "ext-mbstring": "*",
+        "doctrine/deprecations": "^1.1",
         "phpdocumentor/guides": "^2.0@dev || ^1.0",
         "phpdocumentor/guides-cli": "^2.0@dev || ^1.0",
         "phpdocumentor/guides-code": "^2.0@dev || ^1.0",

packages/guides/composer.json

@@ -24,6 +24,7 @@
         "php": "^8.1",
         "ext-json": "*",
         "ext-zlib": "*",
+        "doctrine/deprecations": "^1.0",
         "league/flysystem": "^1.1",
         "league/tactician": "^1.1",
         "league/uri": "^7.4.1",

packages/guides/src/Compiler/CompilerContext.php

@@ -13,20 +13,41 @@
 
 namespace phpDocumentor\Guides\Compiler;
 
+use Doctrine\Deprecations\Deprecation;
 use Exception;
 use phpDocumentor\Guides\Compiler\ShadowTree\TreeNode;
 use phpDocumentor\Guides\Nodes\DocumentNode;
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\Nodes\ProjectNode;
 
-final class CompilerContext
+/**
+ * Context class used in compiler passes to store the state of the nodes.
+ *
+ * The {@see Compiler} is making changes to the nodes in a {@see DocumentNode} as the nodes are immutable cannot
+ * do this directly. This class helps to modify the nodes in the {@see DocumentNode} by creating a shadow tree.
+ *
+ * The class is final and should not be extended, if you need to provide more information to the compiler pass
+ * you can use the {@see CompilerContextInterface} and decorate this class.
+ *
+ * @final
+ */
+class CompilerContext implements CompilerContextInterface
 {
     /** @var TreeNode<Node> */
     private TreeNode $shadowTree;
 
     public function __construct(
         private readonly ProjectNode $projectNode,
     ) {
+        if (self::class === static::class) {
+            return;
+        }
+
+        Deprecation::trigger(
+            'phpdocumentor/guides',
+            'https://github.com/phpDocumentor/guides/issues/971',
+            'Extending CompilerContext is deprecated, please use the CompilerContextInterface instead.',
+        );
     }
 
     public function getProjectNode(): ProjectNode

packages/guides/src/Compiler/CompilerContextInterface.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @link https://phpdoc.org
+ */
+
+namespace phpDocumentor\Guides\Compiler;
+
+use phpDocumentor\Guides\Compiler\ShadowTree\TreeNode;
+use phpDocumentor\Guides\Nodes\DocumentNode;
+use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\Nodes\ProjectNode;
+
+interface CompilerContextInterface
+{
+    public function getProjectNode(): ProjectNode;
+
+    public function getDocumentNode(): DocumentNode;
+
+    public function withDocumentShadowTree(DocumentNode $documentNode): self;
+
+    /** @param TreeNode<Node> $shadowTree */
+    public function withShadowTree(TreeNode $shadowTree): self;
+
+    /** @return TreeNode<Node> */
+    public function getShadowTree(): TreeNode;
+
+    /** @return array<string, string> */
+    public function getLoggerInformation(): array;
+}

packages/guides/src/Compiler/NodeTransformers/CitationInlineNodeTransformer.php

@@ -13,15 +13,15 @@
 
 namespace phpDocumentor\Guides\Compiler\NodeTransformers;
 
-use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Compiler\CompilerContextInterface;
 use phpDocumentor\Guides\Compiler\NodeTransformer;
 use phpDocumentor\Guides\Nodes\Inline\CitationInlineNode;
 use phpDocumentor\Guides\Nodes\Node;
 
 /** @implements NodeTransformer<Node> */
 final class CitationInlineNodeTransformer implements NodeTransformer
 {
-    public function enterNode(Node $node, CompilerContext $compilerContext): Node
+    public function enterNode(Node $node, CompilerContextInterface $compilerContext): Node
     {
         if ($node instanceof CitationInlineNode) {
             $internalTarget = $compilerContext->getProjectNode()->getCitationTarget($node->getName());
@@ -31,7 +31,7 @@ public function enterNode(Node $node, CompilerContext $compilerContext): Node
         return $node;
     }
 
-    public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
+    public function leaveNode(Node $node, CompilerContextInterface $compilerContext): Node|null
     {
         return $node;
     }

packages/guides/src/Compiler/NodeTransformers/CitationTargetTransformer.php

@@ -13,7 +13,7 @@
 
 namespace phpDocumentor\Guides\Compiler\NodeTransformers;
 
-use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Compiler\CompilerContextInterface;
 use phpDocumentor\Guides\Compiler\NodeTransformer;
 use phpDocumentor\Guides\Meta\CitationTarget;
 use phpDocumentor\Guides\Nodes\CitationNode;
@@ -22,7 +22,7 @@
 /** @implements NodeTransformer<Node> */
 final class CitationTargetTransformer implements NodeTransformer
 {
-    public function enterNode(Node $node, CompilerContext $compilerContext): Node
+    public function enterNode(Node $node, CompilerContextInterface $compilerContext): Node
     {
         if ($node instanceof CitationNode) {
             $compilerContext->getProjectNode()->addCitationTarget(
@@ -37,7 +37,7 @@ public function enterNode(Node $node, CompilerContext $compilerContext): Node
         return $node;
     }
 
-    public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
+    public function leaveNode(Node $node, CompilerContextInterface $compilerContext): Node|null
     {
         return $node;
     }

packages/guides/src/Compiler/NodeTransformers/ClassNodeTransformer.php

@@ -13,7 +13,7 @@
 
 namespace phpDocumentor\Guides\Compiler\NodeTransformers;
 
-use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Compiler\CompilerContextInterface;
 use phpDocumentor\Guides\Compiler\NodeTransformer;
 use phpDocumentor\Guides\Nodes\ClassNode;
 use phpDocumentor\Guides\Nodes\DocumentNode;
@@ -32,7 +32,7 @@ final class ClassNodeTransformer implements NodeTransformer
     /** @var string[] */
     private array $classes = [];
 
-    public function enterNode(Node $node, CompilerContext $compilerContext): Node
+    public function enterNode(Node $node, CompilerContextInterface $compilerContext): Node
     {
         if ($node instanceof DocumentNode) {
             // unset classes when entering the next document
@@ -52,7 +52,7 @@ public function enterNode(Node $node, CompilerContext $compilerContext): Node
         return $node;
     }
 
-    public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
+    public function leaveNode(Node $node, CompilerContextInterface $compilerContext): Node|null
     {
         if ($node instanceof ClassNode) {
             //Remove the class node from the tree.

packages/guides/src/Compiler/NodeTransformers/CollectLinkTargetsTransformer.php

@@ -13,7 +13,7 @@
 
 namespace phpDocumentor\Guides\Compiler\NodeTransformers;
 
-use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Compiler\CompilerContextInterface;
 use phpDocumentor\Guides\Compiler\NodeTransformer;
 use phpDocumentor\Guides\Meta\InternalTarget;
 use phpDocumentor\Guides\Nodes\AnchorNode;
@@ -49,7 +49,7 @@ public function __construct(
         $this->documentStack = new SplStack();
     }
 
-    public function enterNode(Node $node, CompilerContext $compilerContext): Node
+    public function enterNode(Node $node, CompilerContextInterface $compilerContext): Node
     {
         if ($node instanceof DocumentNode) {
             $this->documentStack->push($node);
@@ -137,7 +137,7 @@ public function enterNode(Node $node, CompilerContext $compilerContext): Node
         return $node;
     }
 
-    public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
+    public function leaveNode(Node $node, CompilerContextInterface $compilerContext): Node|null
     {
         if ($node instanceof DocumentNode) {
             $this->documentStack->pop();
@@ -157,7 +157,7 @@ public function getPriority(): int
         return 5000;
     }
 
-    private function addLinkTargetToProject(CompilerContext $compilerContext, InternalTarget $internalTarget): void
+    private function addLinkTargetToProject(CompilerContextInterface $compilerContext, InternalTarget $internalTarget): void
     {
         if ($compilerContext->getProjectNode()->hasInternalTarget($internalTarget->getAnchor(), $internalTarget->getLinkType())) {
             $otherLink = $compilerContext->getProjectNode()->getInternalTarget($internalTarget->getAnchor(), $internalTarget->getLinkType());

packages/guides/src/Compiler/NodeTransformers/DocumentBlockNodeTransformer.php

@@ -13,7 +13,7 @@
 
 namespace phpDocumentor\Guides\Compiler\NodeTransformers;
 
-use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Compiler\CompilerContextInterface;
 use phpDocumentor\Guides\Compiler\NodeTransformer;
 use phpDocumentor\Guides\Nodes\DocumentBlockNode;
 use phpDocumentor\Guides\Nodes\Menu\TocNode;
@@ -27,12 +27,12 @@
  */
 final class DocumentBlockNodeTransformer implements NodeTransformer
 {
-    public function enterNode(Node $node, CompilerContext $compilerContext): Node
+    public function enterNode(Node $node, CompilerContextInterface $compilerContext): Node
     {
         return $node;
     }
 
-    public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
+    public function leaveNode(Node $node, CompilerContextInterface $compilerContext): Node|null
     {
         if ($node instanceof DocumentBlockNode) {
             $children = [];

packages/guides/src/Compiler/NodeTransformers/DocumentEntryRegistrationTransformer.php

@@ -13,7 +13,7 @@
 
 namespace phpDocumentor\Guides\Compiler\NodeTransformers;
 
-use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Compiler\CompilerContextInterface;
 use phpDocumentor\Guides\Compiler\NodeTransformer;
 use phpDocumentor\Guides\Nodes\DocumentNode;
 use phpDocumentor\Guides\Nodes\DocumentTree\DocumentEntryNode;
@@ -29,12 +29,12 @@ public function __construct(
     ) {
     }
 
-    public function enterNode(Node $node, CompilerContext $compilerContext): Node
+    public function enterNode(Node $node, CompilerContextInterface $compilerContext): Node
     {
         return $node;
     }
 
-    public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
+    public function leaveNode(Node $node, CompilerContextInterface $compilerContext): Node|null
     {
         if (!$node instanceof DocumentNode) {
             return $node;

packages/guides/src/Compiler/NodeTransformers/FootNodeNamedTransformer.php

@@ -13,7 +13,7 @@
 
 namespace phpDocumentor\Guides\Compiler\NodeTransformers;
 
-use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Compiler\CompilerContextInterface;
 use phpDocumentor\Guides\Compiler\NodeTransformer;
 use phpDocumentor\Guides\Meta\FootnoteTarget;
 use phpDocumentor\Guides\Nodes\FootnoteNode;
@@ -22,7 +22,7 @@
 /** @implements NodeTransformer<Node> */
 final class FootNodeNamedTransformer implements NodeTransformer
 {
-    public function enterNode(Node $node, CompilerContext $compilerContext): Node
+    public function enterNode(Node $node, CompilerContextInterface $compilerContext): Node
     {
         if ($node instanceof FootnoteNode && $this->supports($node)) {
             $number = $compilerContext->getDocumentNode()->addFootnoteTarget(new FootnoteTarget(
@@ -37,7 +37,7 @@ public function enterNode(Node $node, CompilerContext $compilerContext): Node
         return $node;
     }
 
-    public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
+    public function leaveNode(Node $node, CompilerContextInterface $compilerContext): Node|null
     {
         return $node;
     }

packages/guides/src/Compiler/NodeTransformers/FootNodeNumberedTransformer.php

@@ -13,7 +13,7 @@
 
 namespace phpDocumentor\Guides\Compiler\NodeTransformers;
 
-use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Compiler\CompilerContextInterface;
 use phpDocumentor\Guides\Compiler\NodeTransformer;
 use phpDocumentor\Guides\Meta\FootnoteTarget;
 use phpDocumentor\Guides\Nodes\FootnoteNode;
@@ -22,7 +22,7 @@
 /** @implements NodeTransformer<Node> */
 final class FootNodeNumberedTransformer implements NodeTransformer
 {
-    public function enterNode(Node $node, CompilerContext $compilerContext): Node
+    public function enterNode(Node $node, CompilerContextInterface $compilerContext): Node
     {
         if ($node instanceof FootnoteNode && $this->supports($node)) {
             $compilerContext->getDocumentNode()->addFootnoteTarget(new FootnoteTarget(
@@ -36,7 +36,7 @@ public function enterNode(Node $node, CompilerContext $compilerContext): Node
         return $node;
     }
 
-    public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
+    public function leaveNode(Node $node, CompilerContextInterface $compilerContext): Node|null
     {
         return $node;
     }

packages/guides/src/Compiler/NodeTransformers/FootnoteInlineNodeTransformer.php

@@ -13,15 +13,15 @@
 
 namespace phpDocumentor\Guides\Compiler\NodeTransformers;
 
-use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Compiler\CompilerContextInterface;
 use phpDocumentor\Guides\Compiler\NodeTransformer;
 use phpDocumentor\Guides\Nodes\Inline\FootnoteInlineNode;
 use phpDocumentor\Guides\Nodes\Node;
 
 /** @implements NodeTransformer<Node> */
 final class FootnoteInlineNodeTransformer implements NodeTransformer
 {
-    public function enterNode(Node $node, CompilerContext $compilerContext): Node
+    public function enterNode(Node $node, CompilerContextInterface $compilerContext): Node
     {
         if ($node instanceof FootnoteInlineNode) {
             if ($node->getNumber() > 0) {
@@ -38,7 +38,7 @@ public function enterNode(Node $node, CompilerContext $compilerContext): Node
         return $node;
     }
 
-    public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
+    public function leaveNode(Node $node, CompilerContextInterface $compilerContext): Node|null
     {
         return $node;
     }

packages/guides/src/Compiler/NodeTransformers/ListNodeTransformer.php

@@ -13,7 +13,7 @@
 
 namespace phpDocumentor\Guides\Compiler\NodeTransformers;
 
-use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Compiler\CompilerContextInterface;
 use phpDocumentor\Guides\Compiler\NodeTransformer;
 use phpDocumentor\Guides\Nodes\ListItemNode;
 use phpDocumentor\Guides\Nodes\ListNode;
@@ -30,12 +30,12 @@ public function __construct(
     ) {
     }
 
-    public function enterNode(Node $node, CompilerContext $compilerContext): Node
+    public function enterNode(Node $node, CompilerContextInterface $compilerContext): Node
     {
         return $node;
     }
 
-    public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
+    public function leaveNode(Node $node, CompilerContextInterface $compilerContext): Node|null
     {
         assert($node instanceof ListNode);
         foreach ($node->getChildren() as $listItemNode) {

packages/guides/src/Compiler/NodeTransformers/MenuNodeTransformers/AbstractMenuEntryNodeTransformer.php

@@ -14,7 +14,7 @@
 namespace phpDocumentor\Guides\Compiler\NodeTransformers\MenuNodeTransformers;
 
 use Exception;
-use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Compiler\CompilerContextInterface;
 use phpDocumentor\Guides\Compiler\NodeTransformer;
 use phpDocumentor\Guides\Nodes\Menu\MenuEntryNode;
 use phpDocumentor\Guides\Nodes\Menu\MenuNode;
@@ -32,13 +32,13 @@ public function __construct(
     ) {
     }
 
-    final public function enterNode(Node $node, CompilerContext $compilerContext): MenuEntryNode
+    final public function enterNode(Node $node, CompilerContextInterface $compilerContext): MenuEntryNode
     {
         return $node;
     }
 
     /** @param MenuEntryNode $node */
-    final public function leaveNode(Node $node, CompilerContext $compilerContext): MenuEntryNode|null
+    final public function leaveNode(Node $node, CompilerContextInterface $compilerContext): MenuEntryNode|null
     {
         assert($node instanceof MenuEntryNode);
         $currentMenuShaddow = $compilerContext->getShadowTree()->getParent();
@@ -70,5 +70,5 @@ final public function leaveNode(Node $node, CompilerContext $compilerContext): M
     }
 
     /** @return list<MenuEntryNode> */
-    abstract protected function handleMenuEntry(MenuNode $currentMenu, MenuEntryNode $entryNode, CompilerContext $compilerContext): array;
+    abstract protected function handleMenuEntry(MenuNode $currentMenu, MenuEntryNode $entryNode, CompilerContextInterface $compilerContext): array;
 }