1: <?php
2: /**
3: * This file contains the declaration of the interface IMessageManager for working with messages.
4: *
5: * @package System
6: *
7: * @author Oleg Schildt
8: */
9:
10: namespace SmartFactory\Interfaces;
11:
12: /**
13: * Interface for working with messages.
14: *
15: * @author Oleg Schildt
16: */
17: interface IMessageManager extends IInitable
18: {
19: /**
20: * Initializes the message manager with parameters.
21: *
22: * @param array $parameters
23: * The parameters may vary for each message 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: * Stores the error to be reported.
36: *
37: * @param string $message
38: * The error message to be reported.
39: *
40: * @param array $details
41: * The details might be useful if the message translations are provided on the client, not
42: * on the server, and the message should contain some details that may vary from case to case.
43: * In that case, the servers return the message id instead of final text and the details, the client
44: * uses the message id, gets the final translated text and substitutes the parameters through the details.
45: *
46: * @param string $related_element
47: * The error element vaccinated with the error.
48: *
49: * @param string $code
50: * The error code to be reported.
51: *
52: * @param string $technical_info
53: * The technical information for the error. Displaying
54: * of this part might be controlled over an option
55: * "debug_mode".
56: *
57: * @param string $file
58: * The source file where the error occurred. Per default, the file where the adding error called.
59: *
60: * @param string $line
61: * The source file line where the error occurred. Per default, the file line where the adding error called.
62: *
63: * @return void
64: *
65: * @see IMessageManager::addErrorFromSmartException()
66: * @see IMessageManager::addWarning()
67: * @see IMessageManager::addProgWarning()
68: * @see IMessageManager::addDebugMessage()
69: * @see IMessageManager::addInfoMessage()
70: * @see IMessageManager::addBubbleMessage()
71: * @see IMessageManager::getErrors()
72: * @see IMessageManager::hasErrors()
73: * @see IMessageManager::clearErrors()
74: *
75: * @author Oleg Schildt
76: */
77: public function addError(string $message, array $details = [], string $related_element = "", string $code = "", string $technical_info = "", string $file = "", string $line = ""): void;
78:
79: /**
80: * Stores the error to be reported.
81: *
82: * @param \SmartFactory\SmartException $smart_exception
83: * The exception object of collection of exceptions.
84: *
85: * @return void
86: *
87: * @see IMessageManager::addError()
88: * @see IMessageManager::addWarning()
89: * @see IMessageManager::addProgWarning()
90: * @see IMessageManager::addDebugMessage()
91: * @see IMessageManager::addInfoMessage()
92: * @see IMessageManager::addBubbleMessage()
93: * @see IMessageManager::getErrors()
94: * @see IMessageManager::hasErrors()
95: * @see IMessageManager::clearErrors()
96: *
97: * @author Oleg Schildt
98: */
99: public function addErrorFromSmartException(\SmartFactory\SmartException $smart_exception): void;
100:
101: /**
102: * Clears the stored error messages.
103: *
104: * @return void
105: *
106: * @see IMessageManager::clearWarnings()
107: * @see IMessageManager::clearProgWarnings()
108: * @see IMessageManager::clearDebugMessages()
109: * @see IMessageManager::clearInfoMessages()
110: * @see IMessageManager::clearBubbleMessages()
111: * @see IMessageManager::clearAll()
112: * @see IMessageManager::addError()
113: *
114: * @author Oleg Schildt
115: */
116: public function clearErrors(): void;
117:
118: /**
119: * Checks whether a stored error message exist.
120: *
121: * @return bool
122: * Returns true if the stored error message exists, otherwise false.
123: *
124: * @see IMessageManager::hasWarnings()
125: * @see IMessageManager::hasProgWarnings()
126: * @see IMessageManager::hasDebugMessages()
127: * @see IMessageManager::hasInfoMessages()
128: * @see IMessageManager::hasBubbleMessages()
129: * @see IMessageManager::getErrors()
130: * @see IMessageManager::addError()
131: *
132: * @author Oleg Schildt
133: */
134: public function hasErrors(): bool;
135:
136: /**
137: * Returns the array of errors if any have been stored.
138: *
139: * @return array
140: * Returns the array of errors if any have been stored.
141: *
142: * @see IMessageManager::getWarnings()
143: * @see IMessageManager::getProgWarnings()
144: * @see IMessageManager::getDebugMessages()
145: * @see IMessageManager::getInfoMessages()
146: * @see IMessageManager::getBubbleMessages()
147: * @see IMessageManager::hasErrors()
148: * @see IMessageManager::addError()
149: *
150: * @author Oleg Schildt
151: */
152: public function getErrors(): array;
153:
154: /**
155: * Stores the warning to be reported.
156: *
157: * @param string $message
158: * The warning message to be reported.
159: *
160: * @param array $details
161: * The details might be useful if the message translations are provided on the client, not
162: * on the server, and the message should contain some details that may vary from case to case.
163: * In that case, the servers return the message id instead of final text and the details, the client
164: * uses the message id, gets the final translated text and substitutes the parameters through the details.
165: *
166: * @param string $related_element
167: * The error element associated with the warning.
168: *
169: * @return void
170: *
171: * @see IMessageManager::addError()
172: * @see IMessageManager::addProgWarning()
173: * @see IMessageManager::addDebugMessage()
174: * @see IMessageManager::addInfoMessage()
175: * @see IMessageManager::addBubbleMessage()
176: * @see IMessageManager::getWarnings()
177: * @see IMessageManager::hasWarnings()
178: * @see IMessageManager::clearWarnings()
179: *
180: * @author Oleg Schildt
181: */
182: public function addWarning(string $message, array $details = [], string $related_element = ""): void;
183:
184: /**
185: * Clears the stored warning messages.
186: *
187: * @return void
188: *
189: * @see IMessageManager::clearErrors()
190: * @see IMessageManager::clearProgWarnings()
191: * @see IMessageManager::clearDebugMessages()
192: * @see IMessageManager::clearInfoMessages()
193: * @see IMessageManager::clearBubbleMessages()
194: * @see IMessageManager::clearAll()
195: * @see IMessageManager::addWarning()
196: *
197: * @author Oleg Schildt
198: */
199: public function clearWarnings(): void;
200:
201: /**
202: * Checks whether a stored error warning exist.
203: *
204: * @return bool
205: * Returns true if the stored warning message exists, otherwise false.
206: *
207: * @see IMessageManager::hasErrors()
208: * @see IMessageManager::hasProgWarnings()
209: * @see IMessageManager::hasDebugMessages()
210: * @see IMessageManager::hasInfoMessages()
211: * @see IMessageManager::hasBubbleMessages()
212: * @see IMessageManager::getWarnings()
213: * @see IMessageManager::addWarning()
214: *
215: * @author Oleg Schildt
216: */
217: public function hasWarnings(): bool;
218:
219: /**
220: * Returns the array of warnings if any have been stored.
221: *
222: * @return array
223: * Returns the array of warnings if any have been stored.
224: *
225: * @see IMessageManager::getErrors()
226: * @see IMessageManager::getProgWarnings()
227: * @see IMessageManager::getDebugMessages()
228: * @see IMessageManager::getInfoMessages()
229: * @see IMessageManager::getBubbleMessages()
230: * @see IMessageManager::hasWarnings()
231: * @see IMessageManager::addWarning()
232: *
233: * @author Oleg Schildt
234: */
235: public function getWarnings(): array;
236:
237: /**
238: * Stores the programming warning to be reported.
239: *
240: * Programming warnings are shown only if the option
241: * "show programming warning" is active.
242: *
243: * @param string $message
244: * The programming warning message to be reported.
245: *
246: * @param string $file
247: * The source file where the error occurred. Per default, the file where the adding error called.
248: *
249: * @param string $line
250: * The source file line where the error occurred. Per default, the file line where the adding error called.
251: *
252: * @return void
253: *
254: * @see IMessageManager::addError()
255: * @see IMessageManager::addWarning()
256: * @see IMessageManager::addDebugMessage()
257: * @see IMessageManager::addInfoMessage()
258: * @see IMessageManager::addBubbleMessage()
259: * @see IMessageManager::getProgWarnings()
260: * @see IMessageManager::hasProgWarnings()
261: * @see IMessageManager::clearProgWarnings()
262: *
263: * @author Oleg Schildt
264: */
265: public function addProgWarning(string $message, string $file = "", string $line = ""): void;
266:
267: /**
268: * Clears the stored programming warning messages.
269: *
270: * @return void
271: *
272: * @see IMessageManager::clearErrors()
273: * @see IMessageManager::clearWarnings()
274: * @see IMessageManager::clearDebugMessages()
275: * @see IMessageManager::clearInfoMessages()
276: * @see IMessageManager::clearBubbleMessages()
277: * @see IMessageManager::clearAll()
278: * @see IMessageManager::addProgWarning()
279: *
280: * @author Oleg Schildt
281: */
282: public function clearProgWarnings(): void;
283:
284: /**
285: * Checks whether a stored programming warning exist.
286: *
287: * @return bool
288: * Returns true if the stored programming warning message exists, otherwise false.
289: *
290: * @see IMessageManager::hasErrors()
291: * @see IMessageManager::hasWarnings()
292: * @see IMessageManager::hasDebugMessages()
293: * @see IMessageManager::hasInfoMessages()
294: * @see IMessageManager::hasBubbleMessages()
295: * @see IMessageManager::getProgWarnings()
296: * @see IMessageManager::addProgWarning()
297: *
298: * @author Oleg Schildt
299: */
300: public function hasProgWarnings(): bool;
301:
302: /**
303: * Returns the array of programming warnings if any have been stored.
304: *
305: * @return array
306: * Returns the array of programming warnings if any have been stored.
307: *
308: * @see IMessageManager::getErrors()
309: * @see IMessageManager::getWarnings()
310: * @see IMessageManager::getDebugMessages()
311: * @see IMessageManager::getInfoMessages()
312: * @see IMessageManager::getBubbleMessages()
313: * @see IMessageManager::hasProgWarnings()
314: * @see IMessageManager::addProgWarning()
315: *
316: * @author Oleg Schildt
317: */
318: public function getProgWarnings(): array;
319:
320: /**
321: * Stores the debugging message to be reported.
322: *
323: * Displaying of the debugging messages might be
324: * implemented to simplify the debugging process,
325: * e.g. to the browser console or in a lightbox.
326: *
327: * @param string $message
328: * The debugging message to be reported.
329: *
330: * @param string $file
331: * The source file where the debug output occurred. Per default, the file where the debug output called.
332: *
333: * @param string $line
334: * The source file line where the debug output occurred. Per default, the file line where the debug output called.
335: *
336: * @return void
337: *
338: * @see IMessageManager::addError()
339: * @see IMessageManager::addWarning()
340: * @see IMessageManager::addProgWarning()
341: * @see IMessageManager::addInfoMessage()
342: * @see IMessageManager::addBubbleMessage()
343: * @see IMessageManager::getDebugMessages()
344: * @see IMessageManager::hasDebugMessages()
345: * @see IMessageManager::clearDebugMessages()
346: *
347: * @author Oleg Schildt
348: */
349: public function addDebugMessage(string $message, string $file = "", string $line = ""): void;
350:
351: /**
352: * Clears the stored debugging messages.
353: *
354: * @return void
355: *
356: * @see IMessageManager::clearErrors()
357: * @see IMessageManager::clearWarnings()
358: * @see IMessageManager::clearProgWarnings()
359: * @see IMessageManager::clearInfoMessages()
360: * @see IMessageManager::clearBubbleMessages()
361: * @see IMessageManager::clearAll()
362: * @see IMessageManager::addDebugMessage()
363: *
364: * @author Oleg Schildt
365: */
366: public function clearDebugMessages(): void;
367:
368: /**
369: * Checks whether a stored debugging message exist.
370: *
371: * @return bool
372: * Returns true if the stored debugging message exists, otherwise false.
373: *
374: * @see IMessageManager::hasErrors()
375: * @see IMessageManager::hasWarnings()
376: * @see IMessageManager::hasProgWarnings()
377: * @see IMessageManager::hasInfoMessages()
378: * @see IMessageManager::hasBubbleMessages()
379: * @see IMessageManager::getDebugMessages()
380: * @see IMessageManager::addDebugMessage()
381: *
382: * @author Oleg Schildt
383: */
384: public function hasDebugMessages(): bool;
385:
386: /**
387: * Returns the array of debugging messages if any have been stored.
388: *
389: * @return array
390: * Returns the array of debugging messages if any have been stored.
391: *
392: * @see IMessageManager::getErrors()
393: * @see IMessageManager::getWarnings()
394: * @see IMessageManager::getProgWarnings()
395: * @see IMessageManager::getInfoMessages()
396: * @see IMessageManager::getBubbleMessages()
397: * @see IMessageManager::hasDebugMessages()
398: * @see IMessageManager::addDebugMessage()
399: *
400: * @author Oleg Schildt
401: */
402: public function getDebugMessages(): array;
403:
404: /**
405: * Stores the information message to be reported.
406: *
407: * @param string $message
408: * The information message to be reported.
409: *
410: * @param array $details
411: * The details might be useful if the message translations are provided on the client, not
412: * on the server, and the message should contain some details that may vary from case to case.
413: * In that case, the servers return the message id instead of final text and the details, the client
414: * uses the message id, gets the final translated text and substitutes the parameters through the details.
415: *
416: * @param bool $autoclose
417: * The flag that controls whether the message box should be closed
418: * automatically after a time.
419: *
420: * @return void
421: *
422: * @see IMessageManager::addError()
423: * @see IMessageManager::addWarning()
424: * @see IMessageManager::addProgWarning()
425: * @see IMessageManager::addDebugMessage()
426: * @see IMessageManager::addBubbleMessage()
427: * @see IMessageManager::getInfoMessages()
428: * @see IMessageManager::hasInfoMessages()
429: * @see IMessageManager::clearInfoMessages()
430: *
431: * @author Oleg Schildt
432: */
433: public function addInfoMessage(string $message, array $details = [], bool $autoclose = false): void;
434:
435: /**
436: * Clears the stored information messages.
437: *
438: * @return void
439: *
440: * @see IMessageManager::clearErrors()
441: * @see IMessageManager::clearWarnings()
442: * @see IMessageManager::clearProgWarnings()
443: * @see IMessageManager::clearDebugMessages()
444: * @see IMessageManager::clearBubbleMessages()
445: * @see IMessageManager::clearAll()
446: * @see IMessageManager::addInfoMessage()
447: *
448: * @author Oleg Schildt
449: */
450: public function clearInfoMessages(): void;
451:
452: /**
453: * Checks whether an information message exist.
454: *
455: * @return bool
456: * Returns true if the information message exists, otherwise false.
457: *
458: * @see IMessageManager::hasErrors()
459: * @see IMessageManager::hasWarnings()
460: * @see IMessageManager::hasProgWarnings()
461: * @see IMessageManager::hasDebugMessages()
462: * @see IMessageManager::hasBubbleMessages()
463: * @see IMessageManager::getInfoMessages()
464: * @see IMessageManager::addInfoMessage()
465: *
466: * @author Oleg Schildt
467: */
468: public function hasInfoMessages(): bool;
469:
470: /**
471: * Returns the array of information messages if any have been stored.
472: *
473: * @return array
474: * Returns the array of information messages if any have been stored.
475: *
476: * @see IMessageManager::getErrors()
477: * @see IMessageManager::getWarnings()
478: * @see IMessageManager::getProgWarnings()
479: * @see IMessageManager::getDebugMessages()
480: * @see IMessageManager::getBubbleMessages()
481: * @see IMessageManager::hasInfoMessages()
482: * @see IMessageManager::addInfoMessage()
483: *
484: * @author Oleg Schildt
485: */
486: public function getInfoMessages(): array;
487:
488: /**
489: * Stores the information message to be reported.
490: *
491: * @param string $message
492: * The information message to be reported.
493: *
494: * @param array $details
495: * The details might be useful if the message translations are provided on the client, not
496: * on the server, and the message should contain some details that may vary from case to case.
497: * In that case, the servers return the message id instead of final text and the details, the client
498: * uses the message id, gets the final translated text and substitutes the parameters through the details.
499: *
500: * @param bool $autoclose
501: * The flag that controls whether the message box should be closed
502: * automatically after a time.
503: *
504: * @return void
505: *
506: * @see IMessageManager::addError()
507: * @see IMessageManager::addWarning()
508: * @see IMessageManager::addProgWarning()
509: * @see IMessageManager::addDebugMessage()
510: * @see IMessageManager::addInfoMessage()
511: * @see IMessageManager::getBubbleMessages()
512: * @see IMessageManager::hasBubbleMessages()
513: * @see IMessageManager::clearBubbleMessages()
514: *
515: * @author Oleg Schildt
516: */
517: public function addBubbleMessage(string $message, array $details = [], bool $autoclose = true): void;
518:
519: /**
520: * Clears the stored information messages.
521: *
522: * @return void
523: *
524: * @see IMessageManager::clearErrors()
525: * @see IMessageManager::clearWarnings()
526: * @see IMessageManager::clearProgWarnings()
527: * @see IMessageManager::clearDebugMessages()
528: * @see IMessageManager::clearInfoMessages()
529: * @see IMessageManager::clearAll()
530: * @see IMessageManager::addBubbleMessage()
531: *
532: * @author Oleg Schildt
533: */
534: public function clearBubbleMessages(): void;
535:
536: /**
537: * Checks whether an information message exist.
538: *
539: * @return bool
540: * Returns true if the information message exists, otherwise false.
541: *
542: * @see IMessageManager::hasErrors()
543: * @see IMessageManager::hasWarnings()
544: * @see IMessageManager::hasProgWarnings()
545: * @see IMessageManager::hasDebugMessages()
546: * @see IMessageManager::hasInfoMessages()
547: * @see IMessageManager::getBubbleMessages()
548: * @see IMessageManager::addBubbleMessage()
549: *
550: * @author Oleg Schildt
551: */
552: public function hasBubbleMessages(): bool;
553:
554: /**
555: * Returns the array of information messages if any have been stored.
556: *
557: * @return array
558: * Returns the array of information messages if any have been stored.
559: *
560: * @see IMessageManager::getErrors()
561: * @see IMessageManager::getWarnings()
562: * @see IMessageManager::getProgWarnings()
563: * @see IMessageManager::getDebugMessages()
564: * @see IMessageManager::getInfoMessages()
565: * @see IMessageManager::hasBubbleMessages()
566: * @see IMessageManager::addBubbleMessage()
567: *
568: * @author Oleg Schildt
569: */
570: public function getBubbleMessages(): array;
571:
572: /**
573: * Clears all stored messages and active elements.
574: *
575: * @return void
576: *
577: * @see IMessageManager::clearErrors()
578: * @see IMessageManager::clearWarnings()
579: * @see IMessageManager::clearProgWarnings()
580: * @see IMessageManager::clearDebugMessages()
581: * @see IMessageManager::clearInfoMessages()
582: * @see IMessageManager::clearBubbleMessages()
583: *
584: * @author Oleg Schildt
585: */
586: public function clearAll(): void;
587: } // IMessageManager