lordfireen/checkpoint

Time checkpointing library for PHP

v1.0.0 2025-11-24 11:48 UTC

Requires

• php: ^8.2
• psr/clock: ^1.0

Requires (Dev)

• phpunit/phpunit: ^11.5

BSD-3-Clause

• time
• checkpoint

README

A little class that could help you debug by creating checkpoints, with any data, that measure time between them, and also to output them in any format you want.

Installation

You can add this library as a local, per-project dependency to your project using Composer:

I recommend adding it only as a development-time dependency.

composer require --dev lordfireen/checkpoint

But you can also install it globally.

composer require lordfireen/checkpoint

Creating a checkpoint

The only way to create a Checkpoint is to call Checkpoint::create method, which create new Checkpoint, output it's and then return:

\LF\Checkpoint\Checkpoint::create('Checkpoint name', ['some', 'data'], 'as', 'anything', 'as', 'many', 'you', 'want');

Checkpoints are immutable and contain:

• Name of the checkpoint
• Arguments passed to the checkpoint
• Time when the checkpoint was called
• Difference between the previous checkpoint and the current one
• Index of the checkpoint in the list of checkpoints
• Previous checkpoint
• Next checkpoint

Each could be accessed by:

$checkpoint = \LF\Checkpoint\Checkpoint::create('Checkpoint name', ['data']);
$checkpoint->name; // "Checkpoint name"
$checkpoint->arguments; // ["data"]
$checkpoint->time; // DateTimeImmutable object
$checkpoint->diff; // DateInterval object
$checkpoint->index; // 1
$checkpoint->previous(); // Previous Checkpoint object if exists
$checkpoint->next(); // Next Checkpoint object if exists 

There are also methods to get all checkpoints and the last checkpoint:

$last = \LF\Checkpoint\Checkpoint::getLast(); // Last Checkpoint object if exists
$checkpoints = \LF\Checkpoint\Checkpoint::getCheckpoints(); // Array of Checkpoint objects in the order they were created

Checkpoints are Stringable

You can use the Checkpoint object as a string, and it will return a string representation of the checkpoint.

(string) \LF\Checkpoint\Checkpoint::create('Check', ['some', 'data'], 'as', 'anything'); // "Check"(1): [["some","data"],"as","anything"] (0 seconds)
(string) \LF\Checkpoint\Checkpoint::create('It\'s ok'); // Checkpoint "It's ok"(2): [] (0.000006 seconds)

But you could change the format of the string representation of the checkpoint using the Checkpoint::setToStringConversion() method:

\LF\Checkpoint\Checkpoint::setToStringConversion(function (\LF\Checkpoint\Checkpoint $checkpoint) {
    return sprintf('Point: ' . $checkpoint->name);
};
echo \LF\Checkpoint\Checkpoint::create('First'); // Point: First
echo \LF\Checkpoint\Checkpoint::create('Second'); // Point: Second
\LF\Checkpoint\Checkpoint::setToStringConversion(null); // Restore default behavior

WARNING: The default behavior use json_encode() method to convert the arguments to string. This could cause that parameters will be not visible in string, but you could you json_last_error_msg to get information about what is wrong.

Outputting checkpoints

By default, checkpoints are outputted to the standard output using var_dump method. You can change this behavior by using the Checkpoint::setOutput() method. Checkpoints are outputted when the Checkpoint::create() method is called.

\LF\Checkpoint\Checkpoint::setOutput(function (\LF\Checkpoint\Checkpoint $checkpoint) {
    echo (string) $checkpoint;
});
\LF\Checkpoint\Checkpoint::create('Checkpoint name'); // echo Checkpoint "Checkpoint name"(1): [["some","data"],"as","anything"] (0 seconds)