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.

Namespace: Cake\View

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

bool

Whether the config property has already been configured with defaults
$_configStack protected

array

A 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::$_compactAttributes and 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 = []): void

Compile 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): void

Deletes a single config key.

Parameters

string $key: Key to delete.

Returns

void

Throws

Cake\Core\Exception\CakeException
if attempting to clobber existing config

_configRead() protected

_configRead(string|null $key): mixed

Reads 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): void

Writes 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

void

Throws

Cake\Core\Exception\CakeException
if attempting to clobber existing config

_formatAttribute() protected

_formatAttribute(string $key, array<string>|string $value, bool $escape = true): string

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'

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

string

add() public

add(array<string> $templates): $this

Registers 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

$this

addClass() public

addClass(array|string $input, array<string>|string $newClass, string $useIndex = 'class'): array<string>|string

Adds 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>|string

configShallow() public

configShallow(array<string, mixed>|string $key, mixed|null $value = null): $this

Merge 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

$this

format() public

format(string $name, array<string, mixed> $data): string

Format a template string with $data

Parameters

string $name: The template name.
array<string, mixed> $data: The data to insert.

Returns

string

Throws

RuntimeException
If template not found.

formatAttributes() public

formatAttributes(array<string, mixed>|null $options, array<string>|null $exclude = null): string

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::$_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

string

getConfig() public

getConfig(string|null $key = null, mixed $default = null): mixed

Returns 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

mixed

getConfigOrFail() public

getConfigOrFail(string $key): mixed

Returns 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

mixed

Throws

InvalidArgumentException

load() public

load(string $file): void

Load 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

void

pop() public

pop(): void

Restore the most recently pushed set of templates.

Returns

void

push() public

push(): void

Push the current templates into the template stack.

Returns

void

remove() public

remove(string $name): void

Remove the named template.

Parameters

string $name: The template to remove.

Returns

void

setConfig() public

setConfig(array<string, mixed>|string $key, mixed|null $value = null, bool $merge = true): $this

Sets 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

$this

Throws

Cake\Core\Exception\CakeException
When trying to set a key that is invalid.

Property Detail

`$_compactAttributes` protected

List of attributes that can be made compact.

Type

array<string, bool>

`$_compiled` protected

Contains the list of compiled templates

Type

array<string, array>

`$_config` protected

Runtime config

Type

array<string, mixed>

`$_configInitialized` protected

Whether the config property has already been configured with defaults

Type

bool

`$_configStack` protected

A stack of template sets that have been stashed temporarily.

Type

array

`$_defaultConfig` protected

The default templates this instance holds.

Type

array<string, mixed>

© 2005–present The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/4.4/class-Cake.View.StringTemplate.html