XenForo Reference Guide for Developer
Back to top  

General template compiling class.

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) 

Sets up text.

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

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

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

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

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

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

Returns any number of statements.

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

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

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) 

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

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

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

The key is a single quoted string.

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

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

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

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) 

Parameters

$text

string

Text to compile

$options

array

Options

Compile segment into PHP code

compileSegment(string | array $segment, array $options) : string

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

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) 

Mostly handled by the specified tag handler.

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) 

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

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

Parameters

$varRef

stringarray

Variable reference segment(s)

$options

array

Options

Returns

stringPHP code to access named variable

Disables dynamic phrase loading.

disableDynamicPhraseLoad() 

Generally only desired for tests.

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

escapeSingleQuotedString(string $string) : string

Parameters

$string

string

Returns

string

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

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

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

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

Returns

array

Gets a list of all phrases included in this template.

getIncludedPhrases() : array

Returns

arrayList of phrase titles

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

getIncludedTemplates() : array

Returns

array

Gets the current line number.

getLineNumber() : integer

Returns

integer

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

getNamedAttributes(array $attributes, array $wantedAttributes) : array

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

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

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

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

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

Returns

\XenForo_Template_Compiler_Statement_Collection

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

getOutputVar() : string

Returns

string

Gets the PHP statement that initializers the output var.

getOutputVarInitializer() : string

Returns

string

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

getPhraseValue(string $title) : string | false

Parameters

$title

string

Returns

stringfalse

Gets a unique variable name for an internal variable.

getUniqueVar() : string

Returns

string

Gets the variable map list.

getVariableMap() : array

Returns

array

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

identifyPhrasesInParsedTemplate(string | array $segments) : array

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

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

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

Parameters

$segment

stringarray

Segment

$tagName

string

Tag name

Returns

boolean

Lex and parse the template into segments for final compilation.

lexAndParse() : array

Returns

arrayParsed segments

Merges phrases into the existing phrase cache.

mergePhraseCache(array $phraseData) 

Phrases are expected for all languages.

Parameters

$phraseData

array

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

Parses a conditional expression into valid PHP code

parseConditionExpression(string | array $origCondition, array $options) : string

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

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

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

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

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() 
Static

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

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 styles

Resolves the mapping for the specified variable.

resolveMappedVariable(string $name, array $options) : string

Parameters

$name

string

$options

array

Compiler options

Returns

string

Modifies the default options.

setDefaultOptions(array $options) : \XenForo_Template_Compiler

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

Parameters

$options

array

Returns

\XenForo_Template_CompilerFluent interface ($this)

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

setFollowExternal(boolean $value) 

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

Parameters

$value

boolean

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

setLastVistedSegment(mixed $segment) 

Parameters

$segment

mixed

Sets the line number manually.

setLineNumber(integer $lineNumber) 

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.

Parameters

$lineNumber

integer

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

setOutputVar(string $_outputVar) 

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) 

Parameters

$text

string

Sets/merges the variable map list.

setVariableMap(array $map, boolean $merge) 

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) 

Parameters

$segments

arraystring

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

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

Parameters

$title

string

Title of template

$styleId

integer

ID of the style the template should apply to

Returns

falsearrayArray should have keys of id and data (data should be parsed version of template)

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

_identifyPhrasesInSegments(string | array $segments) : array

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

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

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) 
Static

Parameters

$title

string

$compilerType

string

Internal handler for resetting the template cache.

_resetTemplateCache(integer | boolean $styleId, string $compilerType) 
Static

Parameters

$styleId

integerboolean

$compilerType

string

Internal handler for setting the template cache.

_setTemplateCache(array $templates, integer $styleId, string $compilerType) 
Static

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 
 

$_followExternal : boolean

This can be set to false for test compiles.

 

$_functionHandlers : array

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

 

$_includedPhrases 
 

$_includedTemplates 
 

$_languageId 
 

$_lineNumber : integer
 

$_options : array

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

 

$_outputVar : string
 

$_phraseCache 
 

$_styleId 
 

$_tagHandlers : array

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

 

$_templateCache : array

Used for includes

 

$_text : string
 

$_title 
 

$_uniqueVarCount : integer
 

$_uniqueVarPrefix : string
 

$_variableMap : array

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