Symfony bundle that adds the capability to change the datetime of an application

Fund package maintenance!

Installs: 1 301

Dependents: 0

Suggesters: 0

Security: 0

Stars: 7

Watchers: 2

Forks: 0

Open Issues: 9



Symfony bundle that adds the capability to change the datetime of an application


Writing tests for your application is somewhat nice and easy. But what about testing your application that heavily is based upon DateTime objects?

There is symfony/clock which already provides a ClockInterface which you can use to inject a NativeClock or MockClock into your services.

But that only works for tests. What if you want to test end-to-end? You could change the system time of you server, true, but there is an easier way using this symfony-time-machine.


composer require icanhazstring/symfony-time-machine

If the autoregister doesn't work, add the bundle into your config/bundles.php.


return [
    Icanhazstring\SymfonyTimeMachine\TimeMachineBundle => ['all' => true],

How it works

This bundle relies on the presence of ClockInterface as a service in your application. Therefor you need to have something like this in your services.yaml:

    class: Symfony\Component\Clock\NativeClock

This bundle will set this service to public: true as this is needed to change the service on request.

Now everytime you boot the TimeKernel, it will replace the ClockInterface with a MockClock with a parsed datetime string from either a request query/cookie time-machine or environment variable TIME_MACHINE.


Web usage

For web usage you have to alter your public/index.php a little.


use App\Kernel;
use Icanhazstring\SymfonyTimeMachine\TimeKernel;

require_once dirname(__DIR__).'/vendor/autoload_runtime.php';

return function (array $context) {
    $kernel = new Kernel($context['APP_ENV'], (bool) $context['APP_DEBUG']);
    (new TimeKernel($kernel))->fromContext($context)->boot();

    return $kerneL;

Console usage

For console usage alter the bin/console.

return function (array $context) {
    $kernel = new Kernel($context['APP_ENV'], (bool) $context['APP_DEBUG']);
    (new TimeKernel($kernel))->fromContext($context)->boot();

    return new Application($kernel);

Register additional TimeMachineHandler

Sometimes you need to alter some other services in your application along with the time-machine. For this you can implement services implementing the TimeMachineHandler interface.

These will be called right after the ClockInterface was changed in the container. The TimeKernel will use the HandlerRegistry to call TimeMachineHandler::handle() on all available services.

For example, you could add the time-machine query parameter to all openapi paths in your application, as shown here using api-platform:

final class PathModifier implements OpenApiPathModifier, TimeMachineHandler
    public function __construct(private readonly OpenApiFactory $openApiFactory)

    public function handles(string $path, PathItem $pathItem): bool
        return true;

    public function modify(PathItem $pathItem): PathItem
        /** @var array<string, null|Operation> $operations */
        $operations = [
            'get' => $pathItem->getGet(),
            'post' => $pathItem->getPost(),

        foreach ($operations as $method => $operation) {
            if ($operation === null) {

            $queryParameters = $operation->getParameters();
            $queryParameters[] = new Parameter(
                name: 'time-machine',
                in: 'query',
                description: 'Sets the applications datetime to a specific value.',
                required: false,
                schema: ['type' => 'string', 'default' => 'now']

            $wither = 'with'.ucfirst($method);
            /** @var PathItem $pathItem */
            $pathItem = $pathItem->{$wither}($operation->withParameters($queryParameters));

        return $pathItem;

    public function handle(): void