FieldConfig.php — Matomo Analytics – Powerful, Privacy-First Insights for WordPress 5.0.3

matomo / app / core / Settings / FieldConfig.php

matomo / app / core / Settings Last commit date

FieldConfig 2 years ago Measurable 2 years ago Plugin 2 years ago Storage 2 years ago FieldConfig.php 2 years ago Setting.php 2 years ago Settings.php 2 years ago

FieldConfig.php

256 lines

1	<?php
2
3	/**
4	* Matomo - free/libre analytics platform
5	*
6	* @link https://matomo.org
7	* @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
8	*
9	*/
10	namespace Piwik\Settings;
11
12	use Piwik\Validators\BaseValidator;
13	/**
14	* Lets you configure a form field.
15	*
16	* @api
17	*/
18	class FieldConfig
19	{
20	/**
21	* Shows a radio field. To use this field assign it to the `$uiControl` property.
22	*/
23	const UI_CONTROL_RADIO = 'radio';
24	/**
25	* Shows a text field. To use this field assign it to the `$uiControl` property.
26	*/
27	const UI_CONTROL_TEXT = 'text';
28	/**
29	* Shows an email text field. To use this field assign it to the `$uiControl` property.
30	*/
31	const UI_CONTROL_EMAIL = 'email';
32	/**
33	* Shows a URL text field. To use this field assign it to the `$uiControl` property.
34	*/
35	const UI_CONTROL_URL = 'url';
36	/**
37	* Shows a text area. To use this field assign it to the `$uiControl` property.
38	*/
39	const UI_CONTROL_TEXTAREA = 'textarea';
40	/**
41	* Shows a checkbox. To use this field assign it to the `$uiControl` property.
42	*/
43	const UI_CONTROL_CHECKBOX = 'checkbox';
44	/**
45	* Shows a password field. To use this field assign it to the `$uiControl` property.
46	*/
47	const UI_CONTROL_PASSWORD = 'password';
48	/**
49	* Shows a select field where a user can select multiple values.
50	* The type "Array" is required for this ui control. To use this field assign it to the `$uiControl` property.
51	*/
52	const UI_CONTROL_MULTI_SELECT = 'multiselect';
53	/**
54	* Shows a select field. To use this field assign it to the `$uiControl` property.
55	*/
56	const UI_CONTROL_SINGLE_SELECT = 'select';
57	/**
58	* Shows an expandable select field which is useful when each selectable value belongs to a group.
59	* To use this field assign it to the `$uiControl` property.
60	*/
61	const UI_CONTROL_SINGLE_EXPANDABLE_SELECT = 'expandable-select';
62	/**
63	* Lets a user configure an array of form fields.
64	*/
65	const UI_CONTROL_FIELD_ARRAY = 'field-array';
66	/**
67	* Lets a user configure two form fields next to each other, and add multiple entries of those two pairs.
68	*/
69	const UI_CONTROL_MULTI_TUPLE = 'multituple';
70	/**
71	* Generates a hidden form field. To use this field assign it to the `$uiControl` property.
72	*/
73	const UI_CONTROL_HIDDEN = 'hidden';
74	/**
75	* Expects an integer value. Is usually used when creating a setting.
76	*/
77	const TYPE_INT = 'integer';
78	/**
79	* Expects a float value. Is usually used when creating a setting.
80	*/
81	const TYPE_FLOAT = 'float';
82	/**
83	* Expects a string. Is usually used when creating a setting.
84	*/
85	const TYPE_STRING = 'string';
86	/**
87	* Expects a boolean. Is usually used when creating a setting.
88	*/
89	const TYPE_BOOL = 'boolean';
90	/**
91	* Expects an array containing multiple values.
92	*/
93	const TYPE_ARRAY = 'array';
94	/**
95	* Describes what HTML element should be used to manipulate the setting through Piwik's UI.
96	*
97	* See {@link Piwik\Plugin\Settings} for a list of supported control types.
98	*
99	* @var string
100	*/
101	public $uiControl = null;
102	/**
103	* Defines a custom Vue component to use for the internal field UI control. This should be an array with two
104	* keys:
105	*
106	* - plugin: the name of the plugin that the UI control exists in.
107	* - name: the name of the export for the component in the plugin's Vue UMD module.
108	*
109	* @var string[]
110	*/
111	public $customFieldComponent;
112	/**
113	* Name-value mapping of HTML attributes that will be added HTML form control, eg,
114	* `array('size' => 3)`. Attributes will be escaped before outputting.
115	*
116	* @var array
117	*/
118	public $uiControlAttributes = array();
119	/**
120	* Makes field full width.
121	* Useful for `$field->uiControl = FieldConfig::UI_CONTROL_MULTI_TUPLE;`
122	*
123	* @var bool
124	*/
125	public $fullWidth = false;
126	/**
127	* The list of all available values for this setting. If null, the setting can have any value.
128	*
129	* If supplied, this field should be an array mapping available values with their prettified
130	* display value. Eg, if set to `array('nb_visits' => 'Visits', 'nb_actions' => 'Actions')`,
131	* the UI will display Visits and Actions, and when the user selects one, Piwik will
132	* set the setting to nb_visits or nb_actions respectively.
133	*
134	* The setting value will be validated if this field is set. If the value is not one of the
135	* available values, an error will be triggered.
136	*
137	* _Note: If a custom validator is supplied (see {@link $validate}), the setting value will
138	* not be validated._
139	*
140	* @var null\|array
141	*/
142	public $availableValues = null;
143	/**
144	* Text that will appear above this setting's section in the _Plugin Settings_ admin page.
145	*
146	* @var null\|string
147	*/
148	public $introduction = null;
149	/**
150	* Text that will appear directly underneath the setting title in the _Plugin Settings_ admin
151	* page. If set, should be a short description of the setting.
152	*
153	* @var null\|string
154	*/
155	public $description = null;
156	/**
157	* Text that will appear next to the setting's section in the _Plugin Settings_ admin page. If set,
158	* it should contain information about the setting that is more specific than a general description,
159	* such as the format of the setting value if it has a special format.
160	*
161	* Be sure to escape any user input as HTML can be used here.
162	*
163	* @var null\|string
164	*/
165	public $inlineHelp = null;
166	/**
167	* A closure that prepares the setting value. If supplied, this closure will be executed before
168	* the setting has been validated.
169	*
170	* Example
171	*
172	* $setting->prepare = function ($value, Setting $setting) {
173	* return mb_strtolower($value);
174	* }
175	*
176	* @var null\|\Closure
177	*/
178	public $prepare = null;
179	/**
180	* A closure that does some custom validation on the setting before the setting is persisted.
181	*
182	* The closure should take two arguments: the setting value and the {@link Setting} instance being
183	* validated. If the value is found to be invalid, the closure should throw an exception with
184	* a message that describes the error.
185	*
186	* Example
187	*
188	* $setting->validate = function ($value, Setting $setting) {
189	* if ($value > 60) {
190	* throw new \Exception('The time limit is not allowed to be greater than 60 minutes.');
191	* }
192	* }
193	*
194	* @var null\|\Closure
195	*/
196	public $validate = null;
197	/**
198	* A closure that transforms the setting value. If supplied, this closure will be executed after
199	* the setting has been validated.
200	*
201	* _Note: If a transform is supplied, the setting's {@link $type} has no effect. This means the
202	* transformation function will be responsible for casting the setting value to the appropriate
203	* data type._
204	*
205	* Example
206	*
207	* $setting->transform = function ($value, Setting $setting) {
208	* if ($value > 30) {
209	* $value = 30;
210	* }
211	*
212	* return (int) $value;
213	* }
214	*
215	* @var null\|\Closure
216	*/
217	public $transform = null;
218	/**
219	* This setting's display name, for example, `'Refresh Interval'`.
220	*
221	* Be sure to escape any user input as HTML can be used here.
222	*
223	* @var string
224	*/
225	public $title = '';
226	/**
227	* Here you can define conditions so that certain form fields will be only shown when a certain condition
228	* is true. This condition is supposed to be evaluated on the client side dynamically. This way you can hide
229	* for example some fields depending on another field. For example if SiteSearch is disabled, fields to enter
230	* site search keywords is not needed anymore and can be disabled.
231	*
232	* For example 'sitesearch', or 'sitesearch && !use_sitesearch_default' where 'sitesearch' and 'use_sitesearch_default'
233	* are both values of fields.
234	*
235	* @var string
236	*/
237	public $condition;
238	/**
239	* Here you can add one or multiple instances of `Piwik\Validators\BaseValidator` to avoid having to
240	* write the same validators over and over again in {@link $validate}.
241	*
242	* Examples
243	* Want to require a value to be set?
244	* $fieldConfig->validators[] = new Piwik\Validators\NotEmpty();
245	*
246	* Want to require an email?
247	* $fieldConfig->validators[] = new Piwik\Validators\NotEmpty();
248	* $fieldConfig->validators[] = new Piwik\Validators\Email();
249	*
250	* The core comes with a set of various validators that can be used.
251	*
252	* @var BaseValidator[]
253	*/
254	public $validators = [];
255	}
256