Class StringTemplate
Provides an interface for registering and inserting content into simple logic-less string templates.
Used by several helpers to provide simple flexible templates for generating HTML and other content.
Property Summary
-
$_compactAttributes protected
array<string, bool>List of attributes that can be made compact.
-
$_compiled protected
array<string, array>Contains the list of compiled templates
-
$_config protected
array<string, mixed>Runtime config
-
$_configInitialized protected
boolWhether the config property has already been configured with defaults
-
$_configStack protected
arrayA stack of template sets that have been stashed temporarily.
-
$_defaultConfig protected
array<string, mixed>The default templates this instance holds.
Method Summary
-
__construct() public
Constructor.
-
_compileTemplates() protected
Compile templates into a more efficient printf() compatible format.
-
_configDelete() protected
Deletes a single config key.
-
_configRead() protected
Reads a config key.
-
_configWrite() protected
Writes a config key.
-
_formatAttribute() protected
Formats an individual attribute, and returns the string value of the composed attribute. Works with minimized attributes that have the same value as their name such as 'disabled' and 'checked'
-
add() public
Registers a list of templates by name
-
addClass() public
Adds a class and returns a unique list either in array or space separated
-
configShallow() public
Merge provided config with existing config. Unlike
config()which does a recursive merge for nested keys, this method does a simple merge. -
format() public
Format a template string with $data
-
formatAttributes() public
Returns a space-delimited string with items of the $options array. If a key of $options array happens to be one of those listed in
StringTemplate::$_compactAttributesand its value is one of: -
getConfig() public
Returns the config.
-
getConfigOrFail() public
Returns the config for this specific key.
-
load() public
Load a config file containing templates.
-
pop() public
Restore the most recently pushed set of templates.
-
push() public
Push the current templates into the template stack.
-
remove() public
Remove the named template.
-
setConfig() public
Sets the config.
Method Detail
__construct() ¶ public
__construct(array<string, mixed> $config = [])Constructor.
Parameters
-
array<string, mixed>$config optional A set of templates to add.
_compileTemplates() ¶ protected
_compileTemplates(array<string> $templates = []): voidCompile templates into a more efficient printf() compatible format.
Parameters
-
array<string>$templates optional The template names to compile. If empty all templates will be compiled.
Returns
void_configDelete() ¶ protected
_configDelete(string $key): voidDeletes a single config key.
Parameters
-
string$key Key to delete.
Returns
voidThrows
Cake\Core\Exception\CakeExceptionif attempting to clobber existing config
_configRead() ¶ protected
_configRead(string|null $key): mixedReads a config key.
Parameters
-
string|null$key Key to read.
Returns
mixed_configWrite() ¶ protected
_configWrite(array<string, mixed>|string $key, mixed $value, string|bool $merge = false): voidWrites a config key.
Parameters
-
array<string, mixed>|string$key Key to write to.
-
mixed$value Value to write.
-
string|bool$merge optional True to merge recursively, 'shallow' for simple merge, false to overwrite, defaults to false.
Returns
voidThrows
Cake\Core\Exception\CakeExceptionif attempting to clobber existing config
_formatAttribute() ¶ protected
_formatAttribute(string $key, array<string>|string $value, bool $escape = true): stringFormats an individual attribute, and returns the string value of the composed attribute. Works with minimized attributes that have the same value as their name such as 'disabled' and 'checked'
Parameters
-
string$key The name of the attribute to create
-
array<string>|string$value The value of the attribute to create.
-
bool$escape optional Define if the value must be escaped
Returns
stringadd() ¶ public
add(array<string> $templates): $thisRegisters a list of templates by name
Example:
$templater->add([
'link' => '<a href="{{url}}">{{title}}</a>'
'button' => '<button>{{text}}</button>'
]);Parameters
-
array<string>$templates An associative list of named templates.
Returns
$thisaddClass() ¶ public
addClass(array|string $input, array<string>|string $newClass, string $useIndex = 'class'): array<string>|stringAdds a class and returns a unique list either in array or space separated
Parameters
-
array|string$input The array or string to add the class to
-
array<string>|string$newClass the new class or classes to add
-
string$useIndex optional if you are inputting an array with an element other than default of 'class'.
Returns
array<string>|stringconfigShallow() ¶ public
configShallow(array<string, mixed>|string $key, mixed|null $value = null): $thisMerge provided config with existing config. Unlike config() which does
a recursive merge for nested keys, this method does a simple merge.
Setting a specific value:
$this->configShallow('key', $value);Setting a nested value:
$this->configShallow('some.nested.key', $value);Updating multiple config settings at the same time:
$this->configShallow(['one' => 'value', 'another' => 'value']);Parameters
-
array<string, mixed>|string$key The key to set, or a complete array of configs.
-
mixed|null$value optional The value to set.
Returns
$thisformat() ¶ public
format(string $name, array<string, mixed> $data): stringFormat a template string with $data
Parameters
-
string$name The template name.
-
array<string, mixed>$data The data to insert.
Returns
stringThrows
RuntimeExceptionIf template not found.
formatAttributes() ¶ public
formatAttributes(array<string, mixed>|null $options, array<string>|null $exclude = null): stringReturns a space-delimited string with items of the $options array. If a key
of $options array happens to be one of those listed
in StringTemplate::$_compactAttributes and its value is one of:
- '1' (string)
- 1 (integer)
- true (boolean)
- 'true' (string)
Then the value will be reset to be identical with key's name. If the value is not one of these 4, the parameter is not output.
'escape' is a special option in that it controls the conversion of attributes to their HTML-entity encoded equivalents. Set to false to disable HTML-encoding.
If value for any option key is set to null or false, that option will be excluded from output.
This method uses the 'attribute' and 'compactAttribute' templates. Each of
these templates uses the name and value variables. You can modify these
templates to change how attributes are formatted.
Parameters
-
array<string, mixed>|null$options Array of options.
-
array<string>|null$exclude optional Array of options to be excluded, the options here will not be part of the return.
Returns
stringgetConfig() ¶ public
getConfig(string|null $key = null, mixed $default = null): mixedReturns the config.
Usage
Reading the whole config:
$this->getConfig();Reading a specific value:
$this->getConfig('key');Reading a nested value:
$this->getConfig('some.nested.key');Reading with default value:
$this->getConfig('some-key', 'default-value');Parameters
-
string|null$key optional The key to get or null for the whole config.
-
mixed$default optional The return value when the key does not exist.
Returns
mixedgetConfigOrFail() ¶ public
getConfigOrFail(string $key): mixedReturns the config for this specific key.
The config value for this key must exist, it can never be null.
Parameters
-
string$key The key to get.
Returns
mixedThrows
InvalidArgumentExceptionload() ¶ public
load(string $file): voidLoad a config file containing templates.
Template files should define a $config variable containing
all the templates to load. Loaded templates will be merged with existing
templates.
Parameters
-
string$file The file to load
Returns
voidremove() ¶ public
remove(string $name): voidRemove the named template.
Parameters
-
string$name The template to remove.
Returns
voidsetConfig() ¶ public
setConfig(array<string, mixed>|string $key, mixed|null $value = null, bool $merge = true): $thisSets the config.
Usage
Setting a specific value:
$this->setConfig('key', $value);Setting a nested value:
$this->setConfig('some.nested.key', $value);Updating multiple config settings at the same time:
$this->setConfig(['one' => 'value', 'another' => 'value']);Parameters
-
array<string, mixed>|string$key The key to set, or a complete array of configs.
-
mixed|null$value optional The value to set.
-
bool$merge optional Whether to recursively merge or overwrite existing config, defaults to true.
Returns
$thisThrows
Cake\Core\Exception\CakeExceptionWhen trying to set a key that is invalid.