Blade Parser

Blade Parser is a Laravel library designed for parsing, analyzing, and manipulating Blade templates. It consists of five core components:

• Parser: Generates a list of nodes from a Blade template for analysis.
• Documents: An abstraction layer for interacting with a single parsed template.
• Workspaces: An API for managing and working with multiple parsed templates simultaneously.
• Compiler: A configurable Blade compiler implementation that supports precompilers, extensions, and third-party packages.
• Validator: An extensible system for detecting issues in Blade documents (e.g., unpaired conditions or invalid component parameter spacing).

You can quickly parse a Blade template string into a Document object using the Document::fromText() method. Once parsed, the Document instance allows you to query the template structure, such as retrieving or finding specific components.

<?php
 
use Stillatlade-parser\Document\Document;
 
$template = <<<'BLADE'
    Hello, {{ $world }}
BLADE;
 
$document = Document::fromText($template);

The Workspace class is used to manage and interact with multiple parsed Blade templates simultaneously. It allows you to discover files in directories, add individual files, and perform operations across all documents in the workspace (such as compilation or validation).

use Stillat\BladeParser\Workspaces\Workspace;

$workspace = new Workspace();

// Add an entire directory of templates
$workspace->addDirectory('/path/to/resources/views');

// Or add specific files
$workspace->addFile('/path/to/resources/views/welcome.blade.php');

// Access the parsed documents
$documents = $workspace->getDocuments();

After parsing a template into a Document, you can use the following methods to interact with component tags:

• getComponents(): Returns all component tags found in the template.
• findComponentsByTagName('name'): Returns only the components that match the specified tag name.

// Get all components
$document->getComponents()->each(fn($node) => ...);

// Find specific components by tag name
$document->findComponentsByTagName('alert')->each(fn($node) => ...);

Blade Parser includes an Artisan command blade:validate to check all Blade templates in your project for errors.

Setup

Before running the command, you must publish the configuration files:

php artisan vendor:publish --tag=blade

Usage

Run the validation against your project using:

php artisan blade:validate

If validation issues are found, they will be output directly to your terminal.

You can control how Blade's {{ }} syntax is compiled into PHP using setEchoFormat(string $format).

Convenience methods include:

• withDoubleEncoding(): Sets the format to e(%s, true) to double encode entities.
• withoutDoubleEncoding(): Sets the format to e(%s, false) to prevent double encoding.

You can extend the compiler's functionality by registering a callback via extend(). This callback is invoked during the compilation process for text segments. This is useful for adding custom syntax support or modifying how certain parts of the template are processed.

The callback receives the string value to compile and the Compiler instance itself.

$compiler->extend(function (string $value, Compiler $compiler) {
    // Modify the template string before it is fully compiled
    return str_replace('{{ custom_var }}', '{{ $real_var }}', $value);
});

Call cleanUp() to perform cleanup actions on the workspace, such as removing any temporary or compiled files generated during the parsing or compilation process.

$workspace->cleanUp();

When working with an HtmlFragment, you can access its attributes (parameters) using the following methods:

• hasParameter(string $name): Returns true if the fragment contains a parameter with the specified name.
• getParameter(string $name): Returns the FragmentParameter object associated with the given name, or null if it does not exist.

You can get a string representation of the document (effectively re-serializing the nodes) using:

• toString(): Returns a string representation by traversing all nodes and calling their toString() methods.
• (string) $document: The magic __toString() method performs the same action as toString().

$templateString = $document->toString();
// OR
$templateString = (string) $document;

When working with structural directives (like @if...@endif), DirectiveNode provides methods to navigate the relationship between opening and closing tags.

Navigation Methods

• getRootOpeningDirective(): For a closing directive, returns the furthest opening directive in the chain (e.g., for an @endif in a nested structure, it returns the original @if).
• getFinalClosingDirective(): For an opening directive, returns the furthest closing directive in the chain (e.g., for an @if, it returns the final @endif).
• getChainedClosingDirectives(): Returns a Collection of all DirectiveNode objects in the chain of closing directives.