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;