The Document Parser

The Document Parser is responsible for parsing Blade templates. By default, it supports all directives supported by the library's compiler. Any custom directive names need to be registered with the parser instance. It is also possible to disable the parsing of all known core directives.

The following demonstrates one of the simplest ways to use the parser:

 1<?php
 2 
 3use Stillat\BladeParser\Parser\DocumentParser;
 4 
 5$template = <<<'BLADE'
 6@if ($isAwesome)
 7    Laravel is an awesome framework.
 8@endif
 9BLADE;
10 
11$parser = new DocumentParser;
12$nodes = $parser->parse($template);

Once complete, the $nodes array would contain three elements representing the @if directive and its arguments, the final @endif directive, and the literal text that appears between them, including the leading and trailing newline characters.

The parser itself will not throw exceptions when it encounters invalid Blade templates. Instead, it will collect any potentially fatal errors internally, which are retrievable after completed parsing.

#Specifying Custom Directive Names

By default, the document parser does not know any custom directives available within an application. This decision was made to help keep the parser as standalone and reusable as possible. However, it is simple to teach the parser about custom directives:

 1<?php
 2 
 3use Stillat\BladeParser\Parser\DocumentParser;
 4 
 5$parser = new DocumentParser;
 6 
 7// Specify the custom directive names.
 8$parser->setDirectiveNames([
 9    'disk',
10    'elsedisk',
11    'enddisk'
12]);

Alternatively, we can retrieve all custom directives from Laravel's compiler and supply them to our parser instance:

1<?php
2 
3use Illuminate\Support\Facades\Blade;
4use Stillat\BladeParser\Parser\DocumentParser;
5 
6$parser = new DocumentParser;
7 
8// Retrieve all custom directive names from the Laravel compiler.
9$parser->setDirectiveNames(array_keys(Blade::getCustomDirectives()));

We may also register a single directive at a time using the registerCustomDirective method:

1<?php
2 
3use Stillat\BladeParser\Parser\DocumentParser;
4 
5$parser = new DocumentParser;
6$parser->registerCustomDirective('directiveName');

#Disabling Core Directives

Depending on the integration or use case, it may be beneficial to remove support for the core directives and specify only a subset of directives names. We can accomplish this by calling the withoutCoreDirectives method:

 1<?php
 2 
 3use Stillat\BladeParser\Parser\DocumentParser;
 4 
 5$parser = new DocumentParser;
 6 
 7$parser->withoutCoreDirectives()
 8    ->setDirectiveNames([
 9        'custom',
10        'directives',
11        'to',
12        'support',
13    ]);

#Available Methods

#getParsedContent

1<?php
2 
3public function getParsedContent(): string;

#getOriginalContent

1<?php
2 
3public function getOriginalContent(): string;

#setDirectiveNames

Sets the custom directive names.

Argument	Description
$names	The directive names.

1<?php
2 
3use Stillat\BladeParser\Parser\DocumentParser;
4 
5public function setDirectiveNames(
6    array $names
7): DocumentParser;

#getErrors

Retrieves a collection of parser errors.

1<?php
2 
3use Illuminate\Support\Collection;
4 
5public function getErrors(): Collection;

#registerCustomComponentTag

Registers a single custom component tag name.

Argument	Description
$tagName	The component tag name.

1<?php
2 
3use Stillat\BladeParser\Parser\DocumentParser;
4 
5public function registerCustomComponentTag(
6    string $tagName
7): DocumentParser;

#registerCustomComponentTags

Registers multiple custom component tag names.

Argument	Description
$tagNames	The tag names.

1<?php
2 
3use Stillat\BladeParser\Parser\DocumentParser;
4 
5public function registerCustomComponentTags(
6    array $tagNames
7): DocumentParser;

#registerCustomDirective

Registers a single custom directive name.

Argument	Description
$name	The directive name.

1<?php
2 
3public function registerCustomDirective(
4    string $name
5): void;

#withCoreDirectives

1<?php
2 
3use Stillat\BladeParser\Parser\DocumentParser;
4 
5public function withCoreDirectives(): DocumentParser;

#withoutCoreDirectives

Removes support for all core Blade directives.

1<?php
2 
3use Stillat\BladeParser\Parser\DocumentParser;
4 
5public function withoutCoreDirectives(): DocumentParser;

#getDirectiveNames

Retrieves a list of directive names supported by the parser instance.

1<?php
2 
3public function getDirectiveNames(): array;

#hasComponents

Returns a value indicating if any Laravel tag components were parsed.

1<?php
2 
3public function hasComponents(): bool;

#hasCustomComponents

Returns a value indicating if any custom tag components were parsed.

1<?php
2 
3public function hasCustomComponents(): bool;

#getCustomComponentTags

Returns an list of all custom component tag names.

1<?php
2 
3public function getCustomComponentTags(): array;

#hasAnyComponents

Returns a value indicating if any component tags were parsed.

1<?php
2 
3public function hasAnyComponents(): bool;

#parse

Parses the input document and returns an array of nodes.

Argument	Description
$document	The input document.

1<?php
2 
3public function parse(
4    string $document
5): array;

#getNodes

Retrieves the parsed nodes.

1<?php
2 
3public function getNodes(): array;

#getFirstError

Retrieves the first error.

If the error source contains multiple types of errors, such as parser errors and validation errors, all errors will be considered.

1<?php
2 
3use Stillat\BladeParser\Errors\BladeError;
4 
5public function getFirstError(): BladeError;

#getFirstFatalError

Retrieves the first fatal error.

If the error source contains multiple types of errors, such as parser errors and validation errors, all errors will be considered. Fatal errors are considered those that would produce invalid compiled PHP code, regardless of which compiler implementation is used.

1<?php
2 
3use Stillat\BladeParser\Errors\BladeError;
4 
5public function getFirstFatalError(): BladeError;

#hasErrors

Tests if any errors are present.

1<?php
2 
3public function hasErrors(): bool;

#hasFatalErrors

Tests if any fatal errors are present.

1<?php
2 
3public function hasFatalErrors(): bool;

#hasErrorOnLine

Tests if an error matching the provided properties exists on a specific line.

Argument	Description
$line	The line to check.
$type	The error type to check for.
$context	The error context.

1<?php
2 
3use Stillat\BladeParser\Errors\ErrorType;
4 
5public function hasErrorOnLine(int $line,
6                               ErrorType $type,
7                               ConstructContext $context): bool;