https://github.com/rotexsoft/callable-execution-timer
A simple PHP library for tracking the total amount of time a callable (e.g. function / method) takes to execute and return result(s) (if any).
https://github.com/rotexsoft/callable-execution-timer
benchmark benchmarking callable debug measurement performance php php-benchmark php-callable php-callback php-debug php-executor php-functions php-measurement php-performance php-profiler php-profiling php-timer profiler profiling
Last synced: about 2 months ago
JSON representation
A simple PHP library for tracking the total amount of time a callable (e.g. function / method) takes to execute and return result(s) (if any).
- Host: GitHub
- URL: https://github.com/rotexsoft/callable-execution-timer
- Owner: rotexsoft
- License: bsd-3-clause
- Created: 2021-05-14T00:14:00.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2026-01-23T04:57:11.000Z (2 months ago)
- Last Synced: 2026-01-23T10:36:10.443Z (2 months ago)
- Topics: benchmark, benchmarking, callable, debug, measurement, performance, php, php-benchmark, php-callable, php-callback, php-debug, php-executor, php-functions, php-measurement, php-performance, php-profiler, php-profiling, php-timer, profiler, profiling
- Language: PHP
- Homepage:
- Size: 38.1 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Callable Execution Timer
[](https://github.com/rotexsoft/callable-execution-timer/actions/workflows/php.yml)
[](https://github.com/rotexsoft/callable-execution-timer/releases/latest)
[](https://github.com/rotexsoft/callable-execution-timer/blob/master/LICENSE)
[](https://coveralls.io/github/rotexsoft/callable-execution-timer?branch=main)
A simple PHP library for tracking the total amount of time a
[callable](https://www.php.net/manual/en/language.types.callable.php) (e.g.
function / method) takes to execute (it can also return the result of executing
the callable, if desired).
If you want to do some simple execution time profiling in your application, without using some full blown tool like debugbar or xdebug, then this is the package for you.
## Installation
**Via composer:** (Requires PHP 7.4+ or PHP 8.0+).
composer require rotexsoft/callable-execution-timer
## Branching
These are the branches in this repository:
- **main:** contains code for the latest major version of this package
- **1.x:** contains code for the **1.x** version of this package
- **2.x:** contains code for the **1.x** version of this package
## Introduction
A simple PHP library for tracking the total amount of time a callable (e.g.
function / method) takes to execute and return result(s) (if any).
> For the rest of this documentation the term **callable** will mostly be referring to functions / methods
This library also provides information associated with each execution / invocation of the callable such as:
* the arguments passed to the callable (array)
* the total time it took to execute the callable in seconds (int / float)
* the value returned from calling the callable (mixed)
* the absolute path to the file in which the callable was called (string)
* the exact line number in the file in which the callable was called (integer)
## Executing callables
### Executing built-in php functions
Let's call php's built-in [strtolower](https://www.php.net/manual/en/function.strtolower.php) & [strtoupper](https://www.php.net/manual/en/function.strtoupper.php) functions:
```php
NOTE: The first argument passed to **CallableExecutionTimer::callFunc(...)** is a name (conforming to PHP's method naming convention) you want to name the callable you are about to execute. This name will be used to label the information related to the execution of the callable as will be shown later on in this documentation.
> NOTE: The second argument passed to **CallableExecutionTimer::callFunc(...)** is the callable you are trying to execute.
> NOTE: The third argument passed to **CallableExecutionTimer::callFunc(...)** is an array containing all the arguments to be passed to the callable you are trying to execute. You can omit this argument if the callable to be executed does not accept any arguments.
### Executing user defined functions
```php
strtolowerCallback('BOO') . PHP_EOL; // triggers __call & outputs 'boo'
// same as $callableObj1->__call('strtolowerCallback', ['BOO'])
echo $callableObj1(['BOO']) . PHP_EOL; // triggers __invoke & outputs 'boo'
// same as $callableObj1->__invoke(['BOO'])
```
> **WARNING:** Executing a callable that has one or more parameters that should be passed by reference should be done using **\FunctionExecutionTimer\CallableExecutionTimer::callFunc(...)** or executing the function by using the **__invoke(array $args)** mechanism on the instance of **\FunctionExecutionTimer\CallableExecutionTimer** the callable is bound to.
> It won't work by trying to invoke the callable on an instance of **\FunctionExecutionTimer\CallableExecutionTimer**
using the method call syntax that triggers **__call()** under the hood.
For example, you can execute the lambda function below that accepts an argument by reference via the following two ways:
```php
funcWithRefArg($numRef) . PHP_EOL; // Will throw a PHP Warning.
// $numRef will not be passed by
// ref because of the way
// __call(string $methodName, array $args)
// works, meaning that $num will still
// have a value of -1 after the call.
```
## Retrieving execution statistics
There are two ways to retrieve information associated with each execution of callables performed via this library:
1. You can call the **getLatestBenchmark()** method on an instance of **\FunctionExecutionTimer\CallableExecutionTimer** which you just used to execute a callable to get information about the most recent callable execution via that object. This method returns an array with the following keys (in bold, not including the colon):
* **function** : A string. The name (conforming to PHP's method naming convention) you labeled the callable you executed
* **args** : An array. Contains the arguments you passed to the callable you executed, if any, otherwise it would be an empty array.
* **start_time** : A float or an Integer. The timestamp in nanoseconds when the execution of the callable started.
* **end_time** : A float or an Integer. The timestamp in nanoseconds when the execution of the callable ended.
* **total_execution_time_in_seconds** : A float or an Integer. The total number of seconds it took to execute the callable.
* **return_value** : The value returned from the callable that was executed, if any, else NULL.
* **file_called_from** : A string. The absolute path to the file from which the callable was executed.
* **line_called_from** : An Integer. The exact line number in the file from which the callable was executed.
Below is an example:
```php
strtolower('BOO') . PHP_EOL;
var_export($funcObj->getLatestBenchmark());
```
The code above will generate output like the one below:
```
array (
'function' => 'strtolower',
'args' =>
array (
0 => 'BOO',
),
'start_time' => 81023870126000,
'end_time' => 81023870134000,
'total_execution_time_in_seconds' => 8.0E-6,
'return_value' => 'boo',
'file_called_from' => 'C:\\Code\\callable-execution-timer\\tester.php',
'line_called_from' => 105,
)
```
2. You can call **\FunctionExecutionTimer\CallableExecutionTimer::getBenchmarks()** to get information about the all callable executions performed via
* all calls to **\FunctionExecutionTimer\CallableExecutionTimer::callFunc(...)**
* and all callable executions via various instances of **\FunctionExecutionTimer\CallableExecutionTimer**
This method returns an array of arrays. Each sub-array has the structure of the array returned by the **getLatestBenchmark()** method described above. Below is some sample code:
```php
strtolowerMethod('BOO') . PHP_EOL;
echo $funcObj->strtolowerMethod('ABA') . PHP_EOL;
echo CallableExecutionTimer::callFunc(
'funcInline',
function($arg) { return "Hello $arg !"; },
['Jane']
) . PHP_EOL;
var_export(CallableExecutionTimer::getBenchmarks());
```
The code above will generate output like the one below:
```
array (
0 =>
array (
'function' => 'strtolowerMethod',
'args' =>
array (
0 => 'BOO',
),
'start_time' => 87248086831300,
'end_time' => 87248086840600,
'total_execution_time_in_seconds' => 9.3E-6,
'return_value' => 'boo',
'file_called_from' => 'C:\\Code\\callable-execution-timer\\tester.php',
'line_called_from' => 106,
),
1 =>
array (
'function' => 'strtolowerMethod',
'args' =>
array (
0 => 'ABA',
),
'start_time' => 87248086997700,
'end_time' => 87248087001600,
'total_execution_time_in_seconds' => 3.9E-6,
'return_value' => 'aba',
'file_called_from' => 'C:\\Code\\callable-execution-timer\\tester.php',
'line_called_from' => 108,
),
2 =>
array (
'function' => 'funcInline',
'args' =>
array (
0 => 'Jane',
),
'start_time' => 87248087019400,
'end_time' => 87248087024100,
'total_execution_time_in_seconds' => 4.7E-6,
'return_value' => 'Hello Jane !',
'file_called_from' => 'C:\\Code\\callable-execution-timer\\tester.php',
'line_called_from' => 110,
),
)
```
IT IS RECOMMENDED THAT YOU CALL **\FunctionExecutionTimer\CallableExecutionTimer::clearBenchmarks()** BEFORE YOU START EXECUTING THE CALLABLES THAT YOU WANT TO GET EXECUTION INFORMATION FOR. THIS WILL CLEAR ALL PREVIOUS EXECUTION INFO FROM PRIOR CALLABLE EXECUTIONS.