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