1: <?php
2: /**
3: * This file contains the declaration of the interface ISettingsManager for working with settings.
4: *
5: * @package System
6: *
7: * @author Oleg Schildt
8: */
9:
10: namespace SmartFactory\Interfaces;
11:
12: /**
13: * Interface for working with settings.
14: *
15: * @author Oleg Schildt
16: */
17: interface ISettingsManager extends IInitable
18: {
19: /**
20: * Initializes the settings manager with parameters.
21: *
22: * @param array $parameters
23: * The parameters may vary for each settings manager.
24: *
25: * @return void
26: *
27: * @throws \Exception
28: * It might throw an exception in the case of any system errors.
29: *
30: * @author Oleg Schildt
31: */
32: public function init(array $parameters): void;
33:
34: /**
35: * Sets the validator for the settings.
36: *
37: * @param ISettingsValidator $validator
38: * The settings validator.
39: *
40: * @return void
41: *
42: * @see ISettingsManager::getValidator()
43: * @see ISettingsManager::validateSettings()
44: *
45: * @author Oleg Schildt
46: */
47: public function setValidator(ISettingsValidator $validator): void;
48:
49: /**
50: * Returns the validator for the settings.
51: *
52: * @return ?ISettingsValidator
53: * Returns the validator for the settings or null if none is defined.
54: *
55: * @see ISettingsManager::setValidator()
56: * @see ISettingsManager::validateSettings()
57: *
58: * @author Oleg Schildt
59: */
60: public function getValidator(): ?ISettingsValidator;
61:
62: /**
63: * Sets a settings parameter.
64: *
65: * @param string $name
66: * The name of the settings parameter.
67: *
68: * @param mixed $value
69: * The value of the settings parameter.
70: *
71: * @return void
72: *
73: * @see ISettingsManager::getParameter()
74: * @see ISettingsManager::setParameters()
75: *
76: * @author Oleg Schildt
77: */
78: public function setParameter(string $name, mixed $value): void;
79:
80: /**
81: * Sets settings parameters from an array.
82: *
83: * @param array $parameters
84: * Array of parameters in the form key => value.
85: *
86: * @param bool $force_creation
87: * Flag which defines whether the parameter should be created
88: * if not exists. If false, only existing parameters are updated.
89: *
90: * @return void
91: *
92: * @see ISettingsManager::getParameter()
93: * @see ISettingsManager::setParameter()
94: *
95: * @author Oleg Schildt
96: */
97: public function setParameters(array $parameters, bool $force_creation = false): void;
98:
99: /**
100: * Returns the value of a settings parameter.
101: *
102: * @param string $name
103: * The name of the settings parameter.
104: *
105: * @param mixed|null $default
106: * The default value of the settings parameter if it is not set yet.
107: * The parameter is a conformable way to pre-set a parameter
108: * to a default value if its value is not set yet.
109: * However, if the status of the data is dirty and the unsaved
110: * last entered value is requested, then always the actual
111: * last entered value is returned and this parameter is ignored.
112: *
113: * @return mixed
114: * Returns the value of the settings parameter.
115: *
116: * @see ISettingsManager::setParameter()
117: * @see ISettingsManager::setParameters()
118: *
119: * @author Oleg Schildt
120: */
121: public function getParameter(string $name, mixed $default = null): mixed;
122:
123: /**
124: * Sets the settings context.
125: *
126: * Settings might be edited not in one dialog,
127: * There can be several masks for different type of settings,
128: * or the settings can be configured in a wizard.
129: * In this case, only a subset of settings has to be
130: * saved and validated.
131: * To be able to write a flexible validator for the subsets,
132: * the $context is used. It can be - step1, step1, server_settings,
133: * db_connection_settings etc.
134: *
135: * @param string $context
136: * The settings context.
137: *
138: * @return void
139: *
140: * @see ISettingsManager::getContext()
141: *
142: * @author Oleg Schildt
143: */
144: public function setContext(string $context = "default"): void;
145:
146: /**
147: * Returns the current settings context.
148: *
149: * Settings might be edited not in one dialog,
150: * There can be several masks for different type of settings,
151: * or the settings can be configured in a wizard.
152: * In this case, only a subset of settings has to be
153: * saved and validated.
154: * To be able to write a flexible validator for the subsets,
155: * the $context is used. It can be - step1, step1, server_settings,
156: * db_connection_settings etc.
157: *
158: * @return string
159: * Returns the current settings context.
160: *
161: * @see ISettingsManager::setContext()
162: *
163: * @author Oleg Schildt
164: */
165: public function getContext(): string;
166:
167: /**
168: * Validates the current settings values.
169: *
170: * It should be called after settings the new values of the parameters
171: * and before their saving.
172: *
173: * @return void
174: *
175: * @throws \SmartFactory\SmartException|\SmartFactory\SmartExceptionCollection
176: * It might throw an exception if the content type oк JSON data is invalid.
177: *
178: * @uses ISettingsValidator
179: *
180: * @see ISettingsManager::getValidator()
181: * @see ISettingsManager::setValidator()
182: *
183: * @author Oleg Schildt
184: */
185: public function validateSettings(): void;
186:
187: /**
188: * Loads the settings from the persistence source.
189: *
190: * @return void
191: *
192: * @throws \Exception
193: * It might throw an exception in the case of any errors.
194: *
195: * @see ISettingsManager::saveSettings()
196: *
197: * @author Oleg Schildt
198: */
199: public function loadSettings(): void;
200:
201: /**
202: * Saves the settings from to the persistence target.
203: *
204: * @return void
205: *
206: * @throws \Exception
207: * It might throw an exception in the case of any errors.
208: *
209: * @see ISettingsManager::loadSettings()
210: *
211: * @author Oleg Schildt
212: */
213: public function saveSettings(): void;
214: } // ISettingsManager