← All changes | backend/src/ValueObjects/Field/Field.php +320 -73 0.1.2 → 1.5 View file →

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