"There is never enough time." ~ Max Walker

The php-timecop PHP extension makes it possible to manipulate time as experienced by the PHP runtime.

It provides "time travel" and "time freezing" capabilities.

This can be very useful when testing code that has time-sensitive functionality.

This project offers examples demonstrating how PHP TimeCop works.

It can be seen in action at https://php-timecop.glitch.me/

To play around with it, remix this project on Glitch.

1. Install php-timecop on a PHP server of your choice.
2. Clone this repository to the same server.
3. Visit the index.php in a web browser.
4. Study the provided examples and their output.
5. ...
6. Profit!

PHP TimeCop offers four functions to manipulate time.

For the static class method a regular function is also available (execept for return as that is a reserved word in PHP):

• TimeCop::freeze($new_time) / timecop_freeze($new_time)
• timecop_return()
• TimeCop::scale($scaling_factor) / timecop_scale($scaling_factor)
• TimeCop::travel($new_time) / timecop_travel($new_time)

Used to statically mock the concept of "now".

As the PHP runtime executes, time() will not change unless subsequent calls to freeze/return/scale/travel are made.

Return the system to a normal state. Effectively "turn off" php-timecop

Make time move at an accelerated pace. With this function, long time spans can be emulated in a shorter time.

Computes an offset between the currently think time() and the time passed in. It uses this offset to simulate the passage of time.

The result of these examples can be seen below.

<?php
$new_time = isset($_GET['time'])?strtotime($_GET['time']):0;
var_dump(date('Y-m-d H:i:s')); // todays date
Timecop::freeze($new_time);
var_dump(date('Y-m-d H:i:s'));

<?php
$new_time = isset($_GET['time'])?strtotime($_GET['time']):0;
Timecop::freeze($new_time);
sleep(1);
var_dump(date('Y-m-d H:i:s'));
timecop_return(); // "turn off" php-timecop
sleep(1);
var_dump(date('Y-m-d H:i:s'));

<?php
$new_time = isset($_GET['time'])?strtotime($_GET['time']):0;
Timecop::freeze(new DateTime('@' . $new_time));
var_dump((new DateTime())->format('Y-m-d H:i:s'));
Timecop::scale(86400); // time passes at one day per second
sleep(1);
var_dump((new DateTime())->format('Y-m-d H:i:s'));
sleep(1);
var_dump((new DateTime())->format('Y-m-d H:i:s'));

<?php
$new_time = isset($_GET['time'])?strtotime($_GET['time']):0;
Timecop::freeze($new_time);
var_dump(date('Y-m-d H:i:s'));
sleep(1);
var_dump(date('Y-m-d H:i:s'));
Timecop::travel($new_time);
sleep(1);
var_dump(date('Y-m-d H:i:s'));

Below is the output of the examples mentioned above.

string '2018-05-24 16:41:29' (length=19)
string '2008-07-31 00:00:00' (length=19)

string '2008-07-31 00:00:00' (length=19)
string '2018-05-24 16:41:31' (length=19)

string '2008-07-31 00:00:00' (length=19)
string '2008-08-01 00:00:11' (length=19)
string '2008-08-02 00:00:37' (length=19)

string '2008-07-31 00:00:00' (length=19)
string '2008-07-31 00:00:00' (length=19)
string '2008-08-01 00:00:12' (length=19)