Validating Blade

The Blade Parser library provides a simple yet powerful validation system. The validation system can be used to validate individual nodes within a document or entire document instances at once.

#Overview

This documentation page is intended for those looking to implement their own Blade validators, or are curious to learn more about the system. If you are interested in running existing validators against your Laravel project, consider reading the The Validate Command article instead.

The validation system operates by first parsing the nodes of an input template and then running a series of checks on the resulting nodes. These node checks are created by extending the Stillat\BladeParser\Validation\AbstractNodeValidator class.

For example, the following sample is the implementation of the core DirectiveSpacingValidator validator:

 1<?php
 2 
 3namespace Stillat\BladeParser\Validation\Validators;
 4 
 5use Stillat\BladeParser\Nodes\AbstractNode;
 6use Stillat\BladeParser\Nodes\DirectiveNode;
 7use Stillat\BladeParser\Validation\AbstractNodeValidator;
 8use Stillat\BladeParser\Validation\ValidationResult;
 9use Stillat\BladeParser\Validation\Validators\Concerns\CanIgnoreDirectives;
10 
11class DirectiveSpacingValidator extends AbstractNodeValidator
12{
13    use CanIgnoreDirectives;
14 
15    public function validate(AbstractNode $node): ?ValidationResult
16    {
17        if (! $node instanceof DirectiveNode || $this->shouldIgnore($node)) {
18            return null;
19        }
20 
21        if ($node->hasPreviousNode() && $node->hasWhitespaceOnLeft() == 0) {
22            return $this->makeValidationResult($node, "Missing space before [@{$node->content}]");
23        }
24 
25        if ($node->hasNextNode() && $node->hasWhitespaceOnRight() == 0) {
26            return $this->makeValidationResult($node, "Missing space after [@{$node->content}]");
27        }
28 
29        return null;
30    }
31}

Each node validator will receive an AbstractNode instance. It is up to each validator to analyze the node and decide whether it should return a validation result. The validator implementation should return null if a node passes all validation checks. Multiple validation results can be returned as an array.

Node validators are added to a BladeValidator instance using one of the following methods:

addValidator(AbstractNodeValidator $validator)
addValidators(AbstractNodeValidator[] $validators)

Alternatively, validators may extend the Stillat\BladeParser\Validation\AbstractDocumentValidator class to implement a validator that should evaluate an entire Document. These validator implementations will receive a single Document instance as their only argument.

For example, the following is how the core InvalidPhpDocumentValidator validator was implemented:

 1<?php
 2 
 3namespace Stillat\BladeParser\Validation\Validators\Documents;
 4 
 5use Stillat\BladeParser\Document\Document;
 6use Stillat\BladeParser\Validation\AbstractDocumentValidator;
 7use Stillat\BladeParser\Validation\PhpSyntaxValidator;
 8use Stillat\BladeParser\Validation\ValidationResult;
 9 
10class InvalidPhpDocumentValidator extends AbstractDocumentValidator
11{
12    /**
13     * Attempts to detect any invalid PHP syntax in the provided document.
14     *
15     * @param  Document  $document The document instance.
16     * @return ValidationResult|null
17     */
18    public function validate(Document $document): ?ValidationResult
19    {
20        $syntaxValidator = new PhpSyntaxValidator();
21        $result = $syntaxValidator->checkDocument($document);
22        if (! $result->detectedErrors) {
23            return null;
24        }
25 
26        return $result->toValidationResult();
27    }
28}

Document validators may be registered with one of the following methods:

addDocumentValidator(AbstractDocumentValidator $validator)
addDocumentValidators(AbstractDocumentValidator[] $validators)

#Registering Custom Validators

It is not recommended to place custom validator implementations within the blade.validation.core_validators array. The core validators are initialized as singleton objects and have specific requirements for configuration.

Instead, suppose you want to ensure custom validator implementations are available on every BladeValidator instance created. In that case, you can use the resolving method provided by Laravel's service container:

 1<?php
 2 
 3namespace App;
 4 
 5use Illuminate\Support\ServiceProvider as BaseServiceProvider;
 6use Stillat\BladeParser\Validation\BladeValidator;
 7 
 8class ServiceProvider extends BaseServiceProvider
 9{
10    public function boot()
11    {
12        $this->app->resolving(BladeValidator::class, function (BladeValidator $validator) {
13            // Add your validator implementations here.
14        });
15    }
16}

Adding custom validators in this way provides the most flexibility for custom configuration and lifecycle management.

#Available Methods

#getResults

Returns a collection of node validation results.

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

#getDocumentResults

Returns a collection of document validation results.

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

#withCoreValidators

Adds all the core validator instances to the current BladeValidator instance.

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

#getValidatorCount

Returns the total number of validator instances registered with BladeValidator instance.

1<?php
2 
3public function getValidatorCount(): int;

#getValidators

Returns a collection of all registered validator instances.

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

#getNodeValidators

Returns a collection containing only the registered node validator instances.

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

#getDocumentValidators

Returns a collection containing only the registered document validator instances.

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

#hasValidatorInstance

Tests if the BladeValidator instance contains the provided validator.

Argument	Description
$validator	The validator to check.

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

#hasDocumentValidatorInstance

Tests if the BladeValidator instance contains the provided validator.

Argument	Description
$validator	The validator to check.

1<?php
2 
3use Stillat\BladeParser\Validation\AbstractDocumentValidator;
4 
5public function hasDocumentValidatorInstance(
6    AbstractDocumentValidator $validator
7): bool;

#hasValidatorClass

Tests if the BladeValidator instance contains any validator instance with the provided class name.

Argument	Description
$validatorClass	The class name to check.

1<?php
2 
3public function hasValidatorClass(
4    string $validatorClass
5): bool;

#addValidator

Registers a single node validator instance with the BladeValidator instance.

Argument	Description
$validator	The node validator instance.

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

#addValidators

Adds the validators to validator instance.

Argument	Description
$validators	The validators.

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

#addDocumentValidator

Registers a document validator with the BladeValidator instance.

Argument	Description
$validator	The validator instance.

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

#addDocumentValidators

Registers multiple document validators with the BladeValidator instance.

Argument	Description
$validators	The document validator instances.

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

#removeValidator

Removes a validator instance with the provided validator class name.

Argument	Description
$validatorClass	The validator class name.

1<?php
2 
3use Stillat\BladeParser\Validation\BladeValidator;
4 
5public function removeValidator(
6    string $validatorClass
7): BladeValidator;

#validateNodes

Runs all registered node validators against the provided node list.

Argument	Description
$nodes	The nodes to validate.

1<?php
2 
3use Illuminate\Support\Collection;
4 
5public function validateNodes(
6    array $nodes
7): Collection;

#validateDocument

Runs all registered document validators against the provided document.

This method will not automatically run registered node validators against the document's nodes.

Argument	Description
$document	The document to validate.

1<?php
2 
3use Illuminate\Support\Collection;
4use Stillat\BladeParser\Document\Document;
5 
6public function validateDocument(
7    Document $document
8): Collection;