1	<?php
2	declare(strict_types=1);
3	/**
4	* Pop PHP Framework (https://www.popphp.org/)
5	*
6	* @link       https://github.com/popphp/popphp-framework
7	* @author     Nick Sagona, III <nick@popphp.org>
8	* @copyright  Copyright (c) 2009-2026 Nick Sagona, III
9	* @license    https://www.popphp.org/license     New BSD License
10	*/
11
12	/**
13	* @namespace
14	*/
15	namespace Pop\Form\Element;
16
17	/**
18	* Form element interface
19	*
20	* @category   Pop
21	* @package    Pop\Form
22	* @author     Nick Sagona, III <nick@popphp.org>
23	* @copyright  Copyright (c) 2009-2026 Nick Sagona, III
24	* @license    https://www.popphp.org/license     New BSD License
25	* @version    5.0.0
26	*/
27	interface ElementInterface
28	{
29
30	/**
31	* Set the name of the form element
32	*
33	* @param  string $name
34	* @return ElementInterface
35	*/
36	public function setName(string $name): ElementInterface;
37
38	/**
39	* Set the value of the form element
40	*
41	* @param  mixed $value
42	* @return ElementInterface
43	*/
44	public function setValue(mixed $value = null): ElementInterface;
45
46	/**
47	* Reset the value of the form element
48	*
49	* @return ElementInterface
50	*/
51	public function resetValue(): ElementInterface;
52
53	/**
54	* Set the label of the form element
55	*
56	* @param  string $label
57	* @return ElementInterface
58	*/
59	public function setLabel(string $label): ElementInterface;
60
61	/**
62	* Set the attributes of the label of the form element
63	*
64	* @param  array $attribs
65	* @return ElementInterface
66	*/
67	public function setLabelAttributes(array $attribs): ElementInterface;
68
69	/**
70	* Set whether the form element is required
71	*
72	* @param  bool    $required
73	* @param  ?string $requiredMessage
74	* @return ElementInterface
75	*/
76	public function setRequired(bool $required, ?string $requiredMessage = 'This field is required.'): ElementInterface;
77
78	/**
79	* Set whether the form element is disabled
80	*
81	* @param  bool $disabled
82	* @return ElementInterface
83	*/
84	public function setDisabled(bool $disabled): ElementInterface;
85
86	/**
87	* Set whether the form element is readonly
88	*
89	* @param  bool $readonly
90	* @return ElementInterface
91	*/
92	public function setReadonly(bool $readonly): ElementInterface;
93
94	/**
95	* Set error to display before the element
96	*
97	* @param  bool $pre
98	* @return ElementInterface
99	*/
100	public function setErrorPre(bool $pre): ElementInterface;
101
102	/**
103	* Determine if error to display before the element
104	*
105	* @return bool
106	*/
107	public function isErrorPre(): bool;
108
109	/**
110	* Set validators
111	*
112	* @param  array $validators
113	* @return ElementInterface
114	*/
115	public function setValidators(array $validators = []): ElementInterface;
116
117	/**
118	* Clear errors
119	*
120	* @return ElementInterface
121	*/
122	public function clearErrors(): ElementInterface;
123
124	/**
125	* Get form element name
126	*
127	* @return ?string
128	*/
129	public function getName(): ?string;
130
131	/**
132	* Get form element object type
133	*
134	* @return ?string
135	*/
136	public function getType(): ?string;
137
138	/**
139	* Get form element value
140	*
141	* @return mixed
142	*/
143	public function getValue(): mixed;
144
145	/**
146	* Get form element label
147	*
148	* @return ?string
149	*/
150	public function getLabel(): ?string;
151
152	/**
153	* Get the attributes of the form element label
154	*
155	* @return array
156	*/
157	public function getLabelAttributes(): array;
158
159	/**
160	* Get validators
161	*
162	* @return array
163	*/
164	public function getValidators(): array;
165
166	/**
167	* Get whether the form element is required
168	*
169	* @return bool
170	*/
171	public function isRequired(): bool;
172
173	/**
174	* Get whether the form element is disabled
175	*
176	* @return bool
177	*/
178	public function isDisabled(): bool;
179
180	/**
181	* Get whether the form element is readonly
182	*
183	* @return bool
184	*/
185	public function isReadonly(): bool;
186
187	/**
188	* Get whether the form element object is a button
189	*
190	* @return bool
191	*/
192	public function isButton(): bool;
193
194	/**
195	* Get form element errors
196	*
197	* @return array
198	*/
199	public function getErrors(): array;
200
201	/**
202	* Get if form element has errors
203	*
204	* @return bool
205	*/
206	public function hasErrors(): bool;
207
208	/**
209	* Add a validator the form element
210	*
211	* @param  mixed $validator
212	* @return ElementInterface
213	*/
214	public function addValidator(mixed $validator): ElementInterface;
215
216	/**
217	* Validate the value
218	*
219	* @param  mixed $value
220	* @param  array $formValues
221	* @return void
222	*/
223	public function validateValue(mixed $value, array $formValues = []): void;
224
225	/**
226	* Validate the value by callable
227	*
228	* @param  callable $validator
229	* @param  mixed    $value
230	* @param  array    $formValues
231	* @return void
232	*/
233	public function validateCallable(callable $validator, mixed $value, array $formValues = []): void;
234
235	/**
236	* Validate the form element
237	*
238	* @param  array $formValues
239	* @return bool
240	*/
241	public function validate(array $formValues = []): bool;
242
243	}