1: <?php
  2: /**
  3:  * This file contains the declaration of the interface IDebugProfiler for debugging, tracing and profiling.
  4:  *
  5:  * @package System
  6:  *
  7:  * @author Oleg Schildt
  8:  */
  9: 
 10: namespace SmartFactory\Interfaces;
 11: 
 12: /**
 13:  * Interface for debugging, tracing and profiling.
 14:  *
 15:  * @author Oleg Schildt
 16:  */
 17: interface IDebugProfiler extends IInitable
 18: {
 19:     /**
 20:      * Initializes the debug profiler with parameters.
 21:      *
 22:      * @param array $parameters
 23:      * The parameters may vary for each debug profiler.
 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:      * Logs a message to a standard debug output.
 36:      *
 37:      * @param string $message
 38:      * Message to be logged.
 39:      *
 40:      * @param bool $write_call_stack
 41:      * Flag that defines where the call stack should be written.
 42:      *
 43:      * @param string $file_name
 44:      * The target file name.
 45:      *
 46:      * @return void
 47:      *
 48:      * @throws \Exception
 49:      * It might throw an exception in the case of any errors.
 50:      *
 51:      * @author Oleg Schildt
 52:      */
 53:     public function debugMessage(string $message, bool $write_call_stack = false, string $file_name = "debug.log"): void;
 54:     
 55:     /**
 56:      * Logs a message to a standard profiling output and stores the current time.
 57:      *
 58:      * @param string $message
 59:      * Message to be logged.
 60:      *
 61:      * @return void
 62:      *
 63:      * @throws \Exception
 64:      * It might throw an exception in the case of any errors.
 65:      *
 66:      * @see IDebugProfiler::fixProfilePoint()
 67:      *
 68:      * @author Oleg Schildt
 69:      */
 70:     public function startProfilePoint(string $message): void;
 71:     
 72:     /**
 73:      * Logs a message to a standard profiling output and shows
 74:      * the time elapsed since the last call startProfilePoint or
 75:      * fixProfilePoint.
 76:      *
 77:      * @param string $message
 78:      * Message to be logged.
 79:      *
 80:      * @return void
 81:      *
 82:      * @throws \Exception
 83:      * It might throw an exception in the case of any errors.
 84:      *
 85:      * @see IDebugProfiler::startProfilePoint()
 86:      *
 87:      * @author Oleg Schildt
 88:      */
 89:     public function fixProfilePoint(string $message): void;
 90:     
 91:     /**
 92:      * Clears the specified log file.
 93:      *
 94:      * @param string $file_name
 95:      * The target file name.
 96:      *
 97:      * @return void
 98:      *
 99:      * @see IDebugProfiler::clearLogFiles()
100:      *
101:      * @author Oleg Schildt
102:      */
103:     public function clearLogFile(string $file_name): void;
104:     
105:     /**
106:      * Clears all log files.
107:      *
108:      * @return void
109:      *
110:      * @see IDebugProfiler::clearLogFile()
111:      *
112:      * @author Oleg Schildt
113:      */
114:     public function clearLogFiles(): void;
115: } // IDebugProfiler