Debian Codegraph @

vendor/ipl/html/src/Attribute.php

raw
1 <?php
2
3 namespace ipl\Html;
4
5 use InvalidArgumentException;
6
7 /**
8 * HTML Attribute
9 *
10 * Every single HTML attribute is (or should be) an instance of this class.
11 * This guarantees that every attribute is safe and escaped correctly.
12 *
13 * Usually attributes are not instantiated directly, but created through an HTML
14 * element's exposed methods.
15 *
16 * @phpstan-type _AttributeScalar string|bool|null
17 * @phpstan-type AttributeValue _AttributeScalar|array<_AttributeScalar>
18 */
19 class Attribute
20 {
21 /** @var string */
22 protected $name;
23
24 /** @var string The separator used if value is an array */
25 protected $separator = ' ';
26
27 /** @var AttributeValue */
28 protected $value;
29
30 /**
31 * Create a new HTML attribute from the given name and value
32 *
33 * @param string $name The name of the attribute
34 * @param AttributeValue $value The value of the attribute
35 *
36 * @throws InvalidArgumentException If the name of the attribute contains special characters
37 */
38 public function __construct($name, $value = null)
39 {
40 $this->setName($name)->setValue($value);
41 }
42
43 /**
44 * Create a new HTML attribute from the given name and value
45 *
46 * @param string $name The name of the attribute
47 * @param AttributeValue $value The value of the attribute
48 *
49 * @return static
50 *
51 * @throws InvalidArgumentException If the name of the attribute contains special characters
52 */
53 public static function create($name, $value)
54 {
55 return new static($name, $value);
56 }
57
58 /**
59 * Create a new empty HTML attribute from the given name
60 *
61 * The value of the attribute will be null after construction.
62 *
63 * @param string $name The name of the attribute
64 *
65 * @return static
66 *
67 * @throws InvalidArgumentException If the name of the attribute contains special characters
68 */
69 public static function createEmpty($name)
70 {
71 return new static($name, null);
72 }
73
74 /**
75 * Sanitize the given ID
76 *
77 * Removes all characters that are not alphanumeric, underscore or hyphen. Additionally,
78 * the result is enforced to not start with a number by prepending the letter 'a'.
79 * Use it if you need to ensure that an ID is safe to use in CSS selectors.
80 *
81 * @param non-empty-string $id
82 *
83 * @return string
84 *
85 * @throws InvalidArgumentException If the ID is an empty string
86 */
87 public static function sanitizeId(string $id): string
88 {
89 if (empty($id)) {
90 throw new InvalidArgumentException('ID must not be empty');
91 }
92
93 return 'a' . preg_replace('/[^a-z0-9_\-]/i', '', $id);
94 }
95
96 /**
97 * Escape the name of an attribute
98 *
99 * Makes sure that the name of an attribute really is a string.
100 *
101 * @param string $name
102 *
103 * @return string
104 */
105 public static function escapeName($name)
106 {
107 return (string) $name;
108 }
109
110 /**
111 * Escape the value of an attribute
112 *
113 * If the value is an array, returns the string representation
114 * of all array elements joined with the specified glue string.
115 *
116 * Values are escaped according to the HTML5 double-quoted attribute value syntax:
117 * {@link https://html.spec.whatwg.org/multipage/syntax.html#attributes-2 }.
118 *
119 * @param string|string[] $value
120 * @param string $glue Glue string to join elements if value is an array
121 *
122 * @return string
123 */
124 public static function escapeValue($value, $glue = ' ')
125 {
126 if (is_array($value)) {
127 $value = implode($glue, $value);
128 }
129
130 // We force double-quoted attribute value syntax so let's start by escaping double quotes
131 $value = str_replace('"', '&quot;', $value);
132
133 // In addition, values must not contain ambiguous ampersands
134 $value = preg_replace_callback(
135 '/&[0-9A-Z]+;/i',
136 function ($match) {
137 $subject = $match[0];
138
139 if (htmlspecialchars_decode($subject, ENT_COMPAT | ENT_HTML5) === $subject) {
140 // Ambiguous ampersand
141 return str_replace('&', '&amp;', $subject);
142 }
143
144 return $subject;
145 },
146 $value
147 );
148
149 return $value;
150 }
151
152 /**
153 * Get the name of the attribute
154 *
155 * @return string
156 */
157 public function getName()
158 {
159 return $this->name;
160 }
161
162 /**
163 * Set the name of the attribute
164 *
165 * @param string $name
166 *
167 * @return $this
168 *
169 * @throws InvalidArgumentException If the name contains special characters
170 */
171 protected function setName($name)
172 {
173 if (! preg_match('/^[a-z][a-z0-9:-]*$/i', $name)) {
174 throw new InvalidArgumentException(sprintf(
175 'Attribute names with special characters are not yet allowed: %s',
176 $name
177 ));
178 }
179
180 $this->name = $name;
181
182 return $this;
183 }
184
185 /**
186 * Get the separator by which multiple values are concatenated with
187 *
188 * @return string
189 */
190 public function getSeparator(): string
191 {
192 return $this->separator;
193 }
194
195 /**
196 * Set the separator to concatenate multiple values with
197 *
198 * @param string $separator
199 *
200 * @return $this
201 */
202 public function setSeparator(string $separator): self
203 {
204 $this->separator = $separator;
205
206 return $this;
207 }
208
209 /**
210 * Get the value of the attribute
211 *
212 * @return AttributeValue
213 */
214 public function getValue()
215 {
216 return $this->value;
217 }
218
219 /**
220 * Set the value of the attribute
221 *
222 * @param AttributeValue $value
223 *
224 * @return $this
225 */
226 public function setValue($value)
227 {
228 $this->value = $value;
229
230 return $this;
231 }
232
233 /**
234 * Add the given value(s) to the attribute
235 *
236 * @param AttributeValue $value The value(s) to add
237 *
238 * @return $this
239 */
240 public function addValue($value)
241 {
242 $this->value = array_merge((array) $this->value, (array) $value);
243
244 return $this;
245 }
246
247 /**
248 * Remove the given value(s) from the attribute
249 *
250 * The current value is set to null if it matches the value to remove
251 * or is in the array of values to remove.
252 *
253 * If the current value is an array, all elements are removed which
254 * match the value(s) to remove.
255 *
256 * Does nothing if there is no such value to remove.
257 *
258 * @param AttributeValue $value The value(s) to remove
259 *
260 * @return $this
261 */
262 public function removeValue($value)
263 {
264 $value = (array) $value;
265
266 $current = $this->getValue();
267
268 if (is_array($current)) {
269 $this->setValue(array_diff($current, $value));
270 } elseif (in_array($current, $value, true)) {
271 $this->setValue(null);
272 }
273
274 return $this;
275 }
276
277 /**
278 * Test and return true if the attribute is boolean, false otherwise
279 *
280 * @return bool
281 */
282 public function isBoolean()
283 {
284 return is_bool($this->value);
285 }
286
287 /**
288 * Test and return true if the attribute is empty, false otherwise
289 *
290 * Null and the empty array will be considered empty.
291 *
292 * @return bool
293 */
294 public function isEmpty()
295 {
296 return $this->value === null || $this->value === [];
297 }
298
299 /**
300 * Render the attribute to HTML
301 *
302 * If the value of the attribute is of type boolean, it will be rendered as
303 * {@link http://www.w3.org/TR/html5/infrastructure.html#boolean-attributes boolean attribute}.
304 * Note that in this case if the value of the attribute is false, the empty string will be returned.
305 *
306 * If the value of the attribute is null or an empty array,
307 * the empty string will be returned as well.
308 *
309 * Escaping of the attribute's value takes place automatically using {@link Attribute::escapeValue()}.
310 *
311 * @return string
312 */
313 public function render()
314 {
315 if ($this->isEmpty()) {
316 return '';
317 }
318
319 if ($this->isBoolean()) {
320 if ($this->value) {
321 return $this->renderName();
322 }
323
324 return '';
325 } else {
326 return sprintf(
327 '%s="%s"',
328 $this->renderName(),
329 $this->renderValue()
330 );
331 }
332 }
333
334 /**
335 * Render the name of the attribute to HTML
336 *
337 * @return string
338 */
339 public function renderName()
340 {
341 return static::escapeName($this->name);
342 }
343
344 /**
345 * Render the value of the attribute to HTML
346 *
347 * @return string
348 */
349 public function renderValue()
350 {
351 return static::escapeValue($this->value, $this->separator);
352 }
353 }