From d827d5345f778bb9a481e916666c540801108d18 Mon Sep 17 00:00:00 2001
From: Geo Halkiadakis <gchalkiadakis@sklavenitis.co.gr>
Date: Wed, 17 May 2023 18:43:07 +0300
Subject: framework documenting and cleaning

---
 core/classes/Benchmark.php | 106 ++++++++++++++++++++++++++++++++++-----------
 1 file changed, 81 insertions(+), 25 deletions(-)

(limited to 'core/classes')

diff --git a/core/classes/Benchmark.php b/core/classes/Benchmark.php
index a7e93ea..8aa040d 100644
--- a/core/classes/Benchmark.php
+++ b/core/classes/Benchmark.php
@@ -1,14 +1,52 @@
 <?php
 
-// define('BENCHMARKED', true);  // then you know if class is active
-
+/** Benchmarn class
+ * -----------------------------------------------------------------------------
+ * 
+ * Handy class to evaluate the apprication's performace
+ * 
+ * [*] calulates time difference between any two or more marked timespots;
+ * [*] tracks memory usage for the marked timespots
+ * [*] creates reports in various formats
+ * 
+ * TODO: create an (optional) ascii graph ??
+ * 
+ * -----------------------------------------------------------------------------
+ */
 class Benchmark {
 
+    /** PROPERTIES
+     * -------------------------------------------------------------------------
+     */
+
+
+    /** @var array
+     * array of microtimes in [key => val] pairs, where
+     * + key (string): is a custom label used for refering
+     * + val (float) : the microtime when the timespot was created
+     */
     private static $timeSpots = Array();
 
+
+    /** @var array
+     * array of memory used in [key => val] pairs, where
+     * + key (string): is a custom label used for refering (same as in $timeSpots)
+     * + val (float) : the memory usage (in bytes) when the timespot was created
+     */
     private static $memoryUse = Array();
 
-    private static $enableReport = true;
+
+    /** @var boolean
+     * flag to determin if reporting is enaabled
+     */
+    private static $reportEnabled = true;
+
+
+
+
+    /** METHODS
+     * -------------------------------------------------------------------------
+     */
 
     
     /** add_timespot
@@ -37,7 +75,7 @@ class Benchmark {
      */
     public static function disableReport()
     {
-        self::$enableReport = false;
+        self::$reportEnabled = false;
     }
 
 
@@ -45,31 +83,47 @@ class Benchmark {
      * ---
      * renders performance report
      * as html comment at the end of webpage in various modes
-     * @param $mode (string)
-     * + 'comment' (default): include report as html comment
-     * + 'html' : include report as a html div
-     * + 'code' : include report as a pre/code block
+     * 
+     * @param $mode (int): report format id
+     * ... default: BENCH_REPORT_COMMENT (5) = report as html comment;
+     * ... for more report-formats check the BENCH_REPORT_* defines
      */
-    public static function render_report(string $mode = 'comment' )
+    public static function report(string $mode = BENCH_REPORT_COMMENT)
     {
-        if (self::$enableReport) {
+        if ( (self::$reportEnabled) && (!empty(self::$timeSpots)) ) {
 
             switch ($mode) {
-                case 'html':
+                case BENCH_REPORT_ARRAY:
+                    return [
+                        'timespots' => self::$timeSpots,
+                        'memory_usage' => self::$memoryUse
+                    ];
+                    break;
+
+                case BENCH_REPORT_JSON:
+                    return json_encode([
+                        'timespots' => self::$timeSpots,
+                        'memory_usage' => self::$memoryUse
+                    ], JSON_PRETTY_PRINT|JSON_UNESCAPED_UNICODE);
+                    break;
+
+                case BENCH_REPORT_HTML:
                     $open = '<p>';
                     $close = '</b></p>';
                     $divider = ":<b>";
                     $prefix = '<div>';
                     $suffix = '</div>';
                     break;
-                case 'code':
+
+                case BENCH_REPORT_CODE:
                     $open = '';
                     $close = '';
                     $divider = ": ";
                     $prefix = '<pre>';
                     $suffix = '</pre>';
                     break;
-                case 'comment':
+
+                case BENCH_REPORT_COMMENT:
                 default:
                     $open = '<!--';
                     $close = '-->';
@@ -79,11 +133,11 @@ class Benchmark {
                     break;
             }
 
-            echo $prefix;
+            $output = $prefix;
 
             // TIME REPORT 
             // ---------------------------------------------------------------------
-            echo "\n\n{$open} Timings {$close}";
+            $output .= "\n\n{$open} Timings {$close}";
 
             // valid from php 7.3
             // $start = self::$timeSpots[ array_key_first(self::$timespots) ];
@@ -95,7 +149,7 @@ class Benchmark {
             
 
             // if more than 2 timespots
-            // echo dt between each spot
+            // $output .= dt between each spot
             if (count(self::$timeSpots) > 2) {
 
                 // calculate dt between spots
@@ -118,33 +172,35 @@ class Benchmark {
                     }
                 }
 
-                // echo timings
+                // $output .= timings
                 foreach ($time_results as $key => $val) {
-                    echo "\n\t{$open} {$val['part']} {$divider} {$val['dt']} {$close}";
+                    $output .= "\n\t{$open} {$val['part']} {$divider} {$val['dt']} {$close}";
                 }
             }
 
-            // echo total time
-            echo "\n\t{$open} total {$divider} {$all_dt} {$close}";
+            // $output .= total time
+            $output .= "\n\t{$open} total {$divider} {$all_dt} {$close}";
 
 
             // MEMORY REPORT
             // ---------------------------------------------------------------------
-            echo "\n\n{$open} Memory Usage {$close}";
+            $output .= "\n\n{$open} Memory Usage {$close}";
 
             if (count(self::$memoryUse) > 2) {
 
                 foreach (self::$memoryUse as $key => $val) {
-                    echo "\n\t{$open} {$key} {$divider} {$val}MB {$close}";
+                    $output .= "\n\t{$open} {$key} {$divider} {$val}MB {$close}";
                 }
 
             } else {
-                echo "\n\t{$open} memory usage {$divider} ". round(memory_get_usage()/(1024*1024),2) ."MB {$close}";   
+                $output .= "\n\t{$open} memory usage {$divider} ". round(memory_get_usage()/(1024*1024),2) ."MB {$close}";   
             }
 
-            echo $suffix;
+            $output .= $suffix;
 
         }
-        
+        return $output;
+
     }
+
 }
-- 
cgit v1.2.3