XenForo Reference Guide for Developer
Back to top  

Template compiler for administrative templates.

This takes a string (template) and converts it into PHP code. This code represents the full statements.

Most methods are public so as to be usable by the tag/function handlers. Externally, compile() is the primary method to use for basic compilation.

package XenForo_Template

 Methods

Constructor.

__construct(string $text) 
Inherited

Sets up text.

inherited_from \XenForo_Template_Compiler::__construct()

Parameters

$text

string

Text to compile

Adds or replaces a template function handler.

addFunctionHandler(string $function, \XenForo_Template_Compiler_Function_Interface $handler) : \XenForo_Template_Compiler
Inherited
inherited_from \XenForo_Template_Compiler::addFunctionHandler()

Parameters

$function

string

Name of function to handle

$handler

\XenForo_Template_Compiler_Function_Interface

Handler object

Returns

\XenForo_Template_CompilerFluent interface ($this)

Adds or replaces an array of template function handlers.

addFunctionHandlers(array $functions) : \XenForo_Template_Compiler
Inherited
inherited_from \XenForo_Template_Compiler::addFunctionHandlers()

Parameters

$functions

array

Function handlers; key: function name, value: object

Returns

\XenForo_Template_CompilerFluent interface ($this)

Adds or replaces a template tag handler.

addTagHandler(string $tag, \XenForo_Template_Compiler_Tag_Interface $handler) : \XenForo_Template_Compiler
Inherited
inherited_from \XenForo_Template_Compiler::addTagHandler()

Parameters

$tag

string

Name of tag to handle

$handler

\XenForo_Template_Compiler_Tag_Interface

Handler object

Returns

\XenForo_Template_CompilerFluent interface ($this)

Adds or replaces an array of template tag handlers.

addTagHandlers(array $tags) : \XenForo_Template_Compiler
Inherited
inherited_from \XenForo_Template_Compiler::addTagHandlers()

Parameters

$tags

array

Tag handlers; key: tag name, value: object

Returns

\XenForo_Template_CompilerFluent interface ($this)

Build actual PHP code from a set of compiled named params

buildNamedParamCode(array $compiled) : string
Inherited
inherited_from \XenForo_Template_Compiler::buildNamedParamCode()

Parameters

$compiled

array

Already compiled named params. See {@link compileNamedParams}.

Returns

string

Compiles this template from a string.

compile(string $title, integer $styleId, integer $languageId) : string
Inherited

Returns any number of statements.

inherited_from \XenForo_Template_Compiler::compile()

Parameters

$title

string

Title of this template (required to prevent circular references)

$styleId

integer

Style ID this template belongs to (for template includes)

$languageId

integer

Language ID this compilation is for (used for phrases)

Returns

string

Combine uncompiled segments into a string of PHP code.

compileAndCombineSegments(string | array $segments, array $options) : string
Inherited

This is simply a helper function that compiles and then combines them for you.

inherited_from \XenForo_Template_Compiler::compileAndCombineSegments()

Parameters

$segments

stringarray

Segment(s)

$options

arraynull

Override options. If specified, this represents all options.

Returns

stringValid PHP code

Compile a function segment.

compileFunction(string $function, array $arguments, array $options) 
Inherited
inherited_from \XenForo_Template_Compiler::compileFunction()

Parameters

$function

string

Name of function found

$arguments

array

Arguments (really should have at least 1 value). Each argument may be any number of segments

$options

array

Options

Helper funcion to compile the provided segments into the specified variable.

compileIntoVariable(string | array $segments, string $var, array $options, boolean $generateVar) : string
Inherited

This is commonly used to simplify compilation of data that needs to be passed into a function (eg, the children of a form tag).

inherited_from \XenForo_Template_Compiler::compileIntoVariable()

Parameters

$segments

stringarray

Segmenets

$var

string

Name of the variable to compile into. If generateVar is true, this will be written to (by ref).

$options

array

Compiler options

$generateVar

boolean

Whether to generate the var in argument 2 or use the provided input

Returns

stringFull compiled statements

Compiled a set of named params into a set of named params that can be used as PHP code.

compileNamedParams(array $params, array $options, array $compileAsCondition) : array
Inherited

The key is a single quoted string.

inherited_from \XenForo_Template_Compiler::compileNamedParams()

Parameters

$params

array

See {@link parseNamedArguments()}. Key is the name, value is segments for that param.

$options

array

Compiler options

$compileAsCondition

array

A list of named params should be compiled as conditions instead of plain output

Returns

array

Compiles this template from its parsed output.

compileParsed(string | array $segments, string $title, integer $styleId, integer $languageId) : string
Inherited
inherited_from \XenForo_Template_Compiler::compileParsed()

Parameters

$segments

stringarray

$title

string

Title of this template (required to prevent circular references)

$styleId

integer

Style ID this template belongs to (for template includes)

$languageId

integer

Language ID this compilation is for (used for phrases)

Returns

string

Compiles this template from its parsed output.

compileParsedPlainText(string | array $segments, string $title, integer $styleId, integer $languageId) : string
Inherited

The template is considered to be plain text (the default variable escaping is disabled).

inherited_from \XenForo_Template_Compiler::compileParsedPlainText()

Parameters

$segments

stringarray

$title

string

Title of this template (required to prevent circular references)

$styleId

integer

Style ID this template belongs to (for template includes)

$languageId

integer

Language ID this compilation is for (used for phrases)

Returns

string

Compile a plain text segment.

compilePlainText(string $text, array $options) 
Inherited
inherited_from \XenForo_Template_Compiler::compilePlainText()

Parameters

$text

string

Text to compile

$options

array

Options

Compile segment into PHP code

compileSegment(string | array $segment, array $options) : string
Inherited
inherited_from \XenForo_Template_Compiler::compileSegment()

Parameters

$segment

stringarray

Segment

$options

array

Override options, must be specified

Returns

string

Compile segments into an array of PHP code.

compileSegments(string | array $segments, array $options) : \XenForo_Template_Compiler_Statement_Collection
Inherited
inherited_from \XenForo_Template_Compiler::compileSegments()

Parameters

$segments

stringarray

Segment(s)

$options

arraynull

Override options. If specified, this represents all options.

Returns

\XenForo_Template_Compiler_Statement_CollectionCollection of parts of a statement or sub statements

Compile a tag segment.

compileTag(string $tag, array $attributes, array $children, array $options) 
Inherited

Mostly handled by the specified tag handler.

inherited_from \XenForo_Template_Compiler::compileTag()

Parameters

$tag

string

Tag found

$attributes

array

Attributes (key: name, value: value)

$children

array

Any nodes (text, var, tag) that are within this tag

$options

array

Options

Compile a var segment.

compileVar(string $name, array $keys, array $options) 
Inherited
inherited_from \XenForo_Template_Compiler::compileVar()

Parameters

$name

string

Name of variable found, not including keys

$keys

array

Keys, may be empty

$options

array

Options

Compiles a variable reference.

compileVarRef(string | array $varRef, array $options) : string
Inherited

A var ref is a string that looks somewhat like a variable. It is used in some arguments to simplify variable access and only allow variables.

Data received is any number of segments containing strings or variable segments.

Examples: $var, $var.key, $var.{$key}.2, {$key}, {$key}.blah, {$key.blah}.x

inherited_from \XenForo_Template_Compiler::compileVarRef()

Parameters

$varRef

stringarray

Variable reference segment(s)

$options

array

Options

Returns

stringPHP code to access named variable

Disables dynamic phrase loading.

disableDynamicPhraseLoad() 
Inherited

Generally only desired for tests.

inherited_from \XenForo_Template_Compiler::disableDynamicPhraseLoad()

Escape a string for use inside a single-quoted string.

escapeSingleQuotedString(string $string) : string
Inherited
inherited_from \XenForo_Template_Compiler::escapeSingleQuotedString()

Parameters

$string

string

Returns

string

Gets the literal value of a curly function's argument.

getArgumentLiteralValue(string | array $argument) : string | false
Inherited

If a literal value cannot be obtained, false is returned.

inherited_from \XenForo_Template_Compiler::getArgumentLiteralValue()

Parameters

$argument

stringarray

Returns

stringfalseLiteral value or false

Gets the compiler type.

getCompilerType() : string

This method generally needs to be overridden in child classes because of the lack of LSB.

Returns

string

Gets the current set of default options.

getDefaultOptions() : array
Inherited
inherited_from \XenForo_Template_Compiler::getDefaultOptions()

Returns

array

Gets a list of all phrases included in this template.

getIncludedPhrases() : array
Inherited
inherited_from \XenForo_Template_Compiler::getIncludedPhrases()

Returns

arrayList of phrase titles

Gets the list of included template IDs (map or actual template IDs).

getIncludedTemplates() : array
Inherited
inherited_from \XenForo_Template_Compiler::getIncludedTemplates()

Returns

array

Gets the current line number.

getLineNumber() : integer
Inherited
inherited_from \XenForo_Template_Compiler::getLineNumber()

Returns

integer

Quickly gets multiple named attributes and returns any of them that exist.

getNamedAttributes(array $attributes, array $wantedAttributes) : array
Inherited
inherited_from \XenForo_Template_Compiler::getNamedAttributes()

Parameters

$attributes

array

Attributes for the tag

$wantedAttributes

array

Attributes to fetch

Returns

arrayAny attributes that existed

Takes a compiled set of named parameters and turns them into PHP code (an array).

getNamedParamsAsPhpCode(array $params, array $options, array $compileAsCondition) : string
Inherited
inherited_from \XenForo_Template_Compiler::getNamedParamsAsPhpCode()

Parameters

$params

array

See {@link parseNamedArguments()}. Key is the name, value is segments for that param.

$options

array

Compiler options

$compileAsCondition

array

A list of named params should be compiled as conditions instead of plain output

Returns

stringPHP code for an array

Creates a new compiler exception for an incorrect amount of arguments.

getNewCompilerArgumentException(mixed $segment) : \XenForo_Template_Compiler_Exception
Inherited
inherited_from \XenForo_Template_Compiler::getNewCompilerArgumentException()

Parameters

$segment

mixed

The segment that caused this. If specified and has a line number, that line is reported.

Returns

\XenForo_Template_Compiler_Exception

Creates a new compiler exception.

getNewCompilerException(string $message, mixed $segment) : \XenForo_Template_Compiler_Exception
Inherited
inherited_from \XenForo_Template_Compiler::getNewCompilerException()

Parameters

$message

string

Optional message

$segment

mixed

The segment that caused this. If specified and has a line number, that line is reported.

Returns

\XenForo_Template_Compiler_Exception

Creates a new raw statement handler.

getNewRawStatement(string $statement) : \XenForo_Template_Compiler_Statement_Raw
Inherited
inherited_from \XenForo_Template_Compiler::getNewRawStatement()

Parameters

$statement

string

Quickly set a statement

Returns

\XenForo_Template_Compiler_Statement_Raw

Creates a new statement collection handler.

getNewStatementCollection() : \XenForo_Template_Compiler_Statement_Collection
Inherited
inherited_from \XenForo_Template_Compiler::getNewStatementCollection()

Returns

\XenForo_Template_Compiler_Statement_Collection

Gets the variable name that full statements will write their contents into.

getOutputVar() : string
Inherited
inherited_from \XenForo_Template_Compiler::getOutputVar()

Returns

string

Gets the PHP statement that initializers the output var.

getOutputVarInitializer() : string
Inherited
inherited_from \XenForo_Template_Compiler::getOutputVarInitializer()

Returns

string

Gets the value for a phrase in the language the compiler is compiling for.

getPhraseValue(string $title) : string | false
Inherited
inherited_from \XenForo_Template_Compiler::getPhraseValue()

Parameters

$title

string

Returns

stringfalse

Gets a unique variable name for an internal variable.

getUniqueVar() : string
Inherited
inherited_from \XenForo_Template_Compiler::getUniqueVar()

Returns

string

Gets the variable map list.

getVariableMap() : array
Inherited
inherited_from \XenForo_Template_Compiler::getVariableMap()

Returns

array

Identifies the list of phrases that exist in a parsed template.

identifyPhrasesInParsedTemplate(string | array $segments) : array
Inherited

This list can be populated even if the template is invalid.

inherited_from \XenForo_Template_Compiler::identifyPhrasesInParsedTemplate()

Parameters

$segments

stringarray

List of parsed segments

Returns

arrayUnique list of phrases used in this template

Gets an already parsed template for inclusion.

includeParsedTemplate(string $title) : string | array
Inherited
inherited_from \XenForo_Template_Compiler::includeParsedTemplate()

Parameters

$title

string

Name of the template to include

Returns

stringarraySegments

Determines if the segment is a tag with the specified name.

isSegmentNamedTag(string | array $segment, string $tagName) : boolean
Inherited
inherited_from \XenForo_Template_Compiler::isSegmentNamedTag()

Parameters

$segment

stringarray

Segment

$tagName

string

Tag name

Returns

boolean

Lex and parse the template into segments for final compilation.

lexAndParse() : array
Inherited
inherited_from \XenForo_Template_Compiler::lexAndParse()

Returns

arrayParsed segments

Merges phrases into the existing phrase cache.

mergePhraseCache(array $phraseData) 
Inherited

Phrases are expected for all languages.

inherited_from \XenForo_Template_Compiler::mergePhraseCache()

Parameters

$phraseData

array

Format: [language id][title] => value

Parses a conditional expression into valid PHP code

parseConditionExpression(string | array $origCondition, array $options) : string
Inherited
inherited_from \XenForo_Template_Compiler::parseConditionExpression()

Parameters

$origCondition

stringarray

The original unparsed condition. This will consist of plaintext or curly var/function segments.

$options

array

Compiler options

Returns

stringValid PHP code for the condition

Parses a set of named arguments.

parseNamedArguments(array $arguments) : array
Inherited

Each argument should be in the form of "key=value". The key must be literal, but the value can be anything.

inherited_from \XenForo_Template_Compiler::parseNamedArguments()

Parameters

$arguments

array

Arguments to treat as named

Returns

arrayKey is the argument name, value is segment(s) to be compiled

Prepare a collection of segments for iteration.

prepareSegmentsForIteration(string | array $segments) : array
Inherited

This sanitizes the segments so that each step will give you the next segment, which itself may be a string or an array.

inherited_from \XenForo_Template_Compiler::prepareSegmentsForIteration()

Parameters

$segments

stringarray

Returns

array

Removes the named template from the compiler cache.

removeTemplateFromCache(string $title) 
Static

Parameters

$title

string

Resets the phrase cache.

resetPhraseCache() 
InheritedStatic

This should be done when a phrase value changes, before compiling templates.

inherited_from \XenForo_Template_Compiler::resetPhraseCache()

Helper to reset the template cache to reclaim memory or for tests.

resetTemplateCache(integer | true $styleId) 
Static

Parameters

$styleId

integertrue

Style ID to reset the cache for; true for all

Resolves the mapping for the specified variable.

resolveMappedVariable(string $name, array $options) : string
Inherited
inherited_from \XenForo_Template_Compiler::resolveMappedVariable()

Parameters

$name

string

$options

array

Compiler options

Returns

string

Modifies the default options.

setDefaultOptions(array $options) : \XenForo_Template_Compiler
Inherited

Note that this merges into the options, maintaining any that are not specified in the parameter.

inherited_from \XenForo_Template_Compiler::setDefaultOptions()

Parameters

$options

array

Returns

\XenForo_Template_CompilerFluent interface ($this)

Sets whether external data (phrases, includes) should be "followed" and fetched.

setFollowExternal(boolean $value) 
Inherited

This can be set to false when doing a test compile.

inherited_from \XenForo_Template_Compiler::setFollowExternal()

Parameters

$value

boolean

Sets the last segment that has been visited, updating the line number to reflect this.

setLastVistedSegment(mixed $segment) 
Inherited
inherited_from \XenForo_Template_Compiler::setLastVistedSegment()

Parameters

$segment

mixed

Sets the line number manually.

setLineNumber(integer $lineNumber) 
Inherited

This may be needed to report a more accurate line number when tags manually handle child tags (eg, if).

If this function is not used, the line number from the last tag handled by compileSegment() will be used.

inherited_from \XenForo_Template_Compiler::setLineNumber()

Parameters

$lineNumber

integer

Sets the variable name that full statements will write their contents into.

setOutputVar(string $_outputVar) 
Inherited
inherited_from \XenForo_Template_Compiler::setOutputVar()

Parameters

$_outputVar

string

Adds parsed templates to the template cache for the specified style.

setTemplateCache(array $templates, integer $styleId) 
Static

Parameters

$templates

array

Keys are template names, values are parsed vesions of templates

$styleId

integer

ID of the style that the templates are from

Sets the text to be compiled.

setText(string $text) 
Inherited
inherited_from \XenForo_Template_Compiler::setText()

Parameters

$text

string

Sets/merges the variable map list.

setVariableMap(array $map, boolean $merge) 
Inherited
inherited_from \XenForo_Template_Compiler::setVariableMap()

Parameters

$map

array

$merge

boolean

If true, merges; otherwise, overwrites

Finds the phrases used by the specified segments, loads them, and then merges them into the local phrase cache.

_findAndLoadPhrasesFromSegments(array | string $segments) 
Inherited
inherited_from \XenForo_Template_Compiler::_findAndLoadPhrasesFromSegments()

Parameters

$segments

arraystring

Helper to go to the model to get the parsed version of the specified template.

_getParsedTemplateFromModel(string $title, $styleId) : false | array

Parameters

$title

string

Title of template

$styleId

Returns

falsearray

Internal handler to get the phrases that are used in a collection of template segments.

_identifyPhrasesInSegments(string | array $segments) : array
Inherited
inherited_from \XenForo_Template_Compiler::_identifyPhrasesInSegments()

Parameters

$segments

stringarray

Returns

arrayList of phrases used in these segments; phrases may be repeated

Internal function for parsing a condition expression.

_parseConditionExpression(string $expression, array $placeholders, boolean $internalExpression, $isFunction) : string
Inherited

Note that the variables passed into this will be modified by reference.

inherited_from \XenForo_Template_Compiler::_parseConditionExpression()

Parameters

$expression

string

Expression with placeholders replaced with "\x1A"

$placeholders

array

Placeholders for variables/functions

$internalExpression

boolean

Whether to return when we match a right parenthesis

$isFunction

Returns

stringParsed condition

Internal handler to remove the named template from the specified compiler cache.

_removeTemplateFromCache(string $title, string $compilerType) 
InheritedStatic
inherited_from \XenForo_Template_Compiler::_removeTemplateFromCache()

Parameters

$title

string

$compilerType

string

Internal handler for resetting the template cache.

_resetTemplateCache(integer | boolean $styleId, string $compilerType) 
InheritedStatic
inherited_from \XenForo_Template_Compiler::_resetTemplateCache()

Parameters

$styleId

integerboolean

$compilerType

string

Internal handler for setting the template cache.

_setTemplateCache(array $templates, integer $styleId, string $compilerType) 
InheritedStatic
inherited_from \XenForo_Template_Compiler::_setTemplateCache()

Parameters

$templates

array

$styleId

integer

$compilerType

string

Set up the defaults.

_setupDefaults() 

Primarily sets up the handlers for various functions/tags.

 Properties

 

$_compilerType : string

This should be unique per class, based on the source for things like included templates, etc.

 

$_enableDynamicPhraseLoad 
Inherited
inherited_from \XenForo_Template_Compiler::$$_enableDynamicPhraseLoad
 

$_followExternal : boolean
Inherited

This can be set to false for test compiles.

inherited_from \XenForo_Template_Compiler::$$_followExternal
 

$_functionHandlers : array
Inherited

Key is the function name (lower case) and value is the object.

inherited_from \XenForo_Template_Compiler::$$_functionHandlers
 

$_includedPhrases 
Inherited
inherited_from \XenForo_Template_Compiler::$$_includedPhrases
 

$_includedTemplates 
Inherited
inherited_from \XenForo_Template_Compiler::$$_includedTemplates
 

$_languageId 
Inherited
inherited_from \XenForo_Template_Compiler::$$_languageId
 

$_lineNumber : integer
Inherited
inherited_from \XenForo_Template_Compiler::$$_lineNumber
 

$_options : array
Inherited

These will be used if individual handles do not override them. Handlers may override all of them or individual ones.

inherited_from \XenForo_Template_Compiler::$$_options
 

$_outputVar : string
Inherited
inherited_from \XenForo_Template_Compiler::$$_outputVar
 

$_phraseCache 
Inherited
inherited_from \XenForo_Template_Compiler::$$_phraseCache
 

$_styleId 
Inherited
inherited_from \XenForo_Template_Compiler::$$_styleId
 

$_tagHandlers : array
Inherited

Key is tag name (lower case) and value is the object.

inherited_from \XenForo_Template_Compiler::$$_tagHandlers
 

$_templateCache : array
Inherited

Used for includes

inherited_from \XenForo_Template_Compiler::$$_templateCache
 

$_text : string
Inherited
inherited_from \XenForo_Template_Compiler::$$_text
 

$_title 
Inherited
inherited_from \XenForo_Template_Compiler::$$_title
 

$_uniqueVarCount : integer
Inherited
inherited_from \XenForo_Template_Compiler::$$_uniqueVarCount
 

$_uniqueVarPrefix : string
Inherited
inherited_from \XenForo_Template_Compiler::$$_uniqueVarPrefix
 

$_variableMap : array
Inherited

This is primarily used for includes. Key is the from, value is the to.

inherited_from \XenForo_Template_Compiler::$$_variableMap