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 CSS classes to an attribute array.
-
addClassNames() public
Merges two sets of CSS classes into a unique array.
-
configShallow() public
Merge provided config with existing config. Unlike
config()which does a recursive merge for nested keys, this method does a simple merge. -
deleteConfig() public
Deletes a config key.
-
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): $key is null ? array : mixedReads a config key.
Parameters
-
string|null$key Key to read.
Returns
$key is null ? array : 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, mixed $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
-
mixed$value The value of the attribute to create.
-
bool$escape optional Define if the value must be escaped
Returns
stringThe composed attribute.
add() ¶ public
add(array<string, 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, string>$templates An associative list of named templates.
Returns
$thisaddClass() ¶ public
addClass(array<string, mixed>|string|null $input, array<string>|string|false|null $newClass, string $useIndex = 'class'): array<string, string>|string|nullAdds CSS classes to an attribute array.
Merges the provided classes with any existing classes in the specified key and returns the updated attribute array with unique class values.
Deprecated: Passing a non-array as first argument is deprecated. Pass an attributes array instead. Deprecated: Returning a non-array value is deprecated. The method will only return arrays in the future.
Parameters
-
array<string, mixed>|string|null$input The attribute array to add classes to.
-
array<string>|string|false|null$newClass The class(es) to add.
-
string$useIndex optional The array key to use. Defaults to 'class'.
Returns
array<string, string>|string|nullThe updated attribute array.
addClassNames() ¶ public
addClassNames(array<string>|string $existing, array<string>|string $new): array<string>Merges two sets of CSS classes into a unique array.
Accepts class lists as arrays or space-separated strings and returns a unique, indexed array of all classes.
Parameters
-
array<string>|string$existing The existing class(es).
-
array<string>|string$new The new class(es) to merge.
Returns
array<string>A unique array of merged classes.
configShallow() ¶ 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
$thisdeleteConfig() ¶ public
deleteConfig(string $key): $thisDeletes a config key.
Parameters
-
string$key Key to delete. It can be a dot separated string to delete nested keys.
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
stringFormatted string
Throws
InvalidArgumentExceptionIf 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
stringComposed attributes.
getConfig() ¶ public
getConfig(string|null $key = null, mixed $default = null): $key is null ? array : 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
$key is null ? array : mixedConfiguration data at the named key or null if the key does not exist.
getConfigOrFail() ¶ 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
mixedConfiguration data at the named key
Throws
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.