3 * This program is free software; you can redistribute it and/or modify
4 * it under the terms of the GNU General Public License as published by
5 * the Free Software Foundation; either version 2 of the License, or
6 * (at your option) any later version.
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU General Public License for more details.
13 * You should have received a copy of the GNU General Public License along
14 * with this program; if not, write to the Free Software Foundation, Inc.,
15 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
16 * http://www.gnu.org/copyleft/gpl.html
21 use Psr\Log\LoggerAwareInterface
;
22 use Psr\Log\LoggerInterface
;
23 use Psr\Log\NullLogger
;
26 * An interface to help developers measure the performance of their applications.
27 * This interface closely matches the W3C's User Timing specification.
28 * The key differences are:
30 * - The reference point for all measurements which do not explicitly specify
31 * a start time is $_SERVER['REQUEST_TIME_FLOAT'], not navigationStart.
32 * - Successive calls to mark() and measure() with the same entry name cause
33 * the previous entry to be overwritten. This ensures that there is a 1:1
34 * mapping between names and entries.
35 * - Because there is a 1:1 mapping, instead of getEntriesByName(), we have
38 * The in-line documentation incorporates content from the User Timing Specification
39 * https://www.w3.org/TR/user-timing/
40 * Copyright © 2013 World Wide Web Consortium, (MIT, ERCIM, Keio, Beihang).
41 * https://www.w3.org/Consortium/Legal/2015/doc-license
45 class Timing
implements LoggerAwareInterface
{
48 private $entries = [];
50 /** @var LoggerInterface */
53 public function __construct( array $params = [] ) {
55 $this->setLogger( $params['logger'] ??
new NullLogger() );
59 * Sets a logger instance on the object.
61 * @param LoggerInterface $logger
64 public function setLogger( LoggerInterface
$logger ) {
65 $this->logger
= $logger;
69 * Store a timestamp with the associated name (a "mark")
71 * @param string $markName The name associated with the timestamp.
72 * If there already exists an entry by that name, it is overwritten.
73 * @return array The mark that has been created.
75 public function mark( $markName ) {
76 $this->entries
[$markName] = [
78 'entryType' => 'mark',
79 'startTime' => microtime( true ),
82 return $this->entries
[$markName];
86 * @param string $markName The name of the mark that should
87 * be cleared. If not specified, all marks will be cleared.
89 public function clearMarks( $markName = null ) {
90 if ( $markName !== null ) {
91 unset( $this->entries
[$markName] );
95 'name' => 'requestStart',
96 'entryType' => 'mark',
97 'startTime' => $_SERVER['REQUEST_TIME_FLOAT'],
105 * This method stores the duration between two marks along with
106 * the associated name (a "measure").
108 * If neither the startMark nor the endMark argument is specified,
109 * measure() will store the duration from $_SERVER['REQUEST_TIME_FLOAT'] to
111 * If the startMark argument is specified, but the endMark argument is not
112 * specified, measure() will store the duration from the most recent
113 * occurrence of the start mark to the current time.
114 * If both the startMark and endMark arguments are specified, measure()
115 * will store the duration from the most recent occurrence of the start
116 * mark to the most recent occurrence of the end mark.
118 * @param string $measureName
119 * @param string $startMark
120 * @param string $endMark
121 * @return array|bool The measure that has been created, or false if either
122 * the start mark or the end mark do not exist.
124 public function measure( $measureName, $startMark = 'requestStart', $endMark = null ) {
125 $start = $this->getEntryByName( $startMark );
126 if ( $start === null ) {
127 $this->logger
->error( __METHOD__
. ": The mark '$startMark' does not exist" );
130 $startTime = $start['startTime'];
133 $end = $this->getEntryByName( $endMark );
134 if ( $end === null ) {
135 $this->logger
->error( __METHOD__
. ": The mark '$endMark' does not exist" );
138 $endTime = $end['startTime'];
140 $endTime = microtime( true );
143 $this->entries
[$measureName] = [
144 'name' => $measureName,
145 'entryType' => 'measure',
146 'startTime' => $startTime,
147 'duration' => $endTime - $startTime,
150 return $this->entries
[$measureName];
154 * Sort entries in chronological order with respect to startTime.
156 private function sortEntries() {
157 uasort( $this->entries
, function ( $a, $b ) {
158 return $a['startTime'] <=> $b['startTime'];
163 * @return array[] All entries in chronological order.
165 public function getEntries() {
166 $this->sortEntries();
167 return $this->entries
;
171 * @param string $entryType
172 * @return array[] Entries (in chronological order) that have the same value
173 * for the entryType attribute as the $entryType parameter.
175 public function getEntriesByType( $entryType ) {
176 $this->sortEntries();
178 foreach ( $this->entries
as $entry ) {
179 if ( $entry['entryType'] === $entryType ) {
187 * @param string $name
188 * @return array|null Entry named $name or null if it does not exist.
190 public function getEntryByName( $name ) {
191 return $this->entries
[$name] ??
null;