Add Timer class and tests

Author: sebastianfeldmann

src/Runner/Timer.php

@@ -0,0 +1,77 @@
+<?php
+
+/**
+ * This file is part of CaptainHook.
+ *
+ * (c) Sebastian Feldmann <sf@sebastian-feldmann.info>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace CaptainHook\App\Runner;
+
+use RuntimeException;
+
+/**
+ * Timer
+ *
+ * Measures hook and action execution times.
+ *
+ * @package CaptainHook
+ * @author  Sebastian Feldmann <sf@sebastian-feldmann.info>
+ * @link    https://github.com/captainhook-git/captainhook
+ * @since   Class available since Release 5.28.0
+ */
+class Timer
+{
+    private float $start = 0.0;
+    private float $stop = 0.0;
+
+    /**
+     * Start the timer
+     *
+     * @return float
+     */
+    public function start(): float
+    {
+        $this->start = microtime(true);
+        return $this->start;
+    }
+
+    /**
+     * Stop the timer and calculate the elapsed time.
+     *
+     * @return float The time elapsed in seconds.
+     */
+    public function stop(): float
+    {
+        if ($this->start === 0.0) {
+            throw new RuntimeException('Timer not started');
+        }
+        $this->stop = microtime(true);
+        return $this->stop - $this->start;
+    }
+
+    /**
+     * Determine if the timer is currently running
+     *
+     * @return bool
+     */
+    public function isRunning(): bool
+    {
+        return $this->start > 0.0 && $this->stop === 0.0;
+    }
+
+    /**
+     * Creates a new timer, starts the timer, and returns the instance.
+     *
+     * @return \CaptainHook\App\Runner\Timer.
+     */
+    public static function createAndStart(): self
+    {
+        $timer = new self();
+        $timer->start();
+        return $timer;
+    }
+}

tests/unit/Runner/TimerTest.php

@@ -0,0 +1,61 @@
+<?php
+
+/**
+ * This file is part of CaptainHook.
+ *
+ * (c) Sebastian Feldmann <sf@sebastian-feldmann.info>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace CaptainHook\App\Runner;
+
+use PHPUnit\Framework\TestCase;
+use RuntimeException;
+
+class TimerTest extends TestCase
+{
+    public function testStartReturnsTheStartTime(): void
+    {
+        $timer = new Timer();
+
+        $start = $timer->start();
+
+        $this->assertIsFloat($start);
+        $this->assertGreaterThan(0.0, $start);
+    }
+
+    public function testNotStartedTimerCanNotBeStopped(): void
+    {
+        $this->expectException(RuntimeException::class);
+        $timer = new Timer();
+        $timer->stop();
+    }
+
+    public function testTimerStatusCanBeChecked(): void
+    {
+        $timer = new Timer();
+        $this->assertFalse($timer->isRunning());
+
+        $timer->start();
+        $this->assertTrue($timer->isRunning());
+
+        $timer->stop();
+        $this->assertFalse($timer->isRunning());
+    }
+
+    public function testStopReturnsElapsedSeconds(): void
+    {
+        $timer = new Timer();
+
+        $timer->start();
+        usleep(10_000); // 10ms to avoid flaky zero durations on fast machines
+
+        $elapsed = $timer->stop();
+
+        $this->assertIsFloat($elapsed);
+        $this->assertGreaterThan(0.0, $elapsed);
+        $this->assertLessThan(1.0, $elapsed, 'Timer should not take this long in a unit test');
+    }
+}