Blade Documents
The Documents API is the simplest way to begin parsing and analyzing individual Blade templates and provides a cohesive API that combines many of the library's unique features.
Documents are constructed from the nodes created by the document parser and a few other details. The best way to create a new document instance is to use the fromText
static method:
1<?php
2
3use Stillat\BladeParser\Document\Document;
4
5$template = <<<'BLADE'
6 Hello, {{ $world }}
7BLADE;
8
9$document = Document::fromText($template);
Document Static API
An important thing to note about the Document static API is that internally it will use the Laravel service container to resolve its dependencies. It does this through a DocumentFactory, the behavior of which can be changed by library users.
For more details, see the implementation at Stillat\BladeParser\Document\DocumentFactory
.
Once we have a document instance, we can begin working with it. For instance, if we wanted to retrieve the underlying parser nodes, we can call the getNodes
method:
1<?php
2
3use Stillat\BladeParser\Document\Document;
4use Stillat\BladeParser\Nodes\AbstractNode;
5
6$template = <<<'BLADE'
7 Hello, {{ $world }}
8BLADE;
9
10$document = Document::fromText($template);
11
12/** @var AbstractNode $node */
13foreach ($document->getNodes() as $node) {
14 // Do something with the node.
15}
#Available Methods
The document class provides a wide variety of methods that we can use to help make decisions about a Blade template.
#setDirectiveNames
Sets the document's directive names.
The directive names supplied to this method should match those that were used when initially parsing the input template. These directive names will be used when performing structural analysis. If you are using the Blade::fromText($template)
static API, this is managed for you.
Argument | Description |
---|---|
$directives | The directive names. |
1<?php
2
3use Stillat\BladeParser\Document\Document;
4
5public function setDirectiveNames(
6 array $directives
7): Document;
#setFilePath
Sets the document's file path.
Document file paths are optional for most use cases, but can be used by other features such as Workspaces or some validators.
Argument | Description |
---|---|
$path | The file path. |
1<?php
2
3use Stillat\BladeParser\Document\Document;
4
5public function setFilePath(
6 ?string $path
7): Document;
#getFilePath
Gets the document's file path.
1<?php
2
3public function getFilePath(): string;
#getDirectiveNames
Gets the directive names.
1<?php
2
3public function getDirectiveNames(): array;
#releaseNodesFromDocument
Removes the document instance from all attached nodes.
Calling this method will remove the document instance from all nodes that currently belong to this document. This can be useful if you simply want lightweight instances and do not necessarily care about the document instance.
Additionally, this method may be called internally as a result of removing or modifying the node list.
1<?php
2
3public function releaseNodesFromDocument(): void;
#setNodes
Sets the document nodes.
Sets the nodes that represent the parsed template, as well as the original document text. The original document text will be used with other features, like text extraction.
Argument | Description |
---|---|
$nodes | The nodes. |
$nodeText | The original document text. |
1<?php
2
3use Stillat\BladeParser\Document\Document;
4
5public function setNodes(array $nodes,
6 string $nodeText): Document;
#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;
#getNodeArray
Gets the document nodes as a normal array.
Returns a PHP array containing the nodes that represent the parsed template. The nodes returned by this call are the same as those from the getNodes
method call.
1<?php
2
3public function getNodeArray(): array;
#getRootNodes
Gets the root document nodes.
Returns a NodeCollection
instance containing all nodes that do not have a parent node. Invoking this method will trigger structural analysis.
1<?php
2
3use Stillat\BladeParser\Nodes\NodeCollection;
4
5public function getRootNodes(): NodeCollection;
#fromText
Constructs a new Document instance from the provided document text.
The Document instance returned from this method is created by invoking DocumentFactory::makeDocument()
.
Argument | Description |
---|---|
$document | The template content. |
$filePath | An optional file path. |
$customComponentTags | A list of custom component tag names. |
1<?php
2
3use Stillat\BladeParser\Document\Document;
4
5public function fromText(string $document,
6 ?string $filePath = null,
7 array $customComponentTags = []): Document;
#toString
Returns a string representation of the document.
This method will traverse every node in the document and call its corresponding toString()
method. Any modifications made to the document's node will be represented in the results of this method call.
1<?php
2
3public function toString(): string;
#removeNode
Removes the provided node instance from the document.
Calling this method will reindex the nodes, but will not trigger structural analysis. If structural analysis has already been performed on the document, calling this method may remove the start or ending node of existing pairs.
Argument | Description |
---|---|
$node | The node to remove. |
1<?php
2
3use Stillat\BladeParser\Document\Document;
4use Stillat\BladeParser\Nodes\AbstractNode;
5
6public function removeNode(
7 AbstractNode $node
8): Document;
Example Use
1<?php
2
3use Stillat\BladeParser\Document\Document;
4
5$template = <<<'BLADE'
6<?php $count = 1; ?>
7
8The count is {{ $count }}.
9BLADE;
10
11$doc = Document::fromText($template);
12// Remove the first <?php tag from the document.
13$doc->removeNode($doc->getPhpTags()->first());
14
15// Convert the document to Blade without the first <?php tag.
16$result = (string) $doc;
#toDocument
Returns a new document instance from the current document.
This method will take into account any changes made to the nodes that represent the current document. The new document created will use the adjusted document text as its source.
1<?php
2
3use Stillat\BladeParser\Document\Document;
4
5public function toDocument(): Document;