Feature for Timer to measure callable performance

system/Common.php

@@ -1076,19 +1076,25 @@ function stringify_attributes($attributes, bool $js = false): string
 if (! function_exists('timer')) {
     /**
      * A convenience method for working with the timer.
-     * If no parameter is passed, it will return the timer instance,
-     * otherwise will start or stop the timer intelligently.
+     * If no parameter is passed, it will return the timer instance.
+     * If callable is passed, it measures time of callable and
+     * returns its return value if any.
+     * Otherwise will start or stop the timer intelligently.
      *
      * @return mixed|Timer
      */
-    function timer(?string $name = null)
+    function timer(?string $name = null, ?callable $callable = null)
     {
         $timer = Services::timer();
 
         if (empty($name)) {
             return $timer;
         }
 
+        if ($callable !== null) {
+            return $timer->record($name, $callable);
+        }
+
         if ($timer->has($name)) {
             return $timer->stop($name);
         }

system/Debug/Timer.php

@@ -126,4 +126,22 @@ public function has(string $name): bool
     {
         return array_key_exists(strtolower($name), $this->timers);
     }
+
+    /**
+     * Executes callable and measures its time.
+     * Returns its return value if any.
+     *
+     * @param string   $name     The name of the timer
+     * @param callable $callable callable to be executed
+     *
+     * @return object|resource|array|string|int|float|bool|null
+     */
+    public function record(string $name, callable $callable)
+    {
+        $this->start($name);
+        $returnValue = $callable();
+        $this->stop($name);
+
+        return $returnValue;
+    }
 }

tests/system/Debug/TimerTest.php

@@ -12,6 +12,8 @@
 namespace CodeIgniter\Debug;
 
 use CodeIgniter\Test\CIUnitTestCase;
+use RuntimeException;
+use Throwable;
 
 /**
  * @internal
@@ -121,4 +123,107 @@ public function testReturnsNullGettingElapsedTimeOfNonTimer()
 
         $this->assertNull($timer->getElapsedTime('test1'));
     }
+
+    /**
+     * @timeLimit 1.5
+     */
+    public function testRecordFunctionNoReturn()
+    {
+        $timer       = new Timer();
+        $returnValue = $timer->record('longjohn', static function () { sleep(1); });
+
+        $this->assertGreaterThanOrEqual(1.0, $timer->getElapsedTime('longjohn'));
+        $this->assertNull($returnValue);
+    }
+
+    /**
+     * @timeLimit 1.5
+     */
+    public function testRecordFunctionWithReturn()
+    {
+        $timer       = new Timer();
+        $returnValue = $timer->record('longjohn', static function () {
+            sleep(1);
+
+            return 'test';
+        });
+
+        $this->assertGreaterThanOrEqual(1.0, $timer->getElapsedTime('longjohn'));
+        $this->assertSame('test', $returnValue);
+    }
+
+    public function testRecordArrowFunction()
+    {
+        $timer       = new Timer();
+        $returnValue = $timer->record('longjohn', static fn () => strlen('CI4'));
+
+        $this->assertLessThanOrEqual(1.0, $timer->getElapsedTime('longjohn'));
+        $this->assertSame(3, $returnValue);
+    }
+
+    public function testRecordThrowsException()
+    {
+        $this->expectException(RuntimeException::class);
+
+        $timer = new Timer();
+        $timer->record('ex', static function () { throw new RuntimeException(); });
+    }
+
+    public function testRecordThrowsErrorOnCallableWithParams()
+    {
+        $this->expectException(Throwable::class);
+
+        $timer = new Timer();
+        $timer->record('error', 'strlen');
+    }
+
+    public function testCommonNoNameExpectTimer()
+    {
+        $returnValue = timer();
+
+        $this->assertInstanceOf(Timer::class, $returnValue);
+    }
+
+    public function testCommonWithNameExpectTimer()
+    {
+        $returnValue = timer('test');
+
+        $this->assertInstanceOf(Timer::class, $returnValue);
+        $this->assertTrue($returnValue->has('test'));
+    }
+
+    public function testCommonNoNameCallableExpectTimer()
+    {
+        $returnValue = timer(null, static fn () => strlen('CI4'));
+
+        $this->assertInstanceOf(Timer::class, $returnValue);
+    }
+
+    /**
+     * @timeLimit 1.5
+     */
+    public function testCommonCallableExpectNoReturn()
+    {
+        $returnValue = timer('common', static function () { sleep(1); });
+
+        $this->assertNotInstanceOf(Timer::class, $returnValue);
+        $this->assertNull($returnValue);
+        $this->assertGreaterThanOrEqual(1.0, timer()->getElapsedTime('common'));
+    }
+
+    /**
+     * @timeLimit 1.5
+     */
+    public function testCommonCallableExpectWithReturn()
+    {
+        $returnValue = timer('common', static function () {
+            sleep(1);
+
+            return strlen('CI4');
+        });
+
+        $this->assertNotInstanceOf(Timer::class, $returnValue);
+        $this->assertSame(3, $returnValue);
+        $this->assertGreaterThanOrEqual(1.0, timer()->getElapsedTime('common'));
+    }
 }

user_guide_src/source/changelogs/v4.3.0.rst

@@ -42,6 +42,7 @@ Enhancements
 - SQLite ``BaseConnection::getIndexData()`` now can return pseudo index named ``PRIMARY`` for `AUTOINCREMENT` column, and each returned index data has ``type`` property.
 - Added ``spark filter:check`` command to check the filters for a route. See :ref:`Controller Filters <spark-filter-check>` for the details.
 - Now **Encryption** can decrypt data encrypted with CI3's Encryption. See :ref:`encryption-compatible-with-ci3`.
+- Added method ``Timer::record()`` to measure performance in a callable. Also enhanced common function ``timer()`` to accept optional callable.
 - Now ``spark routes`` command shows route names. See :ref:`URI Routing <routing-spark-routes>`.
 
 Changes

user_guide_src/source/testing/benchmark.rst

@@ -38,6 +38,20 @@ and stop timers:
 
 .. literalinclude:: benchmark/003.php
 
+If you use very small code blocks to benchmark, you can also use the ``record()`` method. It accepts
+a no-parameter callable and measures its execution time. Methods ``start()`` and ``stop()`` will be called
+automatically around the function call.
+
+.. literalinclude:: benchmark/010.php
+
+You can also return the callable's return value for further processing.
+
+.. literalinclude:: benchmark/011.php
+
+The same functionality is also available when passing callable to ``timer()`` as second parameter.
+
+.. literalinclude:: benchmark/012.php
+
 Viewing Your Benchmark Points
 =============================
 

user_guide_src/source/testing/benchmark/010.php

@@ -0,0 +1,11 @@
+<?php
+
+$benchmark->record('slow_function', static function () { slow_function('...'); });
+
+/*
+ * Same as:
+ *
+ * $benchmark->start('slow_function');
+ * slow_function('...');
+ * $benchmark->stop('slow_function');
+*/

user_guide_src/source/testing/benchmark/011.php

@@ -0,0 +1,13 @@
+<?php
+
+$length = $benchmark->record('string length', static fn () => strlen('CI4'));
+
+/*
+ * $length = 3
+ *
+ * Same as:
+ *
+ * $benchmark->start('string length');
+ * $length = strlen('CI4');
+ * $benchmark->stop('string length');
+*/

user_guide_src/source/testing/benchmark/012.php

@@ -0,0 +1,13 @@
+<?php
+
+$length = timer('string length', static fn () => strlen('CI4'));
+
+/*
+ * $length = 3
+ *
+ * Same as:
+ *
+ * timer('string length');
+ * $length = strlen('CI4');
+ * timer('string length');
+*/