Timing: add new getDurationSince() method

This method doesn't use the "system" run start time, but uses an arbitrary starttime as provided via a parameter.

This allows for removing some duplicate code in various places.

Includes making the class `final` and explicitly marking this class as an internal class to allow for further changes in the future.

Author: jrfnl

src/Util/Timing.php

@@ -2,16 +2,25 @@
 /**
  * Timing functions for the run.
  *
+ * ---------------------------------------------------------------------------------------------
+ * This class is intended for internal use only and is not part of the public API.
+ * This also means that it has no promise of backward compatibility. Use at your own risk.
+ * ---------------------------------------------------------------------------------------------
+ *
+ * @internal
+ *
  * @author    Greg Sherwood <[email protected]>
+ * @author    Juliette Reinders Folmer <[email protected]>
  * @copyright 2006-2015 Squiz Pty Ltd (ABN 77 084 670 600)
+ * @copyright 2025 PHPCSStandards and contributors
  * @license   https://github.com/PHPCSStandards/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
  */
 
 namespace PHP_CodeSniffer\Util;
 
 use PHP_CodeSniffer\Util\Writers\StatusWriter;
 
-class Timing
+final class Timing
 {
 
     /**
@@ -29,7 +38,7 @@ class Timing
     private const SECOND_IN_MS = 1000;
 
     /**
-     * The start time of the run in microseconds.
+     * The start time of the run in seconds.
      *
      * @var float
      */
@@ -73,6 +82,20 @@ public static function getDuration()
     }//end getDuration()
 
 
+    /**
+     * Get the duration since a given start time up to "now".
+     *
+     * @param float $startTime Start time in microseconds.
+     *
+     * @return float Duration in milliseconds.
+     */
+    public static function getDurationSince($startTime)
+    {
+        return ((microtime(true) - $startTime) * 1000);
+
+    }//end getDurationSince()
+
+
     /**
      * Convert a duration in milliseconds to a human readable duration string.
      *

tests/Core/Util/Timing/TimingTest.php

@@ -60,6 +60,24 @@ public function testGetDurationWithStartReturnsMilliseconds()
     }//end testGetDurationWithStartReturnsMilliseconds()
 
 
+    /**
+     * Verify that getDurationSince() returns the time in milliseconds.
+     *
+     * @return void
+     */
+    public function testGetDurationSinceReturnsMilliseconds()
+    {
+        $startTime = microtime(true);
+        usleep(1500);
+        $duration = Timing::getDurationSince($startTime);
+
+        $this->assertIsFloat($duration);
+        $this->assertGreaterThan(1, $duration);
+        $this->assertLessThan(15, $duration);
+
+    }//end testGetDurationSinceReturnsMilliseconds()
+
+
     /**
      * Verify that printRunTime() doesn't print anything if the timer wasn't started.
      *