Debian Codegraph @

vendor/ipl/html/src/BaseHtmlElement.php

raw
1 <?php
2
3 namespace ipl\Html;
4
5 use ipl\Html\Contract\HtmlElementInterface;
6 use RuntimeException;
7
8 /**
9 * Base class for HTML elements
10 *
11 * Extend this class in order to provide concrete HTML elements or series of HTML elements, e.g. widgets.
12 * When extending this class you should provide the element's tag with {@link $tag}. Setting default attributes is
13 * possible via {@link $defaultAttributes}. And the content of the element is provided in {@link assemble()}.
14 *
15 * # Example Usage
16 * ```
17 * namespace Acme\Widgets;
18 *
19 * use ipl\Html\BaseHtmlElement;
20 *
21 * class Dashboard extends BaseHtmlElement
22 * {
23 * protected $defaultAttributes = ['class' => 'acme-dashboard'];
24 *
25 * protected $tag = 'div';
26 *
27 * protected function assemble()
28 * {
29 * // ...
30 * $this->add($content);
31 * }
32 * }
33 * ```
34 */
35 abstract class BaseHtmlElement extends HtmlDocument implements HtmlElementInterface
36 {
37 /**
38 * List of void elements which must not contain end tags or content
39 *
40 * If {@link $isVoid} is null, this property should be used to decide whether the content and end tag has to be
41 * rendered.
42 *
43 * @var array
44 *
45 * @see https://www.w3.org/TR/html5/syntax.html#void-elements
46 */
47 protected static $voidElements = [
48 'area' => 1,
49 'base' => 1,
50 'br' => 1,
51 'col' => 1,
52 'embed' => 1,
53 'hr' => 1,
54 'img' => 1,
55 'input' => 1,
56 'link' => 1,
57 'meta' => 1,
58 'param' => 1,
59 'source' => 1,
60 'track' => 1,
61 'wbr' => 1
62 ];
63
64 /** @var Attributes */
65 protected $attributes;
66
67 /** @var bool Whether possible attribute callbacks have been registered */
68 protected $attributeCallbacksRegistered = false;
69
70 /** @var bool|null Whether the element is void. If null, void check should use {@link $voidElements} */
71 protected $isVoid;
72
73 /** @var array<string, mixed> You may want to set default attributes when extending this class */
74 protected $defaultAttributes;
75
76 /** @var string Tag of element. Set this property in order to provide the element's tag when extending this class */
77 protected $tag;
78
79 public function getAttributes()
80 {
81 if ($this->attributes === null) {
82 $default = $this->getDefaultAttributes();
83 if (empty($default)) {
84 $this->attributes = new Attributes();
85 } else {
86 $this->attributes = Attributes::wantAttributes($default);
87 }
88
89 $this->ensureAttributeCallbacksRegistered();
90 }
91
92 return $this->attributes;
93 }
94
95 public function addAttributes($attributes)
96 {
97 $this->getAttributes()->add($attributes);
98
99 return $this;
100 }
101
102 /**
103 * Set the attributes of the element
104 *
105 * @param Attributes|array|null $attributes
106 *
107 * @return $this
108 */
109 public function setAttributes($attributes)
110 {
111 $this->attributes = Attributes::wantAttributes($attributes);
112
113 $this->attributeCallbacksRegistered = false;
114 $this->ensureAttributeCallbacksRegistered();
115
116 return $this;
117 }
118
119 public function hasAttribute(string $name): bool
120 {
121 return $this->getAttributes()->has($name);
122 }
123
124 public function getAttribute(string $name): Attribute
125 {
126 return $this->getAttributes()->get($name);
127 }
128
129 public function setAttribute($name, $value)
130 {
131 $this->getAttributes()->set($name, $value);
132
133 return $this;
134 }
135
136 public function removeAttribute(string $name, $value = null): ?Attribute
137 {
138 return $this->getAttributes()->remove($name, $value);
139 }
140
141 /**
142 * Get the default attributes of the element
143 *
144 * @return array
145 */
146 public function getDefaultAttributes()
147 {
148 return $this->defaultAttributes;
149 }
150
151 /**
152 * Get the tag of the element
153 *
154 * Since HTML Elements must have a tag, this method throws an exception if the element does not have a tag.
155 *
156 * @return string
157 *
158 * @throws RuntimeException If the element does not have a tag
159 */
160 final public function getTag()
161 {
162 $tag = $this->tag();
163
164 if (! $tag) {
165 throw new RuntimeException('Element must have a tag');
166 }
167
168 return $tag;
169 }
170
171 /**
172 * Set the tag of the element
173 *
174 * @param string $tag
175 *
176 * @return $this
177 */
178 public function setTag($tag)
179 {
180 $this->tag = $tag;
181
182 return $this;
183 }
184
185 /**
186 * Get whether the element is void
187 *
188 * The default void detection which checks whether the element's tag is in the list of void elements according to
189 * https://www.w3.org/TR/html5/syntax.html#void-elements.
190 *
191 * If you want to override this behavior, use {@link setVoid()}.
192 *
193 * @return bool
194 */
195 public function isVoid()
196 {
197 if ($this->isVoid !== null) {
198 return $this->isVoid;
199 }
200
201 $tag = $this->getTag();
202
203 return isset(self::$voidElements[$tag]);
204 }
205
206 /**
207 * Set whether the element is void
208 *
209 * You may use this method to override the default void detection which checks whether the element's tag is in the
210 * list of void elements according to https://www.w3.org/TR/html5/syntax.html#void-elements.
211 *
212 * If you specify null, void detection is reset to its default behavior.
213 *
214 * @param bool|null $void
215 *
216 * @return $this
217 */
218 public function setVoid($void = true)
219 {
220 $this->isVoid = $void === null ?: (bool) $void;
221
222 return $this;
223 }
224
225 /**
226 * Ensure that possible attribute callbacks have been registered
227 *
228 * Note that this method is automatically called in {@link getAttributes()} and {@link setAttributes()}.
229 *
230 * @return $this
231 */
232 public function ensureAttributeCallbacksRegistered()
233 {
234 if (! $this->attributeCallbacksRegistered) {
235 $this->attributeCallbacksRegistered = true;
236 $this->registerAttributeCallbacks($this->attributes);
237 }
238
239 return $this;
240 }
241
242 /**
243 * Render the content of the element to HTML
244 *
245 * @return string
246 */
247 public function renderContent()
248 {
249 return parent::renderUnwrapped();
250 }
251
252 /**
253 * Get whether the closing tag should be rendered
254 *
255 * @return bool True for void elements, false otherwise
256 */
257 public function wantsClosingTag()
258 {
259 // TODO: There is more. SVG and MathML namespaces
260 return ! $this->isVoid();
261 }
262
263 /**
264 * Use this element to wrap the given document
265 *
266 * @param HtmlDocument $document
267 *
268 * @return $this
269 */
270 public function wrap(HtmlDocument $document)
271 {
272 $document->addWrapper($this);
273
274 return $this;
275 }
276
277 /**
278 * Internal method for accessing the tag
279 *
280 * You may override this method in order to provide the tag dynamically
281 *
282 * @return string
283 */
284 protected function tag()
285 {
286 return $this->tag;
287 }
288
289 /**
290 * Register attribute callbacks
291 *
292 * Override this method in order to register attribute callbacks in concrete classes.
293 */
294 protected function registerAttributeCallbacks(Attributes $attributes)
295 {
296 }
297
298 public function addHtml(ValidHtml ...$content)
299 {
300 $this->ensureAssembled();
301
302 parent::addHtml(...$content);
303
304 return $this;
305 }
306
307 /**
308 * @inheritdoc
309 *
310 * @throws RuntimeException If the element does not have a tag or is void but has content
311 */
312 public function renderUnwrapped()
313 {
314 $this->ensureAssembled();
315
316 $tag = $this->getTag();
317 $content = $this->renderContent();
318 $attributes = $this->getAttributes()->render();
319
320 if (strlen($this->contentSeparator)) {
321 $length = strlen($content);
322 if ($length > 0) {
323 if ($content[0] === '<') {
324 $content = $this->contentSeparator . $content;
325 $length++;
326 }
327 if ($content[$length - 1] === '>') {
328 $content .= $this->contentSeparator;
329 }
330 }
331 }
332
333 if (! $this->wantsClosingTag()) {
334 if (strlen($content)) {
335 throw new RuntimeException('Void elements must not have content');
336 }
337
338 return sprintf('<%s%s />', $tag, $attributes);
339 }
340
341 return sprintf(
342 '<%s%s>%s</%s>',
343 $tag,
344 $attributes,
345 $content,
346 $tag
347 );
348 }
349
350 public function __clone()
351 {
352 parent::__clone();
353
354 if ($this->attributes !== null) {
355 $this->attributes = clone $this->attributes;
356 }
357 }
358 }