Usage
nebula()->timer($unique_id, $action, $category)
Parameters
$unique_id
(Required) (String) A unique ID for this specific timed task
Default: None
$action
(Optional) (String) A start/mark/stop action
Default: "start"
$category
(Optional) (String) Group timings together to be added together
Default: false
Parameter Notes
Actions currently include “start”, “mark” (with an alias of “once”), and “end” (with an alias of “stop”).
Although the $unique_id
is required, if the ID is not unique a random number will be appended to it that begins with _d
On start
actions, the used unique ID is returned so that the timer can be stopped later.
Examples
Time a single task
nebula()->timer('Example Task'); //...do something here nebula()->timer('Example Task', 'end');
Time a task that may be called more than once
$task_name = nebula()->timer('Possible Multiple Tasks'); //...do something here nebula()->timer($task_name, 'end');
Categories multiple similar tasks
foreach ( $big_list as $item ){ nebula()->timer('Big List Task (' . $item . ')', 'start', 'Big List'); //...do something here nebula()->timer('Big List Task (' . $item . ')', 'end'); }
Combine timings from a single category
if ( !empty($this->server_timings['categories']) && !empty($this->server_timings['categories']['Big List']) ){ foreach ( $this->server_timings['categories']['Big List'] as $category => $times ){ $big_list_total = array_sum($times); } }
Mark a point in time with a single entry that immediately starts and stops.
nebula()->timer('Certain Point in Time', 'mark');
Additional Notes
Timings are stored in nebula()->server_timings
and categories are separated into a nebula()->server_timings['categories']
array.
Timings will automatically appear for developers, but the query string ?timings
must be used for non-developers (or logged-out users).
Server Timing API
Timings are sent via the server-timing
HTTP header and can be viewed in Chrome DevTools under Network by clicking the page resource and choosing the Timing tab. It is important to note that these times are finalized before headers are sent.
This timing header is also available in other speed testing tools (like WebPageTest.org) that provide access to response headers.
JavaScript Console Table
Timings are also available in the JavaScript console within the Performance group. Expand it to see all server timings as well as client-side timings as well in a sortable table. Timings are finalized again at the last possible moment to make sure they are complete.
Timings are available in the WordPress admin area too.
Source File
Located in /libs/Utilities/Utilities.php on line 1068.
No Hooks
This function does not have any filters or actions available. Request one?public function timer($unique_id, $action='start', $category=false){ //Unique ID is required if ( empty($unique_id) || in_array(strtolower($unique_id), array('start', 'stop', 'end')) ){ return false; } if ( $action === 'start' || $action === 'mark' || $action === 'once' ){ //Prevent duplicates by appending a random number to the ID (only when duplicate) if ( !empty($this->server_timings[$unique_id]) ){ $unique_id .= '_d' . rand(10000, 99999); } $this->server_timings[$unique_id] = array( 'start' => microtime(true), 'active' => true, 'category' => $category ); //Immediately stop one-off timing marks if ( $action === 'mark' || $action === 'once' ){ $this->server_timings[$unique_id]['end'] = $this->server_timings[$unique_id]['start']+0.001; $this->server_timings[$unique_id]['time'] = 0.001; //Force non-empty time of 1 millisecond $this->server_timings[$unique_id]['active'] = false; //Add to array of this category (if categorization is used) if ( !empty($category) ){ $this->server_timings['categories'][$category][] = 0.001; //Force non-empty time of 1 millisecond } } return $unique_id; //Return the unique ID in case it was changed so that the 'end' call can know what to use } elseif ( in_array(strtolower($action), array('stop', 'end')) ){ if ( !empty($this->server_timings[$unique_id]['start']) ){ //Make sure this timer has started $this->server_timings[$unique_id]['end'] = microtime(true); $this->server_timings[$unique_id]['time'] = $this->server_timings[$unique_id]['end'] - $this->server_timings[$unique_id]['start']; $this->server_timings[$unique_id]['active'] = false; //Add to array of this category (if categorization is used) $this_category = $this->server_timings[$unique_id]['category']; if ( !empty($this_category) ){ $this->server_timings['categories'][$this_category][] = $this->server_timings[$unique_id]['time']; } return true; } } return false; }
Override
This function can not be short-circuited with an override filter. Request one?