Debian Codegraph @

vendor/ipl/html/src/FormElement/FormElements.php

raw
1 <?php
2
3 namespace ipl\Html\FormElement;
4
5 use InvalidArgumentException;
6 use ipl\Html\Contract\DecorableFormElement;
7 use ipl\Html\Contract\DefaultFormElementDecoration;
8 use ipl\Html\Contract\FormElement;
9 use ipl\Html\Contract\FormElementDecoration;
10 use ipl\Html\Contract\FormElementDecorator;
11 use ipl\Html\Contract\ValueCandidates;
12 use ipl\Html\Form;
13 use ipl\Html\FormDecoration\DecoratorChain;
14 use ipl\Html\FormDecorator\DecoratorInterface;
15 use ipl\Html\HtmlDocument;
16 use ipl\Html\ValidHtml;
17 use ipl\Stdlib\Events;
18 use ipl\Stdlib\Plugins;
19 use RuntimeException;
20 use UnexpectedValueException;
21 use WeakMap;
22
23 use function ipl\Stdlib\get_php_type;
24
25 /**
26 * @phpstan-import-type decoratorsFormat from DecoratorChain
27 * @phpstan-import-type loaderPaths from DefaultFormElementDecoration
28 */
29 trait FormElements
30 {
31 use Events;
32 use Plugins;
33
34 /** @var FormElementDecorator|null */
35 private $defaultElementDecorator;
36
37 /** @var bool Whether the default element decorator loader has been registered */
38 protected $defaultElementDecoratorLoaderRegistered = false;
39
40 /** @var bool Whether the default element loader has been registered */
41 protected $defaultElementLoaderRegistered = false;
42
43 /** @var ?WeakMap<FormElement & DecorableFormElement, bool> The decorated elements */
44 private ?WeakMap $decoratedElements = null;
45
46 /**
47 * Custom Element decorator loader paths
48 *
49 * Override this property to add custom decorator loader paths.
50 *
51 * @var loaderPaths
52 */
53 protected array $elementDecoratorLoaderPaths = [];
54
55 /**
56 * Default element decorators
57 *
58 * Override this property to change the default decorators of the elements.
59 *
60 * Please see {@see DecoratorChain::addDecorators()} for the supported array formats.
61 *
62 * @var decoratorsFormat
63 */
64 protected array $defaultElementDecorators = [];
65
66 /** @var FormElement[] */
67 private $elements = [];
68
69 /** @var array<string, array<int, mixed>> */
70 private $populatedValues = [];
71
72 /**
73 * Get the default element decorators.
74 *
75 * @return decoratorsFormat
76 */
77 public function getDefaultElementDecorators(): array
78 {
79 return $this->defaultElementDecorators;
80 }
81
82 public function setDefaultElementDecorators(array $decorators): static
83 {
84 if ($this->hasDefaultElementDecorator()) {
85 throw new RuntimeException(sprintf(
86 'Cannot use element decorators of type %s and legacy decorator of type %s together',
87 FormElementDecoration::class,
88 FormElementDecorator::class
89 ));
90 }
91
92 $this->defaultElementDecorators = $decorators;
93
94 return $this;
95 }
96
97 public function addElementDecoratorLoaderPaths(array $loaderPaths): static
98 {
99 $this->elementDecoratorLoaderPaths = $loaderPaths;
100
101 return $this;
102 }
103
104 public function getElements()
105 {
106 return $this->elements;
107 }
108
109 public function hasElement($element)
110 {
111 if (is_string($element)) {
112 return array_key_exists($element, $this->elements);
113 }
114
115 if ($element instanceof FormElement) {
116 return in_array($element, $this->elements, true);
117 }
118
119 return false;
120 }
121
122 public function getElement($name)
123 {
124 if (! array_key_exists($name, $this->elements)) {
125 throw new InvalidArgumentException(sprintf(
126 "Can't get element '%s'. Element does not exist",
127 $name
128 ));
129 }
130
131 return $this->elements[$name];
132 }
133
134 public function addElement($typeOrElement, $name = null, $options = null)
135 {
136 if (is_string($typeOrElement)) {
137 if ($name === null) {
138 throw new InvalidArgumentException(sprintf(
139 '%s expects parameter 2 to be set if parameter 1 is a string',
140 __METHOD__
141 ));
142 }
143
144 $element = $this->createElement($typeOrElement, $name, $options);
145 } elseif ($typeOrElement instanceof FormElement) {
146 $element = $typeOrElement;
147 } else {
148 throw new InvalidArgumentException(sprintf(
149 '%s() expects parameter 1 to be a string or an instance of %s, %s given',
150 __METHOD__,
151 FormElement::class,
152 get_php_type($typeOrElement)
153 ));
154 }
155
156 $this
157 ->registerElement($element) // registerElement() must be called first because of the name check
158 ->decorate($element)
159 ->addHtml($element);
160
161 return $this;
162 }
163
164 /**
165 * Create an element
166 *
167 * @param string $type Type of the element
168 * @param string $name Name of the element
169 * @param mixed $options Element options as key-value pairs
170 *
171 * @return FormElement
172 *
173 * @throws InvalidArgumentException If the type of the element is unknown
174 */
175 public function createElement($type, $name, $options = null)
176 {
177 $this->ensureDefaultElementLoaderRegistered();
178
179 $class = $this->loadPlugin('element', $type);
180
181 if (! $class) {
182 throw new InvalidArgumentException(sprintf(
183 "Can't create element of unknown type '%s",
184 $type
185 ));
186 }
187
188 /** @var FormElement $element */
189 $element = new $class($name);
190
191 if ($element instanceof DecorableFormElement) {
192 $customDecoratorPaths = $this->elementDecoratorLoaderPaths;
193 $elementDecoratorChain = $element->getDecorators();
194 if (! empty($customDecoratorPaths)) {
195 if ($element instanceof DefaultFormElementDecoration) {
196 $element->addElementDecoratorLoaderPaths($customDecoratorPaths);
197 }
198
199 foreach ($customDecoratorPaths as $path) {
200 $elementDecoratorChain->addDecoratorLoader($path[0], $path[1] ?? '');
201 }
202 }
203
204 $defaultDecorators = $this->getDefaultElementDecorators();
205 if (
206 ! empty($defaultDecorators)
207 && ! $this->hasDefaultElementDecorator()
208 && empty($options['hidden'])
209 && ! $element instanceof HiddenElement
210 && $element->getAttributes()->get('hidden')->isEmpty()
211 ) {
212 if ($element instanceof DefaultFormElementDecoration) {
213 $element->setDefaultElementDecorators($defaultDecorators);
214 }
215
216 if (! isset($options['decorators'])) {
217 $elementDecoratorChain->addDecorators($defaultDecorators);
218 }
219 }
220 }
221
222 if ($options !== null) {
223 $element->addAttributes($options);
224 }
225
226 return $element;
227 }
228
229 public function registerElement(FormElement $element)
230 {
231 $name = $element->getName();
232
233 if ($name === null) {
234 throw new InvalidArgumentException(sprintf(
235 '%s expects the element to provide a name',
236 __METHOD__
237 ));
238 }
239
240 $this->elements[$name] = $element;
241
242 if (array_key_exists($name, $this->populatedValues)) {
243 $element->setValue($this->populatedValues[$name][count($this->populatedValues[$name]) - 1]);
244
245 if ($element instanceof ValueCandidates) {
246 $element->setValueCandidates($this->populatedValues[$name]);
247 }
248 }
249
250 $this->onElementRegistered($element);
251 $this->emit(Form::ON_ELEMENT_REGISTERED, [$element]);
252
253 return $this;
254 }
255
256 /**
257 * Get whether a default element decorator exists
258 *
259 * @return bool
260 * @deprecated This is not of general use anymore. The new decorator implementation handles defaults entirely
261 * internally now. Use {@see getDefaultElementDecorators()} instead only if you absolutely have to.
262 */
263 public function hasDefaultElementDecorator()
264 {
265 return $this->defaultElementDecorator !== null;
266 }
267
268 /**
269 * Get the default element decorator, if any
270 *
271 * @return FormElementDecorator|null
272 * @deprecated Use {@see getDefaultElementDecorators()} instead
273 */
274 public function getDefaultElementDecorator()
275 {
276 return $this->defaultElementDecorator;
277 }
278
279 /**
280 * Set the default element decorator
281 *
282 * If $decorator is a string, the decorator will be automatically created from a registered decorator loader.
283 * A loader for the namespace ipl\\Html\\FormDecorator is automatically registered by default.
284 * See {@link addDecoratorLoader()} for registering a custom loader.
285 *
286 * @param FormElementDecorator|string $decorator
287 *
288 * @return $this
289 *
290 * @deprecated Use {@see setDefaultElementDecorators()} instead
291 * @throws InvalidArgumentException If $decorator is a string and can't be loaded from registered decorator loaders
292 * or if a decorator loader does not return an instance of
293 * {@link FormElementDecorator}
294 */
295 public function setDefaultElementDecorator($decorator)
296 {
297 if (! empty($this->getDefaultElementDecorators())) {
298 throw new RuntimeException(sprintf(
299 'Cannot use element decorators of type %s and legacy decorator of type %s together',
300 FormElementDecoration::class,
301 FormElementDecorator::class
302 ));
303 }
304
305 if ($decorator instanceof FormElementDecorator || $decorator instanceof DecoratorInterface) {
306 $this->defaultElementDecorator = $decorator;
307 } else {
308 $this->ensureDefaultElementDecoratorLoaderRegistered();
309
310 $class = $this->loadPlugin('decorator', $decorator);
311 if (! $class) {
312 throw new InvalidArgumentException(sprintf(
313 "Can't create decorator of unknown type '%s",
314 $decorator
315 ));
316 }
317
318 $d = new $class();
319 if (! $d instanceof FormElementDecorator && ! $d instanceof DecoratorInterface) {
320 throw new InvalidArgumentException(sprintf(
321 "Expected instance of %s for decorator '%s',"
322 . " got %s from a decorator loader instead",
323 FormElementDecorator::class,
324 $decorator,
325 get_php_type($d)
326 ));
327 }
328
329 $this->defaultElementDecorator = $d;
330 }
331
332 return $this;
333 }
334
335 public function getValue($name, $default = null)
336 {
337 if ($this->hasElement($name)) {
338 $value = $this->getElement($name)->getValue();
339 if ($value !== null) {
340 return $value;
341 }
342 }
343
344 return $default;
345 }
346
347 public function getValues()
348 {
349 $values = [];
350 foreach ($this->getElements() as $element) {
351 if (! $element->isIgnored()) {
352 $values[$element->getName()] = $element->getValue();
353 }
354 }
355
356 return $values;
357 }
358
359 public function populate($values)
360 {
361 foreach ($values as $name => $value) {
362 $this->populatedValues[$name][] = $value;
363 if ($this->hasElement($name)) {
364 $this->getElement($name)->setValue($value);
365 }
366 }
367
368 return $this;
369 }
370
371 /**
372 * Get the populated value of the element specified by name
373 *
374 * Returns $default if there is no populated value for this element.
375 *
376 * @param string $name
377 * @param mixed $default
378 *
379 * @return mixed
380 */
381 public function getPopulatedValue($name, $default = null)
382 {
383 return isset($this->populatedValues[$name])
384 ? $this->populatedValues[$name][count($this->populatedValues[$name]) - 1]
385 : $default;
386 }
387
388 /**
389 * Clear populated value of the given element
390 *
391 * @param string $name
392 *
393 * @return $this
394 */
395 public function clearPopulatedValue($name)
396 {
397 if (isset($this->populatedValues[$name])) {
398 unset($this->populatedValues[$name]);
399 }
400
401 return $this;
402 }
403
404 /**
405 * Add all elements from the given element collection
406 *
407 * @param Form $form
408 *
409 * @return $this
410 */
411 public function addElementsFrom($form)
412 {
413 foreach ($form->getElements() as $element) {
414 $this->addElement($element);
415 }
416
417 return $this;
418 }
419
420 /**
421 * Add a decorator loader
422 *
423 * @param string $namespace Namespace of the decorators
424 * @param ?string $postfix Decorator name postfix, if any
425 *
426 * @return $this
427 * @deprecated Use {@see addElementDecoratorLoaderPaths()} instead
428 */
429 public function addDecoratorLoader(string $namespace, ?string $postfix = null): static
430 {
431 $this->addPluginLoader('decorator', $namespace, $postfix);
432
433 return $this;
434 }
435
436 /**
437 * Add an element loader
438 *
439 * @param string $namespace Namespace of the elements
440 * @param ?string $postfix Element name postfix, if any
441 *
442 * @return $this
443 */
444 public function addElementLoader(string $namespace, ?string $postfix = null): static
445 {
446 $this->addPluginLoader('element', $namespace, $postfix);
447
448 return $this;
449 }
450
451 /**
452 * Ensure that our default element decorator loader is registered
453 *
454 * @return $this
455 */
456 protected function ensureDefaultElementDecoratorLoaderRegistered()
457 {
458 if (! $this->defaultElementDecoratorLoaderRegistered) {
459 $this->addDefaultPluginLoader(
460 'decorator',
461 'ipl\\Html\\FormDecorator',
462 'Decorator'
463 );
464
465 $this->defaultElementDecoratorLoaderRegistered = true;
466 }
467
468 return $this;
469 }
470
471 /**
472 * Ensure that our default element loader is registered
473 *
474 * @return $this
475 */
476 protected function ensureDefaultElementLoaderRegistered()
477 {
478 if (! $this->defaultElementLoaderRegistered) {
479 $this->addDefaultPluginLoader('element', __NAMESPACE__, 'Element');
480
481 $this->defaultElementLoaderRegistered = true;
482 }
483
484 return $this;
485 }
486
487 /**
488 * Decorate the given element
489 *
490 * @param FormElement $element
491 *
492 * @return $this
493 *
494 * @throws UnexpectedValueException If the default decorator is set but not an instance of
495 * {@link FormElementDecorator}
496 */
497 protected function decorate(FormElement $element)
498 {
499 if ($element instanceof DecorableFormElement && $element->hasDecorators()) {
500 // new decorator implementation in use
501 $this->decoratedElements ??= new WeakMap();
502 if (! isset($this->decoratedElements[$element])) {
503 $this->decoratedElements[$element] = false;
504 }
505
506 return $this;
507 }
508
509 if ($this->hasDefaultElementDecorator()) {
510 $decorator = $this->getDefaultElementDecorator();
511
512 if (! $decorator instanceof FormElementDecorator && ! $decorator instanceof DecoratorInterface) {
513 throw new UnexpectedValueException(sprintf(
514 '%s expects the default decorator to be an instance of %s, got %s instead',
515 __METHOD__,
516 FormElementDecorator::class,
517 get_php_type($decorator)
518 ));
519 }
520
521 $decorator->decorate($element);
522 }
523
524 return $this;
525 }
526
527 public function isValidEvent($event)
528 {
529 return in_array($event, [
530 Form::ON_SUBMIT,
531 Form::ON_SENT,
532 Form::ON_ERROR,
533 Form::ON_REQUEST,
534 Form::ON_VALIDATE,
535 Form::ON_ELEMENT_REGISTERED,
536 ]);
537 }
538
539 public function removeElement(string|FormElement $element)
540 {
541 if (is_string($element)) {
542 if (! $this->hasElement($element)) {
543 return $this;
544 }
545
546 $element = $this->getElement($element);
547 }
548
549 return $this->remove($element);
550 }
551
552 public function remove(ValidHtml $content)
553 {
554 if ($content instanceof FormElement) {
555 if ($this->hasElement($content)) {
556 if (isset($this->decoratedElements[$content])) {
557 unset($this->decoratedElements[$content]);
558 }
559
560 $name = array_search($content, $this->elements, true);
561 if ($name !== false) {
562 unset($this->elements[$name]);
563 }
564 }
565 }
566
567 return parent::remove($content);
568 }
569
570 protected function beforeRender(): void
571 {
572 if ($this instanceof HtmlDocument) {
573 parent::beforeRender();
574 }
575
576 foreach ($this->decoratedElements ?? [] as $element => &$decorated) {
577 if (! $decorated) {
578 $element->applyDecoration();
579 $decorated = true;
580 }
581 }
582 }
583
584 /**
585 * Handler which is called after an element has been registered
586 *
587 * @param FormElement $element
588 */
589 protected function onElementRegistered(FormElement $element)
590 {
591 }
592 }