Skip to content

Commit a1ccdaa

Browse files
jaapiojaapio
committed
Introduce CompilerContextInterface
The Compiler context is a very important class in our compiler, however extending projects may want to extend the information caried around with the context to add extra information for specific use cases in custom compiler passes. To make this possible I introduced a new interface to be able to wrap the compilercontext and extend the functionality. Changing the interfaces would be a backward compatibility break so we need to introduce this step by step.
1 parent 318b3ef commit a1ccdaa

28 files changed

+122
-73
lines changed

‎packages/guides/src/Compiler/CompilerContext.php‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,18 @@
1919
use phpDocumentor\Guides\Nodes\Node;
2020
use phpDocumentor\Guides\Nodes\ProjectNode;
2121

22-
final class CompilerContext
22+
/**
23+
* Context class used in compiler passes to store the state of the nodes.
24+
*
25+
* The {@see Compiler} is making changes to the nodes in a {@see DocumentNode} as the nodes are immutable cannot
26+
* do this directly. This class helps to modify the nodes in the {@see DocumentNode} by creating a shadow tree.
27+
*
28+
* The class is final and should not be extended, if you need to provide more information to the compiler pass
29+
* you can use the {@see CompilerContextInterface} and decorate this class.
30+
*
31+
* @final
32+
*/
33+
class CompilerContext implements CompilerContextInterface
2334
{
2435
/** @var TreeNode<Node> */
2536
private TreeNode $shadowTree;

‎packages/guides/src/Compiler/CompilerContextInterface.php‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
/**
6+
* This file is part of phpDocumentor.
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*
11+
* @link https://phpdoc.org
12+
*/
13+
14+
namespace phpDocumentor\Guides\Compiler;
15+
16+
use phpDocumentor\Guides\Compiler\ShadowTree\TreeNode;
17+
use phpDocumentor\Guides\Nodes\DocumentNode;
18+
use phpDocumentor\Guides\Nodes\Node;
19+
use phpDocumentor\Guides\Nodes\ProjectNode;
20+
21+
interface CompilerContextInterface
22+
{
23+
public function getProjectNode(): ProjectNode;
24+
25+
public function getDocumentNode(): DocumentNode;
26+
27+
public function withDocumentShadowTree(DocumentNode $documentNode): self;
28+
29+
/** @param TreeNode<Node> $shadowTree */
30+
public function withShadowTree(TreeNode $shadowTree): self;
31+
32+
/** @return TreeNode<Node> */
33+
public function getShadowTree(): TreeNode;
34+
35+
/** @return array<string, string> */
36+
public function getLoggerInformation(): array;
37+
}

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,15 +13,15 @@
1313

1414
namespace phpDocumentor\Guides\Compiler\NodeTransformers;
1515

16-
use phpDocumentor\Guides\Compiler\CompilerContext;
16+
use phpDocumentor\Guides\Compiler\CompilerContextInterface;
1717
use phpDocumentor\Guides\Compiler\NodeTransformer;
1818
use phpDocumentor\Guides\Nodes\Inline\CitationInlineNode;
1919
use phpDocumentor\Guides\Nodes\Node;
2020

2121
/** @implements NodeTransformer<Node> */
2222
final class CitationInlineNodeTransformer implements NodeTransformer
2323
{
24-
public function enterNode(Node $node, CompilerContext $compilerContext): Node
24+
public function enterNode(Node $node, CompilerContextInterface $compilerContext): Node
2525
{
2626
if ($node instanceof CitationInlineNode) {
2727
$internalTarget = $compilerContext->getProjectNode()->getCitationTarget($node->getName());
@@ -31,7 +31,7 @@ public function enterNode(Node $node, CompilerContext $compilerContext): Node
3131
return $node;
3232
}
3333

34-
public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
34+
public function leaveNode(Node $node, CompilerContextInterface $compilerContext): Node|null
3535
{
3636
return $node;
3737
}

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313

1414
namespace phpDocumentor\Guides\Compiler\NodeTransformers;
1515

16-
use phpDocumentor\Guides\Compiler\CompilerContext;
16+
use phpDocumentor\Guides\Compiler\CompilerContextInterface;
1717
use phpDocumentor\Guides\Compiler\NodeTransformer;
1818
use phpDocumentor\Guides\Meta\CitationTarget;
1919
use phpDocumentor\Guides\Nodes\CitationNode;
@@ -22,7 +22,7 @@
2222
/** @implements NodeTransformer<Node> */
2323
final class CitationTargetTransformer implements NodeTransformer
2424
{
25-
public function enterNode(Node $node, CompilerContext $compilerContext): Node
25+
public function enterNode(Node $node, CompilerContextInterface $compilerContext): Node
2626
{
2727
if ($node instanceof CitationNode) {
2828
$compilerContext->getProjectNode()->addCitationTarget(
@@ -37,7 +37,7 @@ public function enterNode(Node $node, CompilerContext $compilerContext): Node
3737
return $node;
3838
}
3939

40-
public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
40+
public function leaveNode(Node $node, CompilerContextInterface $compilerContext): Node|null
4141
{
4242
return $node;
4343
}

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313

1414
namespace phpDocumentor\Guides\Compiler\NodeTransformers;
1515

16-
use phpDocumentor\Guides\Compiler\CompilerContext;
16+
use phpDocumentor\Guides\Compiler\CompilerContextInterface;
1717
use phpDocumentor\Guides\Compiler\NodeTransformer;
1818
use phpDocumentor\Guides\Nodes\ClassNode;
1919
use phpDocumentor\Guides\Nodes\DocumentNode;
@@ -32,7 +32,7 @@ final class ClassNodeTransformer implements NodeTransformer
3232
/** @var string[] */
3333
private array $classes = [];
3434

35-
public function enterNode(Node $node, CompilerContext $compilerContext): Node
35+
public function enterNode(Node $node, CompilerContextInterface $compilerContext): Node
3636
{
3737
if ($node instanceof DocumentNode) {
3838
// unset classes when entering the next document
@@ -52,7 +52,7 @@ public function enterNode(Node $node, CompilerContext $compilerContext): Node
5252
return $node;
5353
}
5454

55-
public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
55+
public function leaveNode(Node $node, CompilerContextInterface $compilerContext): Node|null
5656
{
5757
if ($node instanceof ClassNode) {
5858
//Remove the class node from the tree.

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313

1414
namespace phpDocumentor\Guides\Compiler\NodeTransformers;
1515

16-
use phpDocumentor\Guides\Compiler\CompilerContext;
16+
use phpDocumentor\Guides\Compiler\CompilerContextInterface;
1717
use phpDocumentor\Guides\Compiler\NodeTransformer;
1818
use phpDocumentor\Guides\Meta\InternalTarget;
1919
use phpDocumentor\Guides\Nodes\AnchorNode;
@@ -49,7 +49,7 @@ public function __construct(
4949
$this->documentStack = new SplStack();
5050
}
5151

52-
public function enterNode(Node $node, CompilerContext $compilerContext): Node
52+
public function enterNode(Node $node, CompilerContextInterface $compilerContext): Node
5353
{
5454
if ($node instanceof DocumentNode) {
5555
$this->documentStack->push($node);
@@ -137,7 +137,7 @@ public function enterNode(Node $node, CompilerContext $compilerContext): Node
137137
return $node;
138138
}
139139

140-
public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
140+
public function leaveNode(Node $node, CompilerContextInterface $compilerContext): Node|null
141141
{
142142
if ($node instanceof DocumentNode) {
143143
$this->documentStack->pop();
@@ -157,7 +157,7 @@ public function getPriority(): int
157157
return 5000;
158158
}
159159

160-
private function addLinkTargetToProject(CompilerContext $compilerContext, InternalTarget $internalTarget): void
160+
private function addLinkTargetToProject(CompilerContextInterface $compilerContext, InternalTarget $internalTarget): void
161161
{
162162
if ($compilerContext->getProjectNode()->hasInternalTarget($internalTarget->getAnchor(), $internalTarget->getLinkType())) {
163163
$otherLink = $compilerContext->getProjectNode()->getInternalTarget($internalTarget->getAnchor(), $internalTarget->getLinkType());

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313

1414
namespace phpDocumentor\Guides\Compiler\NodeTransformers;
1515

16-
use phpDocumentor\Guides\Compiler\CompilerContext;
16+
use phpDocumentor\Guides\Compiler\CompilerContextInterface;
1717
use phpDocumentor\Guides\Compiler\NodeTransformer;
1818
use phpDocumentor\Guides\Nodes\DocumentBlockNode;
1919
use phpDocumentor\Guides\Nodes\Menu\TocNode;
@@ -27,12 +27,12 @@
2727
*/
2828
final class DocumentBlockNodeTransformer implements NodeTransformer
2929
{
30-
public function enterNode(Node $node, CompilerContext $compilerContext): Node
30+
public function enterNode(Node $node, CompilerContextInterface $compilerContext): Node
3131
{
3232
return $node;
3333
}
3434

35-
public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
35+
public function leaveNode(Node $node, CompilerContextInterface $compilerContext): Node|null
3636
{
3737
if ($node instanceof DocumentBlockNode) {
3838
$children = [];

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313

1414
namespace phpDocumentor\Guides\Compiler\NodeTransformers;
1515

16-
use phpDocumentor\Guides\Compiler\CompilerContext;
16+
use phpDocumentor\Guides\Compiler\CompilerContextInterface;
1717
use phpDocumentor\Guides\Compiler\NodeTransformer;
1818
use phpDocumentor\Guides\Nodes\DocumentNode;
1919
use phpDocumentor\Guides\Nodes\DocumentTree\DocumentEntryNode;
@@ -29,12 +29,12 @@ public function __construct(
2929
) {
3030
}
3131

32-
public function enterNode(Node $node, CompilerContext $compilerContext): Node
32+
public function enterNode(Node $node, CompilerContextInterface $compilerContext): Node
3333
{
3434
return $node;
3535
}
3636

37-
public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
37+
public function leaveNode(Node $node, CompilerContextInterface $compilerContext): Node|null
3838
{
3939
if (!$node instanceof DocumentNode) {
4040
return $node;

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313

1414
namespace phpDocumentor\Guides\Compiler\NodeTransformers;
1515

16-
use phpDocumentor\Guides\Compiler\CompilerContext;
16+
use phpDocumentor\Guides\Compiler\CompilerContextInterface;
1717
use phpDocumentor\Guides\Compiler\NodeTransformer;
1818
use phpDocumentor\Guides\Meta\FootnoteTarget;
1919
use phpDocumentor\Guides\Nodes\FootnoteNode;
@@ -22,7 +22,7 @@
2222
/** @implements NodeTransformer<Node> */
2323
final class FootNodeNamedTransformer implements NodeTransformer
2424
{
25-
public function enterNode(Node $node, CompilerContext $compilerContext): Node
25+
public function enterNode(Node $node, CompilerContextInterface $compilerContext): Node
2626
{
2727
if ($node instanceof FootnoteNode && $this->supports($node)) {
2828
$number = $compilerContext->getDocumentNode()->addFootnoteTarget(new FootnoteTarget(
@@ -37,7 +37,7 @@ public function enterNode(Node $node, CompilerContext $compilerContext): Node
3737
return $node;
3838
}
3939

40-
public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
40+
public function leaveNode(Node $node, CompilerContextInterface $compilerContext): Node|null
4141
{
4242
return $node;
4343
}

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313

1414
namespace phpDocumentor\Guides\Compiler\NodeTransformers;
1515

16-
use phpDocumentor\Guides\Compiler\CompilerContext;
16+
use phpDocumentor\Guides\Compiler\CompilerContextInterface;
1717
use phpDocumentor\Guides\Compiler\NodeTransformer;
1818
use phpDocumentor\Guides\Meta\FootnoteTarget;
1919
use phpDocumentor\Guides\Nodes\FootnoteNode;
@@ -22,7 +22,7 @@
2222
/** @implements NodeTransformer<Node> */
2323
final class FootNodeNumberedTransformer implements NodeTransformer
2424
{
25-
public function enterNode(Node $node, CompilerContext $compilerContext): Node
25+
public function enterNode(Node $node, CompilerContextInterface $compilerContext): Node
2626
{
2727
if ($node instanceof FootnoteNode && $this->supports($node)) {
2828
$compilerContext->getDocumentNode()->addFootnoteTarget(new FootnoteTarget(
@@ -36,7 +36,7 @@ public function enterNode(Node $node, CompilerContext $compilerContext): Node
3636
return $node;
3737
}
3838

39-
public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
39+
public function leaveNode(Node $node, CompilerContextInterface $compilerContext): Node|null
4040
{
4141
return $node;
4242
}

0 commit comments

Comments
 (0)