Debian Codegraph @

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

raw
1 <?php
2
3 namespace ipl\Html\Contract;
4
5 use Evenement\EventEmitterInterface;
6 use InvalidArgumentException;
7
8 interface FormElements extends EventEmitterInterface
9 {
10 /** @var string Event emitted when an element is registered */
11 public const ON_ELEMENT_REGISTERED = 'elementRegistered';
12
13 /**
14 * Get all elements
15 *
16 * @return FormElement[]
17 */
18 public function getElements();
19
20 /**
21 * Get whether the given element exists
22 *
23 * @param string|FormElement $element
24 *
25 * @return bool
26 */
27 public function hasElement(string|FormElement $element);
28
29 /**
30 * Get the element by the given name
31 *
32 * @param string $name
33 *
34 * @return FormElement
35 *
36 * @throws InvalidArgumentException If no element with the given name exists
37 */
38 public function getElement(string $name);
39
40 /**
41 * Add an element
42 *
43 * @param string|FormElement $typeOrElement Type of the element as string or an instance of FormElement
44 * @param null|string $name Name of the element
45 * @param null|array<string, mixed> $options Element options as key-value pairs
46 *
47 * @return $this
48 *
49 * @throws InvalidArgumentException If the element is invalid (e.g., wrong type, no name)
50 */
51 public function addElement(string|FormElement $typeOrElement, ?string $name = null, ?array $options = null);
52
53 /**
54 * Register an element
55 *
56 * Registers the element for value and validation handling but does not add it to the render stack.
57 * Emits event {@see self::ON_ELEMENT_REGISTERED} with the element as parameter.
58 *
59 * @param FormElement $element
60 *
61 * @return $this
62 *
63 * @throws InvalidArgumentException If $element does not provide a name
64 */
65 public function registerElement(FormElement $element);
66
67 /**
68 * Remove an element
69 *
70 * @param string|FormElement $element
71 *
72 * @return $this
73 */
74 public function removeElement(string|FormElement $element);
75
76 /**
77 * Get the value of the element specified by name
78 *
79 * Returns $default if the element does not exist or has no value.
80 *
81 * @param string $name
82 * @param mixed $default
83 *
84 * @return mixed
85 */
86 public function getValue(string $name, mixed $default = null);
87
88 /**
89 * Get the values for all but ignored elements
90 *
91 * @return array<string, mixed> Values as name-value pairs
92 */
93 public function getValues();
94
95 /**
96 * Populate values of registered elements
97 *
98 * @param iterable<string, mixed> $values Values as name-value pairs
99 *
100 * @return $this
101 */
102 public function populate(iterable $values);
103 }