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;