Querying Document Nodes
Many methods are available to help quickly locate specific Blade constructs within a document. The following demonstrates how we can quickly retrieve the inner content of all echo statements within a document:
1<?php
2
3use Stillat\BladeParser\Nodes\EchoNode;
4use Stillat\BladeParser\Document\Document;
5
6$template = <<<'BLADE'
7 {{ $hello }} {{ $world }}
8BLADE;
9
10
11// Returns " $hello $world "
12Document::fromText($template)
13 ->getEchoes()
14 ->map(fn(EchoNode $e) => $e->innerContent)
15 ->join('');
#Available Methods
The following methods are also available on all NodeCollection
instances, in addition to the following node types:
Stillat\BladeParser\Nodes\Components\ComponentNode
Stillat\BladeParser\Nodes\DirectiveNode
Querying Nodes on Node Instances
Querying nodes on ComponentNode or DirectiveNode instances requires structural analysis. Node queries will be evaluated against each nodes list of children nodes.
If this is your intent, be sure to call the resolveStructures() method on the Document instance first.
#getNodes
Gets the document nodes.
Returns a NodeCollection
instance containing the nodes that represent the parsed template.
1<?php
2
3use Stillat\BladeParser\Nodes\NodeCollection;
4
5public function getNodes(): NodeCollection;
#getEchoes
Returns all Blade echo nodes in the document.
Retrieves all Blade echo statements from the document. Echo nodes are created after parsing the following types of syntax:
Normal echo:
{{ $variable }}
Triple echo:
{{{ $variable }}}
Raw Echo:
{!! $variable !!}
1<?php
2
3use Stillat\BladeParser\Nodes\NodeCollection;
4
5public function getEchoes(): NodeCollection;
Example Use
1<?php
2
3use Stillat\BladeParser\Document\Document;
4
5$template = <<<'BLADE'
6 {{ $variableOne }}
7 {{{ $variableTwo }}}
8 {!! $variableThree !!}
9BLADE;
10
11$doc = Document::fromText($template);
12
13// Returns 3
14$echoCount = $doc->getEchoes()->count();
#getPhpBlocks
Returns all Blade php/endphp blocks within the document.
Retrieves all raw PHP blocks within the source document that were created using Blade's @php
/@endphp
directives.
Raw @php
directives that contain arguments will not be converted to instances of PhpBlockNode
, and will instead become instances of DirectiveNode
.
1<?php
2
3use Stillat\BladeParser\Nodes\NodeCollection;
4
5public function getPhpBlocks(): NodeCollection;
Example Use
1<?php
2
3use Stillat\BladeParser\Document\Document;
4
5$template = <<<'BLADE'
6 @php
7 $count = 1;
8 @endphp
9
10 @php ($count++)
11
12 @php
13 echo "The count is: {$count}";
14 @endphp
15BLADE;
16
17$doc = Document::fromText($template);
18
19// Returns 2
20$phpBlockCount = $doc->getPhpBlocks()->count();
#getPhpTags
Returns all PHP tags within the document.
PHP tags are created after parsing raw PHP regions within the source template. PHP tags will be created whenever the following types of PHP tags are encountered:
PHP Short Echo:
<?= ?>
PHP Open:
<?php ?>
If you are looking to retrieve PHP blocks created using Blade's @php @endphp directives you should refer to thegetPhpBlocks
method instead.
Note: The PHP short echo tags will be parsed even if short tags have been disabled in the PHP configuration.
1<?php
2
3use Stillat\BladeParser\Nodes\NodeCollection;
4
5public function getPhpTags(): NodeCollection;
Example Use
1<?php
2
3use Stillat\BladeParser\Document\Document;
4
5$template = <<<'BLADE'
6 <?php $count = 1; ?>
7
8 The count is: <?= $count ?>
9BLADE;
10
11$doc = Document::fromText($template);
12
13// Returns 2
14$phpTagCount = $doc->getPhpTags()->count();
#getVerbatimBlocks
Returns all verbatim blocks within the document.
Returns all valid @verbatim
/@endverbatim
regions within the source document. Unpaired verbatim directives that could not be converted into a valid VerbatimNode
instance will either become part of the document's literal content (in the case of the @verbatim
directive), or will become a standalone DirectiveNode
(in the case of @endverbatim
).
1<?php
2
3use Stillat\BladeParser\Nodes\NodeCollection;
4
5public function getVerbatimBlocks(): NodeCollection;
Example Use
1<?php
2
3use Stillat\BladeParser\Document\Document;
4
5$template = <<<'BLADE'
6 @verbatim
7 {{ $hello }}
8 @endverbatim
9
10 Content
11
12 @verbatim
13 {{ $world }}
14 @endverbatim
15BLADE;
16
17$doc = Document::fromText($template);
18
19// Returns 2
20$verbatimCount = $doc->getVerbatimBlocks()->count();
#getLiterals
Returns all literal content nodes within the document.
Returns the source template's content that could not be parsed into a valid Blade construct. If a document contains no Blade code, the parser will return a single instance of LiteralNode
.
1<?php
2
3use Stillat\BladeParser\Nodes\NodeCollection;
4
5public function getLiterals(): NodeCollection;
Example Use
1<?php
2
3use Stillat\BladeParser\Document\Document;
4
5$template = <<<'BLADE'
6 One {{ $variable }} Two {{ $variable }}
7
8BLADE;
9
10$doc = Document::fromText($template);
11
12// Returns 3
13$literalCount = $doc->getLiterals()->count();
#getDirectives
Returns all directives within the document.
Returns all directives from the source document. Some directive pairs, such as the @php
/@endphp
and @verbatim
/@endverbatim
pairs will not result in an instance of DirectiveNode
, as they are handled by the parser directly.
1<?php
2
3use Stillat\BladeParser\Nodes\NodeCollection;
4
5public function getDirectives(): NodeCollection;
Example Use
1<?php
2
3use Stillat\BladeParser\Document\Document;
4
5$template = <<<'BLADE'
6 @if ($value)
7
8 @elseif ($anotherValue)
9
10 @else
11
12 @endif
13BLADE;
14
15$doc = Document::fromText($template);
16
17// Returns 4
18$directiveCount = $doc->getDirectives()->count();
#hasAnyDirectives
Tests if the document contains any Blade directives.
1<?php
2
3public function hasAnyDirectives(): bool;
#findDirectiveByName
Attempts to locate the first instance of a directive with the provided name.
Returns the first instance of DirectiveNode
with the provided name. Returns null
if no directive was found.
Argument | Description |
---|---|
$name | The directive name. |
1<?php
2
3use Stillat\BladeParser\Nodes\DirectiveNode;
4
5public function findDirectiveByName(
6 string $name
7): DirectiveNode;
Example Use
1<?php
2
3use Stillat\BladeParser\Document\Document;
4
5$template = <<<'BLADE'
6 @if ($something)
7 @include ('another/file')
8 @endif
9BLADE;
10
11$doc = Document::fromText($template);
12
13// Returns 'another/file'
14$include = $doc->findDirectiveByName('include')->arguments->getStringValue();
#findDirectivesByName
Returns all directives with the provided name in the source document.
Argument | Description |
---|---|
$name | The directive name to search |
1<?php
2
3use Stillat\BladeParser\Nodes\NodeCollection;
4
5public function findDirectivesByName(
6 string $name
7): NodeCollection;
Example Use
1<?php
2
3use Stillat\BladeParser\Document\Document;
4
5$template = <<<'BLADE'
6 @include ('file/one') @if ($something) @endif
7 @include ('file/two')
8 @include
9BLADE;
10
11$doc = Document::fromText($template);
12
13// Returns 3
14$includeCount = $doc->findDirectivesByName('include')->count();
#hasDirective
Tests if the document contains a directive with the provided name.
Argument | Description |
---|---|
$name | The directive name. |
1<?php
2
3public function hasDirective(
4 string $name
5): bool;
Example Use
1<?php
2
3use Stillat\BladeParser\Document\Document;
4
5$template = <<<'BLADE'
6 @extends ('layout')
7
8 @section ('content')
9
10 @endSection
11BLADE;
12
13$doc = Document::fromText($template);
14// Returns true
15$hasExtends = $doc->hasDirective('extends');
16
17// Returns false
18$hasCan = $doc->hasDirective('can');
#getComponents
Returns all component tags within the document.
This method will return all component tags within the document, including closing tags and self-closing tags.
1<?php
2
3use Stillat\BladeParser\Nodes\NodeCollection;
4
5public function getComponents(): NodeCollection;
Example Use
1<?php
2
3use Stillat\BladeParser\Document\Document;
4
5$template = <<<'BLADE'
6 <x-profile :$user />
7
8 <x-alert></x-alert>
9BLADE;
10
11$doc = Document::fromText($template);
12
13// Returns 3
14$componentCount = $doc->getComponents()->count();
#getOpeningComponentTags
Returns all self-closing or opening component tags.
1<?php
2
3use Stillat\BladeParser\Nodes\NodeCollection;
4
5public function getOpeningComponentTags(): NodeCollection;
Example Use
1<?php
2
3use Stillat\BladeParser\Document\Document;
4
5$template = <<<'BLADE'
6 <x-profile :$user />
7
8 <x-alert></x-alert>
9BLADE;
10
11$doc = Document::fromText($template);
12
13// Returns 2
14$componentCount = $doc->getOpeningComponentTags()->count();
#findComponentsByTagName
Finds all components with the provided tag name.
This method will return all component tags that match the provided name, including closing tags.
Argument | Description |
---|---|
$tagName | The tag name to filter on. |
1<?php
2
3use Stillat\BladeParser\Nodes\NodeCollection;
4
5public function findComponentsByTagName(
6 string $tagName
7): NodeCollection;
Example Use
1<?php
2
3use Stillat\BladeParser\Document\Document;
4
5$template = <<<'BLADE'
6 <x-slot:name>
7 <x:slot name="another-name">
8 <x-profile />
9 </x:slot>
10 </x-slot>
11BLADE;
12
13$doc = Document::fromText($template);
14
15// Returns 4
16$componentCount = $doc->findComponentsByTagName('slot')->count();
#findComponentByTagName
Returns the first component tag within the document with the provided name.
Argument | Description |
---|---|
$tagName | The tag name to filter on. |
1<?php
2
3use Stillat\BladeParser\Nodes\Components\ComponentNode;
4
5public function findComponentByTagName(
6 string $tagName
7): ComponentNode;
Example Use
1<?php
2
3use Stillat\BladeParser\Document\Document;
4
5$template = <<<'BLADE'
6 <x-message content="message" />
7 <x-profile />
8BLADE;
9
10$doc = Document::fromText($template);
11$component = $doc->findComponentByTagName('message');
12
13// Returns 'message content="message" '
14$innerContent = $component->innerContent;
#hasAnyComponents
Returns a value indicating if the document has any component tags.
1<?php
2
3public function hasAnyComponents(): bool;
#allOfType
Finds all nodes of the provided type.
Argument | Description |
---|---|
$type | The type to search. |
1<?php
2
3use Stillat\BladeParser\Nodes\NodeCollection;
4
5public function allOfType(
6 string $type
7): NodeCollection;
Example Use
1<?php
2
3use Stillat\BladeParser\Document\Document;
4use Stillat\BladeParser\Nodes\LiteralNode;
5
6$template = <<<'BLADE'
7
8 {{ $hello }}
9
10BLADE;
11
12$doc = Document::fromText($template);
13
14// Returns 2
15$count = $doc->allOfType(LiteralNode::class)->count();
#allNotOfType
Finds all nodes that are not of the provided type.
Argument | Description |
---|---|
$type | The type to search. |
1<?php
2
3use Stillat\BladeParser\Nodes\NodeCollection;
4
5public function allNotOfType(
6 string $type
7): NodeCollection;
Example Use
1<?php
2
3use Stillat\BladeParser\Document\Document;
4use Stillat\BladeParser\Nodes\EchoNode;
5
6$template = <<<'BLADE'
7
8 {{ $hello }}
9
10BLADE;
11
12$doc = Document::fromText($template);
13
14// Returns 2
15$count = $doc->allOfType(EchoNode::class)->count();
#firstOfType
Locates the first instance of the provided node type in the document.
Argument | Description |
---|---|
$type | The node type. |
1<?php
2
3use Stillat\BladeParser\Nodes\AbstractNode;
4
5public function firstOfType(
6 string $type
7): AbstractNode;
Example Use
1<?php
2
3use Stillat\BladeParser\Document\Document;
4use Stillat\BladeParser\Nodes\DirectiveNode;
5
6$template = <<<'BLADE'
7 @if
8 @can
9 @include
10BLADE;
11
12$doc = Document::fromText($template);
13
14// Returns 'if'
15$content = $doc->firstOfType(DirectiveNode::class)->content;
#hasAnyOfType
Tests if the document contains any node of the provided type.
Argument | Description |
---|---|
$type | The desired type. |
1<?php
2
3public function hasAnyOfType(
4 string $type
5): bool;
#lastOfType
Locates the last instance of the provided node type in the document.
Argument | Description |
---|---|
$type | The node type. |
1<?php
2
3use Stillat\BladeParser\Nodes\AbstractNode;
4
5public function lastOfType(
6 string $type
7): AbstractNode;
Example Use
1<?php
2
3use Stillat\BladeParser\Document\Document;
4use Stillat\BladeParser\Nodes\DirectiveNode;
5
6$template = <<<'BLADE'
7 @if
8 @can
9 @include
10BLADE;
11
12$doc = Document::fromText($template);
13
14// Returns 'include'
15$content = $doc->lastOfType(DirectiveNode::class)->content;
#findNodePattern
Locates all instances of the provided node pattern within the document.
Pattern searches exclude instances of LiteralNode
.
Argument | Description |
---|---|
$pattern | The desired pattern. |
1<?php
2
3use Illuminate\Support\Collection;
4
5public function findNodePattern(
6 array $pattern
7): Collection;
Example Use
1<?php
2
3use Stillat\BladeParser\Document\Document;
4use Stillat\BladeParser\Nodes\EchoNode;
5
6$template = <<<'BLADE'
7 {{ $one }} {{ $two }}
8 {{ $three }} @if {{ $four }}
9BLADE;
10
11$doc = Document::fromText($template);
12$pattern = [EchoNode::class, EchoNode::class];
13// Find all node sequences that contain
14// two echo nodes in a row.
15$results = $doc->findNodePattern($pattern);
16// Returns 2
17$resultCount = count($results);
18// Once complete, $text will contain two elements:
19// 0: {{ $one }} {{ $two }}
20// 1: {{ $two }} {{ $three }}
21$text = [];
22
23foreach ($results as $result) {
24 $text[] = $result[0]->content . ' ' . $result[2]->content;
25}
#hasAnyComments
Returns a value indicating if the document has any Blade comments.
1<?php
2
3public function hasAnyComments(): bool;
#findAllNodesStartingOnLine
Retrieves all nodes starting on the target line.
Only the node's starting position is considered.
Argument | Description |
---|---|
$line | The target line. |
1<?php
2
3use Stillat\BladeParser\Nodes\NodeCollection;
4
5public function findAllNodesStartingOnLine(
6 int $line
7): NodeCollection;
#getNodesBefore
Gets all the nodes before the provided node.
Argument | Description |
---|---|
$node | The check node. |
1<?php
2
3use Stillat\BladeParser\Nodes\AbstractNode;
4use Stillat\BladeParser\Nodes\NodeCollection;
5
6public function getNodesBefore(
7 AbstractNode $node
8): NodeCollection;
Example Use
1<?php
2
3use Stillat\BladeParser\Document\Document;
4
5$template = <<<'BLADE'
6 @if {{ $hello }} @endif
7BLADE;
8
9$doc = Document::fromText($template);
10$echo = $doc->getEchoes()->first();
11$before = $doc->getNodesBefore($echo);
12
13// Returns 3
14$nodeCount = $before->count();
#getNodesAfter
Gets all the nodes after the provided node.
Argument | Description |
---|---|
$node | The check node. |
1<?php
2
3use Stillat\BladeParser\Nodes\AbstractNode;
4use Stillat\BladeParser\Nodes\NodeCollection;
5
6public function getNodesAfter(
7 AbstractNode $node
8): NodeCollection;
Example Use
1<?php
2
3use Stillat\BladeParser\Document\Document;
4
5$template = <<<'BLADE'
6 @if {{ $hello }} @endif content {{ $world }}
7BLADE;
8
9$doc = Document::fromText($template);
10$echo = $doc->getEchoes()->first();
11$after = $doc->getNodesAfter($echo);
12
13// Returns 4
14$nodeCount = $after->count();
#getAllParentNodesForNode
Retrieves all parent nodes for the provided node.
Argument | Description |
---|---|
$node | The node. |
1<?php
2
3use Stillat\BladeParser\Nodes\AbstractNode;
4use Stillat\BladeParser\Nodes\NodeCollection;
5
6public function getAllParentNodesForNode(
7 AbstractNode $node
8): NodeCollection;