Skip to content

Commit 21037a3

Browse files
mpdudefabpot
mpdude
authored and
fabpot
committed
Add an html_attr function to make outputting HTML attributes easier
1 parent 91a3f34 commit 21037a3

9 files changed

Lines changed: 927 additions & 0 deletions

‎HtmlAttr/AttributeValueInterface.php‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
<?php
2+
3+
/*
4+
* This file is part of Twig.
5+
*
6+
* (c) Fabien Potencier
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*/
11+
12+
namespace Twig\Extra\Html\HtmlAttr;
13+
14+
/**
15+
* Interface for custom attribute value objects.
16+
*
17+
* Implement this interface to create custom conversion logic when printing out objects as attribute
18+
* values in the `html_attr` function.
19+
*
20+
* @author Matthias Pigulla <mp@webfactory.de>
21+
*/
22+
interface AttributeValueInterface
23+
{
24+
/**
25+
* Returns the string representation of the attribute value. The returned value
26+
* will automatically be escaped for the HTML attribute context.
27+
*
28+
* @return string|null the attribute value as a string, or null to omit the attribute
29+
*/
30+
public function getValue(): ?string;
31+
}

‎HtmlAttr/InlineStyle.php‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
<?php
2+
3+
/*
4+
* This file is part of Twig.
5+
*
6+
* (c) Fabien Potencier
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*/
11+
12+
namespace Twig\Extra\Html\HtmlAttr;
13+
14+
use Twig\Error\RuntimeError;
15+
16+
/**
17+
* @author Matthias Pigulla <mp@webfactory.de>
18+
*/
19+
final class InlineStyle implements MergeableInterface, AttributeValueInterface
20+
{
21+
private readonly array $value;
22+
23+
public function __construct(mixed $value)
24+
{
25+
if (!is_iterable($value)) {
26+
throw new RuntimeError('InlineStyle can only be created from iterable values.');
27+
}
28+
29+
$this->value = [...$value];
30+
}
31+
32+
public function mergeInto(mixed $previous): mixed
33+
{
34+
if ($previous instanceof self) {
35+
return new self([...$previous->value, ...$this->value]);
36+
}
37+
38+
if (is_iterable($previous)) {
39+
return new self([...$previous, ...$this->value]);
40+
}
41+
42+
throw new RuntimeError('Attributes using InlineStyle can only be merged with iterables or other InlineStyle instances.');
43+
}
44+
45+
public function appendFrom(mixed $newValue): mixed
46+
{
47+
if (!is_iterable($newValue)) {
48+
throw new RuntimeError('Only iterable values can be appended to InlineStyle.');
49+
}
50+
51+
return new self([...$this->value, ...$newValue]);
52+
}
53+
54+
public function getValue(): ?string
55+
{
56+
$style = '';
57+
foreach ($this->value as $name => $value) {
58+
if (empty($value) || true === $value) {
59+
continue;
60+
}
61+
if (is_numeric($name)) {
62+
$style .= trim($value, '; ').'; ';
63+
} else {
64+
$style .= $name.': '.$value.'; ';
65+
}
66+
}
67+
68+
return trim($style) ?: null;
69+
}
70+
}

‎HtmlAttr/MergeableInterface.php‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
<?php
2+
3+
/*
4+
* This file is part of Twig.
5+
*
6+
* (c) Fabien Potencier
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*/
11+
12+
namespace Twig\Extra\Html\HtmlAttr;
13+
14+
/**
15+
* Interface for attribute values that support custom merge behavior.
16+
*
17+
* Implement this interface to define how attribute values should be merged when multiple
18+
* attribute arrays are combined using `html_attr_merge`. This allows for
19+
* sophisticated merging logic beyond simple array merging.
20+
*
21+
* Objects implementing this interface probably want to implement either {@see AttributeValueInterface}
22+
* or `\Stringable` as well, in order to provide a reasonable to-string-conversion when being
23+
* the last value after a merge.
24+
*
25+
* @author Matthias Pigulla <mp@webfactory.de>
26+
*/
27+
interface MergeableInterface
28+
{
29+
/**
30+
* Merge value from $this with another, previous value. In the merge arguments list, $this is on the right
31+
* hand side of $previous. This is the preferred merge method, so that newer (right) values have control
32+
* over the result.
33+
*
34+
* The `$previous` value is whatever value was present for a particular attribute before. Implementations
35+
* are free to completely ignore this value, effectively implementing "override only" merge behavior.
36+
* They can merge it with their own value, resulting in array-like merge behavior. Or they could throw
37+
* an exception when only particular types can be merged.
38+
*
39+
* Returns the new, resulting value as a new instance. Does not modify either $this not $previous.
40+
*/
41+
public function mergeInto(mixed $previous): mixed;
42+
43+
/**
44+
* Merge value from $this with a new value. In the merge arguments list, $this is on the left hand side of
45+
* $newValue, but $newValue does not implement this interface itself.
46+
*
47+
* The `$newValue` value is whatever was given in the right hand side merge argument. Implementations are
48+
* free to return either the new value, implementing "override" merge behavior. They could also return
49+
* a value that represents a merge result between their current and the new value. Or they could throw
50+
* an exception when only particular types can be merged.
51+
*
52+
* Returns the new, resulting set as a new instance. Does not modify $this.
53+
*/
54+
public function appendFrom(mixed $newValue): mixed;
55+
}

‎HtmlAttr/SeparatedTokenList.php‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
<?php
2+
3+
/*
4+
* This file is part of Twig.
5+
*
6+
* (c) Fabien Potencier
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*/
11+
12+
namespace Twig\Extra\Html\HtmlAttr;
13+
14+
use Twig\Error\RuntimeError;
15+
16+
/**
17+
* @author Matthias Pigulla <mp@webfactory.de>
18+
*/
19+
final class SeparatedTokenList implements AttributeValueInterface, MergeableInterface
20+
{
21+
private readonly array $value;
22+
23+
public function __construct(mixed $value, private readonly string $separator = ' ')
24+
{
25+
if (is_iterable($value)) {
26+
$this->value = [...$value];
27+
} elseif (\is_scalar($value)) {
28+
$this->value = [$value];
29+
} else {
30+
throw new RuntimeError('SeparatedTokenList can only be constructed from iterable or scalar values.');
31+
}
32+
}
33+
34+
public function mergeInto(mixed $previous): mixed
35+
{
36+
if ($previous instanceof self && $previous->separator === $this->separator) {
37+
return new self([...$previous->value, ...$this->value], $this->separator);
38+
}
39+
40+
if (is_iterable($previous)) {
41+
return new self([...$previous, ...$this->value], $this->separator);
42+
}
43+
44+
throw new RuntimeError('SeparatedTokenList can only be merged with iterables or other SeparatedTokenList instances using the same separator.');
45+
}
46+
47+
public function appendFrom(mixed $newValue): mixed
48+
{
49+
if (!is_iterable($newValue)) {
50+
throw new RuntimeError('Only iterable values can be appended to SeparatedTokenList.');
51+
}
52+
53+
return new self([...$this->value, ...$newValue], $this->separator);
54+
}
55+
56+
public function getValue(): ?string
57+
{
58+
$filtered = array_filter($this->value, static fn ($v) => null !== $v && false !== $v);
59+
60+
// Omit attribute if list contains only false or null values
61+
if (!$filtered) {
62+
return null;
63+
}
64+
65+
// true values are not printed, but result in the attribute not being omitted
66+
return trim(implode($this->separator, array_filter($filtered, static fn ($v) => true !== $v)));
67+
}
68+
}

‎HtmlExtension.php‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,15 @@
1212
namespace Twig\Extra\Html;
1313

1414
use Symfony\Component\Mime\MimeTypes;
15+
use Twig\Environment;
1516
use Twig\Error\RuntimeError;
1617
use Twig\Extension\AbstractExtension;
18+
use Twig\Extra\Html\HtmlAttr\AttributeValueInterface;
19+
use Twig\Extra\Html\HtmlAttr\InlineStyle;
20+
use Twig\Extra\Html\HtmlAttr\MergeableInterface;
21+
use Twig\Extra\Html\HtmlAttr\SeparatedTokenList;
1722
use Twig\Markup;
23+
use Twig\Runtime\EscaperRuntime;
1824
use Twig\TwigFilter;
1925
use Twig\TwigFunction;
2026

@@ -31,6 +37,8 @@ public function getFilters(): array
3137
{
3238
return [
3339
new TwigFilter('data_uri', [$this, 'dataUri']),
40+
new TwigFilter('html_attr_merge', [self::class, 'htmlAttrMerge']),
41+
new TwigFilter('html_attr_type', [self::class, 'htmlAttrType']),
3442
];
3543
}
3644

@@ -39,6 +47,7 @@ public function getFunctions(): array
3947
return [
4048
new TwigFunction('html_classes', [self::class, 'htmlClasses']),
4149
new TwigFunction('html_cva', [self::class, 'htmlCva']),
50+
new TwigFunction('html_attr', [self::class, 'htmlAttr'], ['needs_environment' => true, 'is_safe' => ['html']]),
4251
];
4352
}
4453

@@ -125,4 +134,129 @@ public static function htmlCva(array|string $base = [], array $variants = [], ar
125134
{
126135
return new Cva($base, $variants, $compoundVariants, $defaultVariant);
127136
}
137+
138+
/** @internal */
139+
public static function htmlAttrType(mixed $value, string $type = 'sst'): AttributeValueInterface
140+
{
141+
return match ($type) {
142+
'sst' => new SeparatedTokenList($value, ' '),
143+
'cst' => new SeparatedTokenList($value, ', '),
144+
'style' => new InlineStyle($value),
145+
default => throw new RuntimeError(\sprintf('Unknown attribute type "%s" The only supported types are "sst", "cst" and "style".', $type)),
146+
};
147+
}
148+
149+
/** @internal */
150+
public static function htmlAttrMerge(iterable|string|false|null ...$arrays): array
151+
{
152+
$result = [];
153+
154+
foreach ($arrays as $array) {
155+
if (!$array) {
156+
continue;
157+
}
158+
159+
if (\is_string($array)) {
160+
throw new RuntimeError('Only empty strings may be passed as string arguments to html_attr_merge. This is to support the implicit else clause for ternary operators.');
161+
}
162+
163+
foreach ($array as $key => $value) {
164+
if (!isset($result[$key])) {
165+
$result[$key] = $value;
166+
167+
continue;
168+
}
169+
170+
$existing = $result[$key];
171+
172+
switch (true) {
173+
case $value instanceof MergeableInterface:
174+
$result[$key] = $value->mergeInto($existing);
175+
break;
176+
case $existing instanceof MergeableInterface:
177+
$result[$key] = $existing->appendFrom($value);
178+
break;
179+
case is_iterable($existing) && is_iterable($value):
180+
$result[$key] = [...$existing, ...$value];
181+
break;
182+
case (\is_scalar($existing) || \is_object($existing)) && (\is_scalar($value) || \is_object($value)):
183+
$result[$key] = $value;
184+
break;
185+
default:
186+
throw new RuntimeError(\sprintf('Cannot merge incompatible values for key "%s".', $key));
187+
}
188+
}
189+
}
190+
191+
return $result;
192+
}
193+
194+
/** @internal */
195+
public static function htmlAttr(Environment $env, iterable|string|false|null ...$args): string
196+
{
197+
$attr = self::htmlAttrMerge(...$args);
198+
199+
$result = '';
200+
$runtime = $env->getRuntime(EscaperRuntime::class);
201+
202+
foreach ($attr as $name => $value) {
203+
if (str_starts_with($name, 'aria-')) {
204+
// For aria-*, convert booleans to "true" and "false" strings
205+
if (true === $value) {
206+
$value = 'true';
207+
} elseif (false === $value) {
208+
$value = 'false';
209+
}
210+
}
211+
212+
if (str_starts_with($name, 'data-')) {
213+
if (!$value instanceof AttributeValueInterface && null !== $value && !\is_scalar($value)) {
214+
// ... encode non-null non-scalars as JSON
215+
try {
216+
$value = json_encode($value, \JSON_THROW_ON_ERROR);
217+
} catch (\JsonException $e) {
218+
throw new RuntimeError(\sprintf('The "%s" attribute value cannot be JSON encoded.', $name), previous: $e);
219+
}
220+
} elseif (true === $value) {
221+
// ... and convert boolean true to a 'true' string.
222+
$value = 'true';
223+
}
224+
}
225+
226+
// Convert iterable values to token lists
227+
if (!$value instanceof AttributeValueInterface && is_iterable($value)) {
228+
if ('style' === $name) {
229+
$value = new InlineStyle($value);
230+
} else {
231+
$value = new SeparatedTokenList($value);
232+
}
233+
}
234+
235+
if ($value instanceof AttributeValueInterface) {
236+
$value = $value->getValue();
237+
}
238+
239+
// In general, ...
240+
if (true === $value) {
241+
// ... use attribute="" for boolean true,
242+
// which is XHTML compliant and indicates the "empty value default", see
243+
// https://html.spec.whatwg.org/multipage/syntax.html#attributes-2 and
244+
// https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#boolean-attributes
245+
$value = '';
246+
}
247+
248+
if (null === $value || false === $value) {
249+
// omit null-valued and false attributes completely (note aria-* has been processed before)
250+
continue;
251+
}
252+
253+
if (\is_object($value) && !$value instanceof \Stringable) {
254+
throw new RuntimeError(\sprintf('The "%s" attribute value should be a scalar, an iterable, or an object implementing "%s", got "%s".', $name, \Stringable::class, get_debug_type($value)));
255+
}
256+
257+
$result .= $runtime->escape($name, 'html_attr_relaxed').'="'.$runtime->escape((string) $value).'" ';
258+
}
259+
260+
return trim($result);
261+
}
128262
}

0 commit comments

Comments
 (0)