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);

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;