Debian Codegraph @

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

raw
1 <?php
2
3 namespace ipl\Html\FormElement;
4
5 use ipl\Html\Attribute;
6 use ipl\Html\Attributes;
7 use ipl\Html\BaseHtmlElement;
8 use ipl\Html\Contract\DecorableFormElement;
9 use ipl\Html\Contract\FormElement;
10 use ipl\Html\Contract\FormElementDecoration;
11 use ipl\Html\Contract\ValueCandidates;
12 use ipl\Html\Form;
13 use ipl\Html\FormDecoration\DecoratorChain;
14 use ipl\Html\FormDecoration\FormElementDecorationResult;
15 use ipl\I18n\Translation;
16 use ipl\Stdlib\Messages;
17 use ipl\Validator\ValidatorChain;
18 use ReflectionProperty;
19
20 /**
21 * Base implementation of a form element
22 *
23 * @phpstan-import-type decoratorsFormat from DecoratorChain
24 */
25 abstract class BaseFormElement extends BaseHtmlElement implements FormElement, ValueCandidates, DecorableFormElement
26 {
27 use Messages;
28 use Translation;
29
30 /** @var string Description of the element */
31 protected $description;
32
33 /** @var string Label of the element */
34 protected $label;
35
36 /** @var string Name of the element */
37 protected $name;
38
39 /** @var bool Whether the element is ignored */
40 protected $ignored = false;
41
42 /** @var bool Whether the element is required */
43 protected $required = false;
44
45 /** @var null|bool Whether the element is valid; null if the element has not been validated yet, bool otherwise */
46 protected $valid;
47
48 /** @var ValidatorChain Registered validators */
49 protected $validators;
50
51 /** @var mixed Value of the element */
52 protected $value;
53
54 /** @var array<int, mixed> Value candidates of the element */
55 protected $valueCandidates = [];
56
57 /** @var ?DecoratorChain<FormElementDecoration> All registered decorators */
58 protected ?DecoratorChain $decorators = null;
59
60 /**
61 * Create a new form element
62 *
63 * @param string $name Name of the form element
64 * @param mixed $attributes Attributes of the form element
65 */
66 public function __construct($name, $attributes = null)
67 {
68 $this->setName($name);
69 $this->init();
70
71 if ($attributes !== null) {
72 $this->addAttributes($attributes);
73 }
74 }
75
76 public function getDescription()
77 {
78 return $this->description;
79 }
80
81 /**
82 * Set the description of the element
83 *
84 * @param string $description
85 *
86 * @return $this
87 */
88 public function setDescription($description)
89 {
90 $this->description = $description;
91
92 return $this;
93 }
94
95 public function getLabel()
96 {
97 return $this->label;
98 }
99
100 /**
101 * Set the label of the element
102 *
103 * @param string $label
104 *
105 * @return $this
106 */
107 public function setLabel($label)
108 {
109 $this->label = $label;
110
111 return $this;
112 }
113
114 public function getName()
115 {
116 return $this->name;
117 }
118
119 /**
120 * Set the name for the element
121 *
122 * @param string $name
123 *
124 * @return $this
125 */
126 public function setName($name)
127 {
128 $this->name = $name;
129
130 return $this;
131 }
132
133 public function isIgnored()
134 {
135 return $this->ignored;
136 }
137
138 /**
139 * Set whether the element is ignored
140 *
141 * @param bool $ignored
142 *
143 * @return $this
144 */
145 public function setIgnored($ignored = true)
146 {
147 $this->ignored = (bool) $ignored;
148
149 return $this;
150 }
151
152 public function isRequired()
153 {
154 return $this->required;
155 }
156
157 /**
158 * Set whether the element is required
159 *
160 * @param bool $required
161 *
162 * @return $this
163 */
164 public function setRequired($required = true)
165 {
166 $this->required = (bool) $required;
167
168 return $this;
169 }
170
171 public function isValid()
172 {
173 if ($this->valid === null) {
174 $this->validate();
175 }
176
177 return $this->valid;
178 }
179
180 /**
181 * Get the validators
182 *
183 * @return ValidatorChain
184 */
185 public function getValidators()
186 {
187 if ($this->validators === null) {
188 $chain = new ValidatorChain();
189 $this->addDefaultValidators($chain);
190 $this->validators = $chain;
191 }
192
193 return $this->validators;
194 }
195
196 /**
197 * Set the validators
198 *
199 * @param iterable $validators
200 *
201 * @return $this
202 */
203 public function setValidators($validators)
204 {
205 $this
206 ->getValidators()
207 ->clearValidators()
208 ->addValidators($validators);
209
210 return $this;
211 }
212
213 /**
214 * Add validators
215 *
216 * @param iterable $validators
217 *
218 * @return $this
219 */
220 public function addValidators($validators)
221 {
222 $this->getValidators()->addValidators($validators);
223
224 return $this;
225 }
226
227 public function hasValue()
228 {
229 $value = $this->getValue();
230
231 return ! Form::isEmptyValue($value);
232 }
233
234 public function getValue()
235 {
236 return $this->value;
237 }
238
239 public function setValue($value)
240 {
241 if ($value === '') {
242 $this->value = null;
243 } else {
244 $this->value = $value;
245 }
246
247 $this->valid = null;
248
249 return $this;
250 }
251
252 public function getValueCandidates()
253 {
254 return $this->valueCandidates;
255 }
256
257 public function setValueCandidates(array $values)
258 {
259 $this->valueCandidates = $values;
260
261 return $this;
262 }
263
264 public function onRegistered(Form $form)
265 {
266 }
267
268 /**
269 * Validate the element using all registered validators
270 *
271 * @return $this
272 */
273 public function validate()
274 {
275 $this->ensureAssembled();
276
277 if (! $this->hasValue()) {
278 if ($this->isRequired()) {
279 $this->setMessages([$this->translate('This field is required.')]);
280 $this->valid = false;
281 } else {
282 $this->valid = true;
283 }
284 } else {
285 $this->valid = $this->getValidators()->isValid($this->getValue());
286 $this->setMessages($this->getValidators()->getMessages());
287 }
288
289 return $this;
290 }
291
292 public function hasBeenValidated()
293 {
294 return $this->valid !== null;
295 }
296
297 /**
298 * Callback for the name attribute
299 *
300 * @return Attribute|string
301 */
302 public function getNameAttribute()
303 {
304 return $this->getName();
305 }
306
307 /**
308 * Callback for the required attribute
309 *
310 * @return Attribute|null
311 */
312 public function getRequiredAttribute()
313 {
314 if ($this->isRequired()) {
315 return new Attribute('required', true);
316 }
317
318 return null;
319 }
320
321 /**
322 * Callback for the value attribute
323 *
324 * @return mixed
325 */
326 public function getValueAttribute()
327 {
328 return $this->getValue();
329 }
330
331 /**
332 * Initialize this form element
333 *
334 * If you want to initialize this element after construction, override this method
335 */
336 protected function init(): void
337 {
338 }
339
340 /**
341 * Add default validators
342 */
343 protected function addDefaultValidators(ValidatorChain $chain): void
344 {
345 }
346
347 protected function registerValueCallback(Attributes $attributes)
348 {
349 $attributes->registerAttributeCallback(
350 'value',
351 [$this, 'getValueAttribute'],
352 [$this, 'setValue']
353 );
354 }
355
356 protected function registerAttributeCallbacks(Attributes $attributes)
357 {
358 $this->registerValueCallback($attributes);
359
360 $attributes
361 ->registerAttributeCallback('label', null, [$this, 'setLabel'])
362 ->registerAttributeCallback('name', [$this, 'getNameAttribute'], [$this, 'setName'])
363 ->registerAttributeCallback('description', null, [$this, 'setDescription'])
364 ->registerAttributeCallback('validators', null, [$this, 'setValidators'])
365 ->registerAttributeCallback('ignore', null, [$this, 'setIgnored'])
366 ->registerAttributeCallback('required', [$this, 'getRequiredAttribute'], [$this, 'setRequired'])
367 ->registerAttributeCallback('decorators', null, [$this, 'setDecorators']);
368
369 $this->registerCallbacks();
370 }
371
372 /** @deprecated Use {@link registerAttributeCallbacks()} instead */
373 protected function registerCallbacks()
374 {
375 }
376
377 /**
378 * @deprecated
379 *
380 * {@see Attributes::get()} does not respect callbacks,
381 * but we need the value of the callback to nest attribute names.
382 */
383 protected function getValueOfNameAttribute()
384 {
385 $attributes = $this->getAttributes();
386
387 $callbacksProperty = new ReflectionProperty(get_class($attributes), 'callbacks');
388 $callbacks = $callbacksProperty->getValue($attributes);
389
390 if (isset($callbacks['name'])) {
391 $name = $callbacks['name']();
392
393 if ($name instanceof Attribute) {
394 return $name->getValue();
395 }
396
397 return $name;
398 }
399
400 return $this->getName();
401 }
402
403 public function getDecorators(): DecoratorChain
404 {
405 if ($this->decorators === null) {
406 $this->decorators = new DecoratorChain(FormElementDecoration::class);
407 }
408
409 return $this->decorators;
410 }
411
412 /**
413 * Set the decorators
414 *
415 * @param decoratorsFormat $decorators
416 *
417 * @return $this
418 */
419 public function setDecorators(array $decorators): static
420 {
421 $this->getDecorators()
422 ->clearDecorators()
423 ->addDecorators($decorators);
424
425 return $this;
426 }
427
428 public function hasDecorators(): bool
429 {
430 return $this->getDecorators()->hasDecorators();
431 }
432
433 public function applyDecoration(): void
434 {
435 $results = new FormElementDecorationResult();
436 foreach ($this->getDecorators() as $decorator) {
437 $decorator->decorateFormElement($results, $this);
438 }
439
440 $wrapper = $results->assemble();
441 if (! $wrapper->isEmpty()) {
442 $this->addWrapper($wrapper);
443 }
444 }
445 }