Validating Documents

The document validation system provides a convenient wrapper around the Blade Parser's validation system. Using the validation system, we can quickly run any number of validators against our input document to catch potential compilation or runtime errors ahead of time.

#Available Methods

#getErrors

Returns the Blade errors.

Returns a Collection instance containing the document's errors. This method will return errors from all sources, such as parser and validation errors.

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

#getValidationErrors

Returns a collection containing the document's validation errors.

Errors added to the document via. the addValidationResult or addValidationError methods will be included in the results.

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

#hasErrors

Tests if any errors are present.

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

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

Example Use

 1<?php
 2 
 3use Stillat\BladeParser\Document\Document;
 4 
 5$template = <<<'BLADE'
 6    Hello, {{ $world
 7BLADE;
 8 
 9$doc = Document::fromText($template);
10 
11// Returns '[BLADE_P001001] Unexpected end of input while parsing echo on line 1'
12$message = $doc->getFirstError()->getErrorMessage();

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

Example Use

 1<?php
 2 
 3use Stillat\BladeParser\Document\Document;
 4 
 5$template = <<<'BLADE'
 6    Hello, {{ $world }}
 7        @verbatim
 8            {{ $hello
 9BLADE;
10 
11$doc = Document::fromText($template);
12 
13// Returns '[BLADE_P003001] Unexpected end of input while parsing verbatim on line 2'
14$message = $doc->getFirstFatalError()->getErrorMessage();

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

Example Use

 1<?php
 2 
 3use Stillat\BladeParser\Document\Document;
 4 
 5$template = <<<'BLADE'
 6    {{ $hello {{-- world --}}
 7BLADE;
 8 
 9$doc = Document::fromText($template);
10 
11// Returns true
12$hasError = $doc->hasErrorOnLine(1, ErrorType::UnexpectedCommentEncountered, ConstructContext::Echo);

#validator

Returns access to an internal BladeValidator instance.

If a validator instance does not already exist, one will be automatically created by calling the ValidatorFactory::makeBladeValidator() method.

1<?php
2 
3use Stillat\BladeParser\Validation\BladeValidator;
4 
5public function validator(): BladeValidator;

#withCoreValidators

Includes the core validators on the internal BladeValidator instance.

If a BladeValidator instance does not already exist on the document, a new one will be created automatically via the ValidatorFactory::makeBladeValidator() factory method.
Under a typical installation environment, this will load the validators that are configured under the config path: blade.validation.core_validators

1<?php
2 
3use Stillat\BladeParser\Document\Document;
4 
5public function withCoreValidators(): Document;

Example Use

 1<?php
 2 
 3use Stillat\BladeParser\Document\Document;
 4 
 5$template = <<<'BLADE'
 6    {{ $hello {{-- world --}}
 7BLADE;
 8 
 9$doc = Document::fromText($template);
10 
11// Returns 19
12$count = $doc->withCoreValidators()->validator()->getValidators()->count();

#withValidator

Adds a validator instance to the internal BladeValidator instance.

Argument	Description
$validator	The validator instance.

1<?php
2 
3use Stillat\BladeParser\Document\Document;
4use Stillat\BladeParser\Validation\AbstractNodeValidator;
5 
6public function withValidator(
7    AbstractNodeValidator $validator
8): Document;

Example Use

 1<?php
 2 
 3use Stillat\BladeParser\Document\Document;
 4 
 5$validator = new class extends AbstractNodeValidator
 6{
 7    public function validate(AbstractNode $node) : ValidationResult|array|null
 8    {
 9        return null;
10    }
11};
12$doc = Document::fromText('');
13// Returns 19
14$beforeCount = $doc->withCoreValidators()->validator()->getValidators()->count();
15$doc->withValidator($validator);
16 
17// Returns 20
18$afterCount = $doc->validator()->getValidators()->count();

#withValidators

Adds a list of validator instances to the internal BladeValidator instance.

Argument	Description
$validators	The validator instances.

1<?php
2 
3use Stillat\BladeParser\Document\Document;
4 
5public function withValidators(
6    array $validators
7): Document;

#validate

Validates the document with the internal BladeValidator instance.

After validation is complete, any produced validation errors will be available through the getErrors() method, as well as the getValidationErrors() method to retrieve only the validation errors.

1<?php
2 
3use Stillat\BladeParser\Document\Document;
4 
5public function validate(): Document;

Example Use

 1<?php
 2 
 3use Stillat\BladeParser\Document\Document;
 4use Stillat\BladeParser\Validation\Validators\InconsistentIndentationLevelValidator;
 5 
 6$template = <<<'BLADE'
 7    @if ($something)
 8 
 9       @endif
10BLADE;
11 
12$doc = Document::fromText($template);
13$doc->withValidator(new InconsistentIndentationLevelValidator());
14$doc->validate();
15 
16// Returns:
17// [BLADE_V011] Inconsistent indentation level of 7 for [@endif]; parent [@if] has a level of 4 on line 3
18$message = $doc->getValidationErrors()->first()->getErrorMessage();