josbeir/cakephp-templater-defaults

TemplaterDefaults plugin for CakePHP

0.2.0 2025-09-10 09:49 UTC

Requires

• php: >=8.1
• cakephp/cakephp: ^5.0

Requires (Dev)

• cakephp/cakephp-codesniffer: ^5.2
• cakephp/debug_kit: ^5.1
• cakephp/plugin-installer: ^2.0.1
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^11.1.3 || ^12.0
• rector/rector: ^2.1

MIT

README

A custom templater for CakePHP that enables you to define default HTML attributes within CakePHP's string template system, making it easier to integrate with your preferred CSS setups and streamline HTML markup generated by helpers.

CakePHP's StringTemplates system does not allow merging attributes set at runtime with attributes defined in the template. This little plugin fixes this problem.

Table of Contents

1. Features
2. Installation
3. Usage
4. Examples
5. Limitations
6. Contributing
7. License

Features

• Attribute Merging: Runtime attributes are merged with template defaults, allowing easy extension or override.
• Attribute Swapping: Use the :swap suffix (e.g. class:swap) to completely replace a default attribute value.
• Works with CakePHP Helpers: Seamlessly integrates with helpers like FormHelper via the templateClass option.

Installation

Install via Composer:

composer require josbeir/cakephp-templater-defaults

Why

Imagine this template defintion for your FormHelper

'templates' => [
    'input' => '<input class="border border-slate-500 rounded-sm max-w-md min-w-4" type="{{type}}" name="{{name}}"{{attrs}}>',
];

In many cases you will want to add classes to control the size, width, etc. of those elements. This is not possible in core's StringTemplate unless you override the entire template at runtime on a per-element basis.

$this->Form->control('field', ['class' => 'extra-class']);
// Renders to
<div class="input text">
  <label>...</label>
  <input class="border border-slate-500 rounded-sm max-w-md min-w-4" type="text" name="field" class="extra-class">
</div>

This is not expected behavior.

Rather than doing that, this plugin uses a different approach: it merges the existing (default) attributes with ones defined at runtime:

$this->Form->control('field', ['class' => 'extra-class']);
// Renders to
<div class="input text">
  <label>...</label>
  <input class="border border-slate-500 rounded-sm max-w-md min-w-4 extra-class" type="text" name="field">
</div>

Usage

You can use the custom StringTemplate class directly or configure CakePHP helpers (like FormHelper) to use it:

In your AppView.php, set the templateClass option on any helper where you want to use this plugin.

use \TemplaterDefaults\View\StringTemplate;

$this->loadHelper('Form', [
    'templateClass' => StringTemplate::class,
]);

Examples

Attribute Merging

Default and runtime classes are merged:

// In your template file (e.g. src/Template/Example/index.php)
echo $this->Form->control('field', [
	'type' => 'text',
	'class' => 'runtime',
]);
// <input class="default runtime" ... >

Attribute Swapping

Use class:swap to replace the default:

echo $this->Form->control('field', [
	'type' => 'text',
	'class:swap' => 'swapped',
]);
// <input class="swapped" ... >

Or removing the default attribute.

echo $this->Form->control('field', [
	'type' => 'text',
	'class:swap' => '',
]);

// <input ... >

Limitations

• Default attributes obviously only work on html/xml style templates
• Only the top level element will be populated. Nested elements are ignored.

Contributing

Contributions, issues, and feature requests are welcome! Feel free to open a pull request or issue on GitHub. Please follow CakePHP coding standards and ensure all code is properly tested before submitting.

License

MIT