ivyforms / backend / src / ValueObjects / Field / Field.php

Field.php in The Innovative Form Builder – IvyForms 0.6, at backend/src/ValueObjects/Field/Field.php

531 lines 12.8 KB

Raw Download Zip

1	<?php
2
3	/**
4	* @copyright © TMS-Plugins. All rights reserved.
5	* @licence See LICENCE.md for license details.
6	*/
7
8	namespace IvyForms\ValueObjects\Field;
9
10	// phpcs:disable PSR1.Files.SideEffects
11	if (!defined('ABSPATH')) {
12	exit; // Exit if accessed directly
13	}
14
15	use IvyForms\Common\Exceptions\ValidationException;
16	use IvyForms\Services\Translations\BackendStrings;
17
18	/**
19	* Class Field
20	*
21	* @SuppressWarnings(PHPMD)
22	* @package IvyForms\ValueObjects\Field
23	*/
24	final class Field
25	{
26	/**
27	* @var int
28	*/
29	public int $id;
30	/**
31	* @var int
32	*/
33	public int $formId;
34	/**
35	* @var int
36	*/
37	public int $fieldIndex;
38	/**
39	* @var string
40	*/
41	public string $type;
42	/**
43	* @var int
44	*/
45	public int $position;
46	/**
47	* @var int\|null
48	*/
49	public ?int $parentId;
50	/**
51	* @var FieldGeneralSettings
52	*/
53	public FieldGeneralSettings $generalSettings;
54	/**
55	* @var FieldOptions
56	*/
57	public FieldOptions $fieldOptions;
58	/**
59	* @var int Number of rows (for textarea fields)
60	*/
61	public int $rows;
62	/** @var bool */
63	public bool $confirmFieldEnabled;
64	/** @var string */
65	public string $confirmFieldLabel;
66	/** @var string */
67	public string $confirmFieldPlaceholder;
68	/** @var bool */
69	public bool $confirmFieldHideLabel;
70	/**
71	* @var FieldAdvancedSettings
72	*/
73	public FieldAdvancedSettings $advancedSettings;
74	/**
75	* @var array<string, mixed> Additional properties from Pro plugin
76	*/
77	private array $additionalProperties = [];
78
79	/**
80	* Field constructor.
81	* @SuppressWarnings(PHPMD)
82	*
83	* @param int $id
84	* @param int $formId
85	* @param int $fieldIndex
86	* @param string $type
87	* @param int $position
88	* @param int\|null $parentId
89	* @param FieldGeneralSettings $generalSettings
90	* @param FieldOptions $fieldOptions
91	* @param FieldAdvancedSettings $advancedSettings
92	* @param int $rows
93	* @param bool $confirmFieldEnabled
94	* @param string $confirmFieldLabel
95	* @param string $confirmFieldPlaceholder
96	* @param bool $confirmFieldHideLabel
97	*
98	* @throws ValidationException
99	*/
100	public function __construct(
101	int $id,
102	int $formId,
103	int $fieldIndex,
104	string $type,
105	int $position,
106	FieldGeneralSettings $generalSettings,
107	FieldOptions $fieldOptions,
108	FieldAdvancedSettings $advancedSettings,
109	?int $parentId = null,
110	int $rows = 0,
111	bool $confirmFieldEnabled = false,
112	string $confirmFieldLabel = '',
113	string $confirmFieldPlaceholder = '',
114	bool $confirmFieldHideLabel = false
115	) {
116	$this->id = $this->validateId($id);
117	$this->formId = $this->validateId($formId);
118	$this->fieldIndex = $this->validateId($fieldIndex);
119	$this->type = $this->validateString($type, 50, 'type');
120	$this->position = $this->validatePosition($position);
121	$this->parentId = $this->validateParentId($parentId);
122	$this->generalSettings = $generalSettings;
123	$this->fieldOptions = $fieldOptions;
124	$this->advancedSettings = $advancedSettings;
125	$this->rows = $this->validateRows($rows);
126	$this->confirmFieldEnabled = $this->validateBool($confirmFieldEnabled);
127	$this->confirmFieldLabel = $this->validateString(
128	$confirmFieldLabel,
129	255,
130	'confirmFieldLabel'
131	);
132	$this->confirmFieldPlaceholder = $this->validateString(
133	$confirmFieldPlaceholder,
134	255,
135	'confirmFieldPlaceholder'
136	);
137	$this->confirmFieldHideLabel = $this->validateBool($confirmFieldHideLabel);
138
139	/**
140	* Allows initialization of additional properties for the Field value object.
141	* @since 0.1.0
142	*
143	* @param mixed[] $additionalProperties The current list of additional properties.
144	* @param Field $field The Field value object instance.
145	* @return mixed[] The modified list of additional properties.
146	*/
147	$this->additionalProperties =
148	apply_filters('ivyforms/field/value_object/init_additional_properties', [], $this);
149	}
150
151	/**
152	* Set an additional property
153	*
154	* @param string $key
155	* @param mixed $value
156	*
157	* @return void
158	*/
159	public function setAdditionalProperty(string $key, $value): void
160	{
161	foreach ($this->additionalProperties as &$property) {
162	if (array_key_exists($key, $property)) {
163	$property[$key] = $value; // update existing
164	return;
165	}
166	}
167
168	// if not found, append new key-value pair
169	$this->additionalProperties[] = [$key => $value];
170	}
171
172	/**
173	* Get an additional property
174	*
175	* @param string $key
176	* @return mixed\|null The value of the additional property, or null if not found
177	*/
178	public function getAdditionalProperty(string $key)
179	{
180	foreach ($this->additionalProperties as $property) {
181	if (array_key_exists($key, $property)) {
182	return $property[$key];
183	}
184	}
185	return null;
186	}
187
188	/**
189	* Get all additional properties
190	*
191	* @return array<string, mixed> The additional properties
192	*/
193	public function getAllAdditionalProperties(): array
194	{
195	return $this->additionalProperties;
196	}
197
198	/**
199	* Validates the ID.
200	*
201	* @param int $id
202	*
203	* @return int
204	* @throws ValidationException
205	*/
206	public function validateId(int $id): int
207	{
208	if ($id < 0) {
209	throw new ValidationException(BackendStrings::getExceptionStrings()['id_positive_integer']);
210	}
211	return $id;
212	}
213
214	/**
215	* Validates parent id which can be null or non-negative int.
216	*
217	* @param int\|null $parentId
218	*
219	* @return int\|null
220	* @throws ValidationException
221	*/
222	private function validateParentId(?int $parentId): ?int
223	{
224	if ($parentId === null) {
225	return null;
226	}
227	if ($parentId < 0) {
228	throw new ValidationException(BackendStrings::getExceptionStrings()['parentId_positive_integer']);
229	}
230	return $parentId;
231	}
232
233	/**
234	* Validates a string value.
235	*
236	* @param string $value
237	* @param int $maxLength
238	* @param string $fieldName
239	*
240	* @return string
241	*
242	* @throws ValidationException
243	*/
244	private function validateString(string $value, int $maxLength, string $fieldName): string
245	{
246	if (strlen($value) > $maxLength) {
247	throw new ValidationException(
248	sprintf(
249	/* translators: 1: String value, 2: String max length. */
250	esc_html__('%1$s must be at most %2$d characters.', 'ivyforms'),
251	esc_html($fieldName),
252	$maxLength
253	)
254	);
255	}
256	return $value;
257	}
258
259	/**
260	* Validates the position.
261	*
262	* @param int $value
263	*
264	* @return int
265	*
266	* @throws ValidationException
267	*/
268	private function validatePosition(int $value): int
269	{
270	if ($value < 0) {
271	throw new ValidationException(
272	esc_html__('position must be a non-negative integer.', 'ivyforms')
273	);
274	}
275	return $value;
276	}
277
278	/**
279	* Validates a boolean field.
280	*
281	* @param bool $value
282	*
283	* @return bool
284	*/
285	private function validateBool(bool $value): bool
286	{
287	return $value;
288	}
289
290	/**
291	* Validate rows.
292	*
293	* @param int $rows
294	* @return int
295	* @throws ValidationException
296	*/
297	private function validateRows(int $rows): int
298	{
299	if ($rows < 0) {
300	throw new ValidationException(
301	esc_html__('rows must be at least 1.', 'ivyforms')
302	);
303	}
304	return $rows;
305	}
306
307	/**
308	* Get the form ID.
309	*
310	* @return int
311	*/
312	public function getFormId(): int
313	{
314	return $this->formId;
315	}
316
317	/**
318	* Get the field ID.
319	*
320	* @return int
321	*/
322	public function getId(): int
323	{
324	return $this->id;
325	}
326
327	/**
328	* Get the field index.
329	*
330	* @return int
331	*/
332	public function getIndex(): int
333	{
334	return $this->fieldIndex;
335	}
336
337	/**
338	* Get the field type.
339	*
340	* @return string
341	*/
342	public function getType(): string
343	{
344	return $this->type;
345	}
346
347	/**
348	* Get the field position.
349	*
350	* @return int
351	*/
352	public function getPosition(): int
353	{
354	return $this->position;
355	}
356
357	/**
358	* Get the parent field id.
359	*
360	* @return int\|null
361	*/
362	public function getParentId(): ?int
363	{
364	return $this->parentId;
365	}
366
367	/**
368	* Get the general settings object.
369	*
370	* @return FieldGeneralSettings
371	*/
372	public function getGeneralSettings(): FieldGeneralSettings
373	{
374	return $this->generalSettings;
375	}
376
377	/**
378	* Get the field options.
379	*
380	* @return FieldOptions
381	*/
382	public function getFieldOptions(): FieldOptions
383	{
384	return $this->fieldOptions;
385	}
386
387	/**
388	* Get number of rows.
389	* @return int
390	*/
391	public function getRows(): int
392	{
393	return $this->rows;
394	}
395
396	/**
397	* Set number of rows.
398	* @param int $rows
399	*/
400	public function setRows(int $rows): void
401	{
402	$this->rows = $rows;
403	}
404
405	/**
406	* Check if the confirm field feature is enabled.
407	*
408	* @return bool
409	*/
410	public function isConfirmFieldEnabled(): bool
411	{
412	return $this->confirmFieldEnabled;
413	}
414
415	/**
416	* Get the confirm field label.
417	*
418	* @return string
419	*/
420	public function getConfirmFieldLabel(): string
421	{
422	return $this->confirmFieldLabel;
423	}
424
425	/**
426	* Get the confirm field placeholder.
427	*
428	* @return string
429	*/
430	public function getConfirmFieldPlaceholder(): string
431	{
432	return $this->confirmFieldPlaceholder;
433	}
434
435	/**
436	* Check if the confirm field label should be hidden.
437	*
438	* @return bool
439	*/
440	public function isConfirmFieldHideLabel(): bool
441	{
442	return $this->confirmFieldHideLabel;
443	}
444
445	/**
446	* Set the confirm field feature enabled/disabled.
447	*
448	* @param bool $enabled
449	*/
450	public function setConfirmFieldEnabled(bool $enabled): void
451	{
452	$this->confirmFieldEnabled = $enabled;
453	}
454
455	/**
456	* Set the confirm field label.
457	*
458	* @param string $label
459	*/
460	public function setConfirmFieldLabel(string $label): void
461	{
462	$this->confirmFieldLabel = $label;
463	}
464
465	/**
466	* Set the confirm field placeholder.
467	*
468	* @param string $ph
469	*/
470	public function setConfirmFieldPlaceholder(string $ph): void
471	{
472	$this->confirmFieldPlaceholder = $ph;
473	}
474
475	/**
476	* Set the confirm field label visibility.
477	*
478	* @param bool $hide
479	*/
480	public function setConfirmFieldHideLabel(bool $hide): void
481	{
482	$this->confirmFieldHideLabel = $hide;
483	}
484
485	/**
486	* Get the general settings object.
487	*
488	* @return FieldAdvancedSettings
489	*/
490	public function getAdvancedSettings(): FieldAdvancedSettings
491	{
492	return $this->advancedSettings;
493	}
494
495	/**
496	* Convert the field to an array.
497	*
498	* @return array<string, mixed>
499	*/
500	public function toArray(): array
501	{
502	$data = [
503	'id' => $this->id,
504	'formId' => $this->formId,
505	'fieldIndex' => $this->fieldIndex,
506	'type' => $this->type,
507	'position' => $this->position,
508	'parentId' => $this->parentId,
509	'generalSettings' => $this->generalSettings->toArray(),
510	'fieldOptions' => $this->fieldOptions->toArray(),
511	'rows' => $this->rows,
512	'confirmFieldEnabled' => $this->confirmFieldEnabled,
513	'confirmFieldLabel' => $this->confirmFieldLabel,
514	'confirmFieldPlaceholder' => $this->confirmFieldPlaceholder,
515	'confirmFieldHideLabel' => $this->confirmFieldHideLabel,
516	// Advanced options
517	'advancedSettings' => $this->advancedSettings->toArray()
518	];
519
520	/**
521	* Allows modification of the array representation of the Field value object.
522	* @since 0.1.0
523	*
524	* @param mixed[] $data The current array representation of the Field value object.
525	* @param Field $field The Field value object instance.
526	* @return mixed[] The modified array representation of the Field value object.
527	*/
528	return apply_filters('ivyforms/field/value_object/add_to_array_additional_properties', $data, $this);
529	}
530	}
531