class SSTemplateParser extends Parser implements TemplateParser (View source)

This is the parser for the SilverStripe template language. It gets called on a string and uses a php-peg parser to match that string against the language structure, building up the PHP code to execute that structure as it parses

The $result array that is built up as part of the parsing (see thirdparty/php-peg/README.md for more on how parsers build results) has one special member, 'php', which contains the php equivalent of that part of the template tree.

Some match rules generate alternate php, or other variations, so check the per-match documentation too.

Terms used:

Marked: A string or lookup in the template that has been explictly marked as such - lookups by prepending with "$" (like $Foo.Bar), strings by wrapping with single or double quotes ('Foo' or "Foo")

Bare: The opposite of marked. An argument that has to has it's type inferred by usage and 2.4 defaults.

Example of using a bare argument for a loop block: <% loop Foo %>

Block: One of two SS template structures. The special characters "<%" and "%>" are used to wrap the opening and (required or forbidden depending on which block exactly) closing block marks.

Open Block: An SS template block that doesn't wrap any content or have a closing end tag (in fact, a closing end tag is forbidden)

Closed Block: An SS template block that wraps content, and requires a counterpart <% end_blockname %> tag

Angle Bracket: angle brackets "<" and ">" are used to eat whitespace between template elements N: eats white space including newlines (using in legacy _t support)

Methods

__construct(array $closedBlocks = [], array $openBlocks = [])

Allow the injection of new closed & open block callables

construct($matchrule, $name, $arguments = null)

Override the function that constructs the result arrays to also prepare a 'php' item in the array

setClosedBlocks(array $closedBlocks)

Set the closed blocks that the template parser should use

setOpenBlocks(array $openBlocks)

Set the open blocks that the template parser should use

addClosedBlock(string $name, callable $callable)

Add a closed block callable to allow <% name %><% end_name %> syntax

addOpenBlock(string $name, callable $callable)

Add a closed block callable to allow <% name %> syntax

match_Template($stack = array())

No description

Template_STR($res, $sub)

No description

match_Word($stack = array())

No description

match_NamespacedWord($stack = array())

No description

match_Number($stack = array())

No description

match_Value($stack = array())

No description

match_CallArguments($stack = array())

No description

CallArguments_Argument($res, $sub)

Values are bare words in templates, but strings in PHP. We rely on PHP's type conversion to back-convert strings to numbers when needed.

match_Call($stack = array())

No description

match_LookupStep($stack = array())

No description

match_LastLookupStep($stack = array())

No description

match_Lookup($stack = array())

No description

Lookup__construct($res)

No description

Lookup_AddLookupStep($res, $sub, $method)

The basic generated PHP of LookupStep and LastLookupStep is the same, except that LookupStep calls 'obj' to get the next ViewableData in the sequence, and LastLookupStep calls different methods (XML_val, hasValue, obj) depending on the context the lookup is used in.

Lookup_LookupStep($res, $sub)

No description

Lookup_LastLookupStep($res, $sub)

No description

match_Translate($stack = array())

No description

match_InjectionVariables($stack = array())

No description

match_Entity($stack = array())

No description

Translate__construct($res)

No description

Translate_Entity($res, $sub)

No description

Translate_Default($res, $sub)

No description

Translate_Context($res, $sub)

No description

Translate_InjectionVariables($res, $sub)

No description

Translate__finalise($res)

No description

InjectionVariables__construct($res)

No description

InjectionVariables_InjectionName($res, $sub)

No description

InjectionVariables_Argument($res, $sub)

No description

InjectionVariables__finalise($res)

No description

match_MalformedBracketInjection($stack = array())

No description

match_SimpleInjection($stack = array())

No description

match_BracketInjection($stack = array())

No description

match_Injection($stack = array())

No description

Injection_STR($res, $sub)

No description

match_DollarMarkedLookup($stack = array())

No description

DollarMarkedLookup_STR($res, $sub)

No description

match_QuotedString($stack = array())

No description

match_FreeString($stack = array())

No description

match_Argument($stack = array())

No description

Argument_DollarMarkedLookup($res, $sub)

If we get a bare value, we don't know enough to determine exactly what php would be the translation, because we don't know if the position of use indicates a lookup or a string argument.

Argument_QuotedString($res, $sub)

No description

Argument_Lookup($res, $sub)

No description

Argument_FreeString($res, $sub)

No description

match_ComparisonOperator($stack = array())

No description

match_Comparison($stack = array())

No description

Comparison_Argument($res, $sub)

No description

Comparison_ComparisonOperator($res, $sub)

No description

match_PresenceCheck($stack = array())

No description

PresenceCheck_Not($res, $sub)

No description

PresenceCheck_Argument($res, $sub)

No description

match_IfArgumentPortion($stack = array())

No description

IfArgumentPortion_STR($res, $sub)

No description

match_BooleanOperator($stack = array())

No description

match_IfArgument($stack = array())

No description

IfArgument_IfArgumentPortion($res, $sub)

No description

IfArgument_BooleanOperator($res, $sub)

No description

match_IfPart($stack = array())

No description

match_ElseIfPart($stack = array())

No description

match_ElsePart($stack = array())

No description

match_If($stack = array())

No description

If_IfPart($res, $sub)

No description

If_ElseIfPart($res, $sub)

No description

If_ElsePart($res, $sub)

No description

match_Require($stack = array())

No description

Require_Call($res, $sub)

No description

match_CacheBlockArgument($stack = array())

No description

CacheBlockArgument_DollarMarkedLookup($res, $sub)

No description

CacheBlockArgument_QuotedString($res, $sub)

No description

CacheBlockArgument_Lookup($res, $sub)

No description

match_CacheBlockArguments($stack = array())

No description

CacheBlockArguments_CacheBlockArgument($res, $sub)

No description

match_CacheBlockTemplate($stack = array())

No description

match_UncachedBlock($stack = array())

No description

UncachedBlock_Template($res, $sub)

No description

match_CacheRestrictedTemplate($stack = array())

No description

CacheRestrictedTemplate_CacheBlock($res, $sub)

No description

CacheRestrictedTemplate_UncachedBlock($res, $sub)

No description

match_CacheBlock($stack = array())

No description

CacheBlock__construct($res)

No description

CacheBlock_CacheBlockArguments($res, $sub)

No description

CacheBlock_Condition($res, $sub)

No description

CacheBlock_CacheBlock($res, $sub)

No description

CacheBlock_UncachedBlock($res, $sub)

No description

CacheBlock_CacheBlockTemplate($res, $sub)

No description

match_OldTPart($stack = array())

No description

match_N($stack = array())

No description

OldTPart__construct($res)

No description

OldTPart_QuotedString($res, $sub)

No description

OldTPart_CallArguments($res, $sub)

No description

OldTPart__finalise($res)

No description

match_OldTTag($stack = array())

No description

OldTTag_OldTPart($res, $sub)

No description

match_OldSprintfTag($stack = array())

No description

OldSprintfTag__construct($res)

No description

OldSprintfTag_OldTPart($res, $sub)

No description

OldSprintfTag_CallArguments($res, $sub)

No description

match_OldI18NTag($stack = array())

No description

OldI18NTag_STR($res, $sub)

No description

match_NamedArgument($stack = array())

No description

NamedArgument_Name($res, $sub)

No description

NamedArgument_Value($res, $sub)

No description

match_Include($stack = array())

No description

Include__construct($res)

No description

Include_Template($res, $sub)

No description

Include_NamedArgument($res, $sub)

No description

Include__finalise($res)

No description

match_BlockArguments($stack = array())

No description

match_NotBlockTag($stack = array())

No description

match_ClosedBlock($stack = array())

No description

ClosedBlock__construct($res)

As mentioned in the parser comment, block handling is kept fairly generic for extensibility. The match rule builds up two important elements in the match result array: 'ArgumentCount' - how many arguments were passed in the opening tag 'Arguments' an array of the Argument match rule result arrays

ClosedBlock_BlockArguments($res, $sub)

No description

ClosedBlock__finalise($res)

No description

ClosedBlock_Handle_Loop($res)

This is an example of a block handler function. This one handles the loop tag.

ClosedBlock_Handle_With($res)

The closed block handler for with blocks

match_OpenBlock($stack = array())

No description

OpenBlock__construct($res)

No description

OpenBlock_BlockArguments($res, $sub)

No description

OpenBlock__finalise($res)

No description

OpenBlock_Handle_Debug($res)

This is an open block handler, for the <% debug %> utility tag

OpenBlock_Handle_Base_tag($res)

This is an open block handler, for the <% base_tag %> tag

OpenBlock_Handle_Current_page($res)

This is an open block handler, for the <% current_page %> tag

match_MismatchedEndBlock($stack = array())

No description

MismatchedEndBlock__finalise($res)

No description

match_MalformedOpenTag($stack = array())

No description

MalformedOpenTag__finalise($res)

No description

match_MalformedCloseTag($stack = array())

No description

MalformedCloseTag__finalise($res)

No description

match_MalformedBlock($stack = array())

No description

match_CommentWithContent($stack = array())

No description

match_EmptyComment($stack = array())

No description

match_Comment($stack = array())

No description

Comment__construct($res)

No description

match_TopTemplate($stack = array())

No description

TopTemplate__construct($res)

The TopTemplate also includes the opening stanza to start off the template

match_Text($stack = array())

No description

Text__finalise($res)

We convert text

string
compileString(string $string, string $templateName = "", bool $includeDebuggingComments = false, bool $topTemplate = true)

Compiles some passed template source code into the php code that will execute as per the template source.

static mixed|string
compileFile($template)

Compiles some file that contains template source code, and returns the php code that will execute as per that source

Details

__construct(array $closedBlocks = [], array $openBlocks = [])

Allow the injection of new closed & open block callables

Parameters

array $closedBlocks
array $openBlocks

construct($matchrule, $name, $arguments = null)

Override the function that constructs the result arrays to also prepare a 'php' item in the array

Parameters

$matchrule
$name
$arguments

setClosedBlocks(array $closedBlocks)

Set the closed blocks that the template parser should use

This method will delete any existing closed blocks, please use addClosedBlock if you don't want to overwrite

Parameters

array $closedBlocks

Exceptions

InvalidArgumentException

setOpenBlocks(array $openBlocks)

Set the open blocks that the template parser should use

This method will delete any existing open blocks, please use addOpenBlock if you don't want to overwrite

Parameters

array $openBlocks

Exceptions

InvalidArgumentException

addClosedBlock(string $name, callable $callable)

Add a closed block callable to allow <% name %><% end_name %> syntax

Parameters

string $name

The name of the token to be used in the syntax <% name %><% end_name %>

callable $callable

The function that modifies the generation of template code

Exceptions

InvalidArgumentException

addOpenBlock(string $name, callable $callable)

Add a closed block callable to allow <% name %> syntax

Parameters

string $name

The name of the token to be used in the syntax <% name %>

callable $callable

The function that modifies the generation of template code

Exceptions

InvalidArgumentException

match_Template($stack = array())

Parameters

$stack

Template_STR($res, $sub)

Parameters

$res
$sub

match_Word($stack = array())

Parameters

$stack

match_NamespacedWord($stack = array())

Parameters

$stack

match_Number($stack = array())

Parameters

$stack

match_Value($stack = array())

Parameters

$stack

match_CallArguments($stack = array())

Parameters

$stack

CallArguments_Argument($res, $sub)

Values are bare words in templates, but strings in PHP. We rely on PHP's type conversion to back-convert strings to numbers when needed.

Parameters

$res
$sub

match_Call($stack = array())

Parameters

$stack

match_LookupStep($stack = array())

Parameters

$stack

match_LastLookupStep($stack = array())

Parameters

$stack

match_Lookup($stack = array())

Parameters

$stack

Lookup__construct($res)

Parameters

$res

Lookup_AddLookupStep($res, $sub, $method)

The basic generated PHP of LookupStep and LastLookupStep is the same, except that LookupStep calls 'obj' to get the next ViewableData in the sequence, and LastLookupStep calls different methods (XML_val, hasValue, obj) depending on the context the lookup is used in.

Parameters

$res
$sub
$method

Lookup_LookupStep($res, $sub)

Parameters

$res
$sub

Lookup_LastLookupStep($res, $sub)

Parameters

$res
$sub

match_Translate($stack = array())

Parameters

$stack

match_InjectionVariables($stack = array())

Parameters

$stack

match_Entity($stack = array())

Parameters

$stack

Translate__construct($res)

Parameters

$res

Translate_Entity($res, $sub)

Parameters

$res
$sub

Translate_Default($res, $sub)

Parameters

$res
$sub

Translate_Context($res, $sub)

Parameters

$res
$sub

Translate_InjectionVariables($res, $sub)

Parameters

$res
$sub

Translate__finalise($res)

Parameters

$res

InjectionVariables__construct($res)

Parameters

$res

InjectionVariables_InjectionName($res, $sub)

Parameters

$res
$sub

InjectionVariables_Argument($res, $sub)

Parameters

$res
$sub

InjectionVariables__finalise($res)

Parameters

$res

match_MalformedBracketInjection($stack = array())

Parameters

$stack

MalformedBracketInjection__finalise($res)

Parameters

$res

match_SimpleInjection($stack = array())

Parameters

$stack

match_BracketInjection($stack = array())

Parameters

$stack

match_Injection($stack = array())

Parameters

$stack

Injection_STR($res, $sub)

Parameters

$res
$sub

match_DollarMarkedLookup($stack = array())

Parameters

$stack

DollarMarkedLookup_STR($res, $sub)

Parameters

$res
$sub

match_QuotedString($stack = array())

Parameters

$stack

match_FreeString($stack = array())

Parameters

$stack

match_Argument($stack = array())

Parameters

$stack

Argument_DollarMarkedLookup($res, $sub)

If we get a bare value, we don't know enough to determine exactly what php would be the translation, because we don't know if the position of use indicates a lookup or a string argument.

Instead, we record 'ArgumentMode' as a member of this matches results node, which can be:

  • lookup if this argument was unambiguously a lookup (marked as such)
  • string is this argument was unambiguously a string (marked as such, or impossible to parse as lookup)
  • default if this argument needs to be handled as per 2.4

In the case of 'default', there is no php member of the results node, but instead 'lookup_php', which should be used by the parent if the context indicates a lookup, and 'string_php' which should be used if the context indicates a string

Parameters

$res
$sub

Argument_QuotedString($res, $sub)

Parameters

$res
$sub

Argument_Lookup($res, $sub)

Parameters

$res
$sub

Argument_FreeString($res, $sub)

Parameters

$res
$sub

match_ComparisonOperator($stack = array())

Parameters

$stack

match_Comparison($stack = array())

Parameters

$stack

Comparison_Argument($res, $sub)

Parameters

$res
$sub

Comparison_ComparisonOperator($res, $sub)

Parameters

$res
$sub

match_PresenceCheck($stack = array())

Parameters

$stack

PresenceCheck_Not($res, $sub)

Parameters

$res
$sub

PresenceCheck_Argument($res, $sub)

Parameters

$res
$sub

match_IfArgumentPortion($stack = array())

Parameters

$stack

IfArgumentPortion_STR($res, $sub)

Parameters

$res
$sub

match_BooleanOperator($stack = array())

Parameters

$stack

match_IfArgument($stack = array())

Parameters

$stack

IfArgument_IfArgumentPortion($res, $sub)

Parameters

$res
$sub

IfArgument_BooleanOperator($res, $sub)

Parameters

$res
$sub

match_IfPart($stack = array())

Parameters

$stack

match_ElseIfPart($stack = array())

Parameters

$stack

match_ElsePart($stack = array())

Parameters

$stack

match_If($stack = array())

Parameters

$stack

If_IfPart($res, $sub)

Parameters

$res
$sub

If_ElseIfPart($res, $sub)

Parameters

$res
$sub

If_ElsePart($res, $sub)

Parameters

$res
$sub

match_Require($stack = array())

Parameters

$stack

Require_Call($res, $sub)

Parameters

$res
$sub

match_CacheBlockArgument($stack = array())

Parameters

$stack

CacheBlockArgument_DollarMarkedLookup($res, $sub)

Parameters

$res
$sub

CacheBlockArgument_QuotedString($res, $sub)

Parameters

$res
$sub

CacheBlockArgument_Lookup($res, $sub)

Parameters

$res
$sub

match_CacheBlockArguments($stack = array())

Parameters

$stack

CacheBlockArguments_CacheBlockArgument($res, $sub)

Parameters

$res
$sub

match_CacheBlockTemplate($stack = array())

Parameters

$stack

match_UncachedBlock($stack = array())

Parameters

$stack

UncachedBlock_Template($res, $sub)

Parameters

$res
$sub

match_CacheRestrictedTemplate($stack = array())

Parameters

$stack

CacheRestrictedTemplate_CacheBlock($res, $sub)

Parameters

$res
$sub

CacheRestrictedTemplate_UncachedBlock($res, $sub)

Parameters

$res
$sub

match_CacheBlock($stack = array())

Parameters

$stack

CacheBlock__construct($res)

Parameters

$res

CacheBlock_CacheBlockArguments($res, $sub)

Parameters

$res
$sub

CacheBlock_Condition($res, $sub)

Parameters

$res
$sub

CacheBlock_CacheBlock($res, $sub)

Parameters

$res
$sub

CacheBlock_UncachedBlock($res, $sub)

Parameters

$res
$sub

CacheBlock_CacheBlockTemplate($res, $sub)

Parameters

$res
$sub

match_OldTPart($stack = array())

Parameters

$stack

match_N($stack = array())

Parameters

$stack

OldTPart__construct($res)

Parameters

$res

OldTPart_QuotedString($res, $sub)

Parameters

$res
$sub

OldTPart_CallArguments($res, $sub)

Parameters

$res
$sub

OldTPart__finalise($res)

Parameters

$res

match_OldTTag($stack = array())

Parameters

$stack

OldTTag_OldTPart($res, $sub)

Parameters

$res
$sub

match_OldSprintfTag($stack = array())

Parameters

$stack

OldSprintfTag__construct($res)

Parameters

$res

OldSprintfTag_OldTPart($res, $sub)

Parameters

$res
$sub

OldSprintfTag_CallArguments($res, $sub)

Parameters

$res
$sub

match_OldI18NTag($stack = array())

Parameters

$stack

OldI18NTag_STR($res, $sub)

Parameters

$res
$sub

match_NamedArgument($stack = array())

Parameters

$stack

NamedArgument_Name($res, $sub)

Parameters

$res
$sub

NamedArgument_Value($res, $sub)

Parameters

$res
$sub

match_Include($stack = array())

Parameters

$stack

Include__construct($res)

Parameters

$res

Include_Template($res, $sub)

Parameters

$res
$sub

Include_NamedArgument($res, $sub)

Parameters

$res
$sub

Include__finalise($res)

Parameters

$res

match_BlockArguments($stack = array())

Parameters

$stack

match_NotBlockTag($stack = array())

Parameters

$stack

match_ClosedBlock($stack = array())

Parameters

$stack

ClosedBlock__construct($res)

As mentioned in the parser comment, block handling is kept fairly generic for extensibility. The match rule builds up two important elements in the match result array: 'ArgumentCount' - how many arguments were passed in the opening tag 'Arguments' an array of the Argument match rule result arrays

Once a block has successfully been matched against, it will then look for the actual handler, which should be on this class (either defined or extended on) as ClosedBlock_Handler_Name(&$res), where Name is the tag name, first letter captialized (i.e Control, Loop, With, etc).

This function will be called with the match rule result array as it's first argument. It should return the php result of this block as it's return value, or throw an error if incorrect arguments were passed.

Parameters

$res

ClosedBlock_BlockArguments($res, $sub)

Parameters

$res
$sub

ClosedBlock__finalise($res)

Parameters

$res

ClosedBlock_Handle_Loop($res)

This is an example of a block handler function. This one handles the loop tag.

Parameters

$res

ClosedBlock_Handle_With($res)

The closed block handler for with blocks

Parameters

$res

match_OpenBlock($stack = array())

Parameters

$stack

OpenBlock__construct($res)

Parameters

$res

OpenBlock_BlockArguments($res, $sub)

Parameters

$res
$sub

OpenBlock__finalise($res)

Parameters

$res

OpenBlock_Handle_Debug($res)

This is an open block handler, for the <% debug %> utility tag

Parameters

$res

OpenBlock_Handle_Base_tag($res)

This is an open block handler, for the <% base_tag %> tag

Parameters

$res

OpenBlock_Handle_Current_page($res)

This is an open block handler, for the <% current_page %> tag

Parameters

$res

match_MismatchedEndBlock($stack = array())

Parameters

$stack

MismatchedEndBlock__finalise($res)

Parameters

$res

match_MalformedOpenTag($stack = array())

Parameters

$stack

MalformedOpenTag__finalise($res)

Parameters

$res

match_MalformedCloseTag($stack = array())

Parameters

$stack

MalformedCloseTag__finalise($res)

Parameters

$res

match_MalformedBlock($stack = array())

Parameters

$stack

match_CommentWithContent($stack = array())

Parameters

$stack

match_EmptyComment($stack = array())

Parameters

$stack

match_Comment($stack = array())

Parameters

$stack

Comment__construct($res)

Parameters

$res

match_TopTemplate($stack = array())

Parameters

$stack

TopTemplate__construct($res)

The TopTemplate also includes the opening stanza to start off the template

Parameters

$res

match_Text($stack = array())

Parameters

$stack

Text__finalise($res)

We convert text

Parameters

$res

string compileString(string $string, string $templateName = "", bool $includeDebuggingComments = false, bool $topTemplate = true)

Compiles some passed template source code into the php code that will execute as per the template source.

Parameters

string $string

The source of the template

string $templateName

The name of the template, normally the filename the template source was loaded from

bool $includeDebuggingComments

True is debugging comments should be included in the output

bool $topTemplate

True if this is a top template, false if it's just a template

Return Value

string

The php that, when executed (via include or exec) will behave as per the template source

Exceptions

SSTemplateParseException

static mixed|string compileFile($template)

Compiles some file that contains template source code, and returns the php code that will execute as per that source

Parameters

$template
  • A file path that contains template source code

Return Value

mixed|string
  • The php that, when executed (via include or exec) will behave as per the template source