Parser Nodes Overview

The document parser returns a list of nodes as a result of parsing. There are many different types available, depending on the input template. The most basic node type is the LiteralNode, representing the template's non-Blade parts. If an input document contains no detectable Blade code, the LiteralNode will be the only node in the resulting list.

#The Base Node

All nodes within the library ultimately extend the Stillat\BladeParser\Nodes\BaseNode class. This class provides information that is useful to all node types, such as the following:

• index: A node's index identifies its position within the source document and starts at zero.

• id: Each node is assigned an arbitrary, random identifier when constructed.

• content: Each node stores some content. The exact value of this member will vary depending on the node type.

In addition to the properties above, the base node provides access to each node's position via the $position member. The Position class provides access to the following information:

 1<?php
 2 
 3namespace Stillat\BladeParser\Nodes;
 4 
 5class Position
 6{
 7    /**
 8     * The starting character offset.
 9     *
10     * Starts at zero.
11     *
12     * @var int
13     */
14    public int $startOffset = 0;
15 
16    /**
17     * The starting line number.
18     *
19     * Starts at one.
20     *
21     * @var int|null
22     */
23    public ?int $startLine = null;
24 
25    /**
26     * The starting column number.
27     *
28     * Starts at one.
29     *
30     * @var int|null
31     */
32    public ?int $startColumn = null;
33 
34    /**
35     * The ending character offset.
36     *
37     * Starts at zero.
38     *
39     * @var int
40     */
41    public int $endOffset = 0;
42 
43    /**
44     * The ending line number.
45     *
46     * Starts at one.
47     *
48     * @var int|null
49     */
50    public ?int $endLine = null;
51 
52    /**
53     * The ending column number.
54     *
55     * Starts at one.
56     *
57     * @var int|null
58     */
59    public ?int $endColumn = null;
60 
61      // ...
62}

Depending on the node's origin, it is possible that the position or some of the values contained within the position may be null. An example of when positions may be null are when nodes are manually created and added to a document.

All character and index counting start at zero when interacting with the library. Positional details such as line and column numbers will always begin counting at one. As an example, a position with the character offset of 0 will have line and column numbers of 1.

#Literal Nodes

Instances of Stillat\BladeParser\Nodes\LiteralNode are created to represent the non-Blade content contained within an input document. Literal nodes maintain helpful information, such as the original trailing and leading whitespace discovered while parsing the template.

#Comment Nodes

The parser will emit Stillat\BladeParser\Nodes\CommentNode instances when it successfully parses a Blade comment. If a comment is not completed, the start of the comment will become part of a LiteralNode instance.

The following sample document would produce a CommentNode and a LiteralNode:

1{{-- The comment --}}
2    {{-- This will become part of the literal content.

#Directive Nodes

Instances of Stillat\BladeParser\Nodes\DirectiveNode are created after the parser successfully parses a Blade directive. If the parser can parse arguments following the directive's name, the argument's details will also be within the directive node. Arguments begin with an opening ( and are closed with a ). They may have any number of parenthesis within them as long as they are balanced or contained within strings.

#Echo Nodes

The parser produces instances of Stillat\BladeParser\Nodes\EchoNode after it parses one of the three supported echo statement types. These types are:

• Echo: Produced when parsing {{ $variable }} echo statements

• TripleEcho: Produced when parsing {{{ $variable }}} statements

• RawEcho: Produced when parsing {!! $variable !!} statements

The parser will produce an error if it encounters a valid opening echo sequence without locating its appropriate closing sequence. The parser cannot be configured by users to recognize other echo statement syntax.

#PHP Block Nodes

The parser produces instances of the Stillat\BladeParser\Nodes\PhpBlockNode class after successfully parsing a @php and @endphp directive pair. PhpBlockNode instances are only created when the opening @php directive contains no arguments.

Unpaired @endphp directives will not be paired during structural analysis and will emit no content in any compiled output.

#PHP Tag Nodes

The parser emits Stillat\BladeParser\Nodes\PhpTagNode instances when it parses traditional PHP tags within a Blade template. Each PhpTagNode node is categorized in one of two ways:

• PhpOpenTag: Indicates the PHP tag started with the <?php tag.

• PhpOpenTagWithEcho: Indicates the PHP tag started with the <?= tag.

If either tag type is improperly closed, the tag will implicitly extend to the end of the document.

#Verbatim Nodes

The @verbatim and @endverbatim pair is represented by the Stillat\BladeParser\Nodes\VerbatimNode. This structure type is handled internally within the parser, and the library ignores any improper usage of the @verbatim or @endverbatim directives during structural analysis.

Unclosed @verbatim tags will cause a parser error to be generated, and the @verbatim directive will become part of a LiteralNode instance.