2.1.1. Recording the time

You only need to tell timelog where to start keeping track of the time (usually on the main code level), when to finish and where to take the time in between by adding three kinds of timelog calls to your code where you want to check on the execution times:

timelog::begin() and timelog::end() will show up in the timelog as indented blocks of time recordings, including the entire recording overall. For each section the total time that section has taken will be shown.

timelog::log() shows up in the timelog as single time recording.

Note: These calls are very fast even if time recording is enabled, so adding a timelog recording call causes almost no distortion of the actual application code's execution time. The more time-consuming task of generating the plain text and/or HTML reports is actually only done once in the very last timelog::end() call on the main level and the time that consumes is reported separately and does not distort the recorded times either.

2.1.2. Enabling and disabling time recording

In any place in the code you can call timelog::enable() or timelog::disable() as needed, possibly depending on debug modes and other application conditions.

The effect will be that timelog recording is either enabled or disabled until the respective other call is made or until the next timelog::end().

In particular, the application may choose to disable timelog recording even before the first timelog::begin() and that will disable recording completely (unless switched back on again).

2.1.3. Example

This is an example of an extremely simple piece of code using timelog without any extra configuration:

As a result, this report will be dumped to the PHP error log:

+ demo()
| 0.020793s (25.730%) first delay
| 0.000007s (0.009%) some other work
| 0.000003s (0.004%)
|
|+ important section
|| 0.024823s (30.717%) inner delay
|| 0.000013s (0.016%) 
|= 0.024836s (30.733%) (total)
|
| 0.035162s (43.511%) second delay
| 0.000011s (0.014%) done.
= 0.080812s (100.000%) (total)
2020-05-26 05:21:02 timelog generation took extra 0.000075s (0.093%) dumpmode='log'

2.2.1. Configure where the timelog will go

By default, timelog dumps its log to the PHP error log, but there are actually multiple options available, which can all be combined as needed:

Note: This call can be made at any time before the final timelog::end() which produces the timelogs.

In detail:

• log (default): Dump the plain text timelog to the PHP error log.

• stdout: Print the plain text timelog to stdout so it will be displayed when the PHP script is run from the command line or dumped to the page as plain text if run as a web script.

• page: Display the HTML timelog on the current page.

• file="filename" or file+="filename": Save or append the HTML timelog to the indicated file.

Additional options which affect only HTML timelogs:

• fold<0.1 or fold<5%: Automatically fold (collapse) any inner section in the HTML timelog if its time is <0.1s or if it makes up less than 5% of the total running time.

When the file+="filename" option is being used, timelogs will accumulate in that file. That is why there is also a call to indicate that this timelog run should actually flush the old content of the file before adding this current timelog:

Notes:

• This call can be made at any time before the final timelog::end() which produces the timelogs.

• This call should be made if this PHP run actually produces a new main page (for instance in something like pageheaders.php) so a new timelog will be started, while timelogs for the Ajax requests coming from the loaded page can just accumulate below.

2.2.2. Enable user control of timelog

While it can be sufficient to just set up timelog configuration in the PHP source code, timelog also offers the option of letting the user / developer control timelog from the URL field of the browser.

For this it is enough to simply add the following call to the application after the application calls session_start() but before the application calls the final timelog::end() (and also before the application potentially closes the session for write access if it does):

That is all that is required to offer the following features to the user / developer:

• Activate and deactivate timelog and set a timelog session ID:

  • ?timelog: activate timelog within this session and set $_SESSION['timelog']['ID'] = ''

  • ?timelog=myID: activate timelog and set $_SESSION['timelog']['ID'] = 'myID'

  • ?timelog=0 or ?timelog=off: deactivate timelog within this session

• Set the reference time for timelog coloring:

  • ?timelogref=0.2: Logs with total time >= 0.2s are shown in red, shorter ones shift towards green.

Of course these parameters can be combined, too: ?timelog=myID&timelogref=0.2

Note: The timelog setting is preserved in the PHP session until logout and the parameters only need to be added when this setting is to be changed.

2.2.3. Full-featured example of timelog use

This is an example of how an application could be using timelog with all its features, assuming that all pages and all Ajax requests run this same script:

In this example the user / developer will normally not have any timelog generated until they activate it by appending parameters like these:

http://localhost/myapplication/somepage?timelog=myname&timelogref=0.5

Which will make the HTML timelog available at a location like this:

http://localhost/myapplication/develop/timelog/timelog_myname.html

After any page load and after any Ajax request that timelog can be reloaded to update it in a second browser window.

And finally the user / developer may simply log out of their session or deactivate timelog again like this:

http://localhost/myapplication/somepage?timelog=off

Notes:

• By indicating different timelog IDs when enabling timelog, different users can each have their own, separate timelogs apart from the other users.

• The timelog directory can and should of course be password-secured to protect any internal information which could otherwise become available to unauthorized users through timelogs.