FastForward\Clock

FastForward\Clock provides PSR-20 compliant clock implementations and seamless integration with Fast Forward Container.

This package offers two clock implementations: SystemClock for production time and FrozenClock for deterministic testing.

✨ Features

• 🕒 PSR-20 Compliant - Full support for the PSR-20 Clock interface
• 🧪 Testing Made Easy - FrozenClock lets you freeze time for reliable tests
• 🌐 Timezone Support - Configure timezones in production and tests
• 🔌 Container Integration - Automatic service registration via ClockServiceProvider
• 🎯 Beginner Friendly - Simple API designed for developers new to PSR patterns

📦 Installation

composer require fast-forward/clock

Requirements:

• PHP 8.3 or higher
• fast-forward/container 1.6 or higher
• psr/clock 1.0

🛠️ Usage

Basic: Get the current time

The simplest way to get the current time is using SystemClock:

<?phpdeclare(strict_types=1);
useFastForward\Clock\SystemClock;
$clock = newSystemClock();
echo$clock->now()->format(DATE_ATOM) . PHP_EOL;

With a specific timezone

<?phpdeclare(strict_types=1);
useFastForward\Clock\SystemClock;
$clock = newSystemClock('America/Sao_Paulo');
echo$clock->now()->format('Y-m-d H:i:s P') . PHP_EOL;

Using with Fast Forward Container

For larger applications, use the service provider to register the clock in your container:

<?phpdeclare(strict_types=1);
useFastForward\Clock\ServiceProvider\ClockServiceProvider;
usePsr\Clock\ClockInterface;
usefunctionFastForward\Container\container;
$container = container(newClockServiceProvider());
$clock = $container->get(ClockInterface::class);
echo$clock->now()->format(DATE_ATOM) . PHP_EOL;

Freezing time for tests

Use FrozenClock to create deterministic tests:

<?phpdeclare(strict_types=1);
useFastForward\Clock\FrozenClock;
$clock = newFrozenClock('2026-04-07 10:00:00');
echo$clock->now()->format(DATE_ATOM) . PHP_EOL;
// Output: 2026-04-07T10:00:00+00:00

FrozenClock accepts multiple input formats:

<?phpdeclare(strict_types=1);
useFastForward\Clock\FrozenClock;
// From a DateTimeImmutable$clock1 = newFrozenClock(newDateTimeImmutable('2026-04-07 10:00:00'));
// From a string$clock2 = newFrozenClock('next Monday');
// From a timestamp$clock3 = newFrozenClock(1775640000);
// From another ClockInterface$clock4 = newFrozenClock(newSystemClock('America/New_York'));

Using FrozenClock with Fast Forward Container in tests

<?phpdeclare(strict_types=1);
useFastForward\Clock\ServiceProvider\ClockServiceProvider;
useFastForward\Clock\FrozenClock;
useFastForward\Container\ServiceProvider\ArrayServiceProvider;
usePsr\Clock\ClockInterface;
usePsr\Container\ContainerInterface;
usefunctionFastForward\Container\container;
$frozenClock = newFrozenClock('2026-04-07 10:00:00');
$testProvider = newArrayServiceProvider([
FrozenClock::class => staticfn(ContainerInterface$container): FrozenClock => $frozenClock,
ClockInterface::class => staticfn(ContainerInterface$container): FrozenClock => $container->get(FrozenClock::class),
]);
$container = container($testProvider, newClockServiceProvider());
$clock = $container->get(ClockInterface::class);
echo$clock->now()->format(DATE_ATOM) . PHP_EOL;

🧰 API Summary

Class	Description
FastForward\Clock\SystemClock	PSR-20 clock that returns current system time with optional timezone
FastForward\Clock\FrozenClock	PSR-20 clock that returns a fixed time (ideal for testing)
FastForward\Clock\ServiceProvider\ClockServiceProvider	Registers clock services in Fast Forward Container

SystemClock Constructor

publicfunction __construct(DateTimeZone|string|null$timezone = null)

Parameter	Type	Description
$timezone	DateTimeZone|string|null	Timezone for the clock (defaults to system default)

FrozenClock Constructor

publicfunction __construct(DateTimeInterface|ClockInterface|string|int|float$clock = 'now')

Parameter	Type	Description
$clock	DateTimeInterface|ClockInterface|string|int|float	The time to freeze. Accepts DateTimeImmutable, string (relative or absolute), timestamp, or another ClockInterface

🔌 Integration

This package integrates seamlessly with:

• Fast Forward Container - Use ClockServiceProvider for automatic registration
• PSR-20 - Both SystemClock and FrozenClock implement Psr\Clock\ClockInterface
• Any PSR-11 Container - Both clocks can be instantiated directly without the service provider

📁 Directory Structure

src/
├── SystemClock.php # Production clock implementation
├── FrozenClock.php # Testing clock implementation
├── ServiceProvider/
│ ├── ClockServiceProvider.php # Container service provider
│ └── Factory/
│ └── DateTimeZoneFactory.php # Timezone factory
tests/
├── SystemClockTest.php
├── FrozenClockTest.php
└── ServiceProvider/
└── ClockServiceProviderTest.php
examples/
├── 01-system-clock.php
├── 02-system-clock-with-timezone.php
├── 03-frozen-clock.php
├── 04-frozen-clock-inputs.php
├── 05-frozen-clock-container.php
└── 06-psr20-clock-interface.php
docs/
└── ... (Sphinx documentation)

⚙️ Advanced / Customization

Custom timezone via configuration

If you use Fast Forward Config, you can configure the default timezone:

<?phpuseFastForward\Config\Config;
useFastForward\Clock\ServiceProvider\ClockServiceProvider;
usefunctionFastForward\Container\container;
$config = newConfig([
DateTimeZone::class => 'America/Sao_Paulo',
]);
$container = container($config, newClockServiceProvider());

Creating a custom clock

Both clocks are final readonly classes, but you can wrap them:

<?phpdeclare(strict_types=1);
useFastForward\Clock\FrozenClock;
usePsr\Clock\ClockInterface;
finalclass StubbedClock implements ClockInterface
{
publicfunction__construct(privateClockInterface$clock)
{
}
publicfunctionnow(): \DateTimeImmutable
{
return$this->clock->now();
}
publicstaticfunctioncreate(string$time): self
{
returnnewself(newFrozenClock($time));
}
}

❓ FAQ

Q: What's the difference between SystemClock and FrozenClock?
A:SystemClock returns the current time and is suitable for production. FrozenClock returns a fixed time and is ideal for testing.

Q: Which interface should I use in my application?
A: Use Psr\Clock\ClockInterface for maximum portability. Both implementations satisfy this interface.

Q: How do I freeze time in tests?
A: Use FrozenClock directly, or register it via ArrayServiceProvider before ClockServiceProvider.

Q: Can I use this without Fast Forward Container?
A: Yes! Simply instantiate SystemClock or FrozenClock directly in your code.

Q: Does this work with other PSR-11 containers?
A: Yes. The clocks are standalone classes that don't require any container.

Q: How do I set a specific timezone?
A: Pass a timezone string or DateTimeZone instance to the SystemClock constructor.

🛡 License

This project is licensed under the MIT License.

🤝 Contributing

Issues, documentation improvements, and pull requests are welcome!

🔗 Links

• Repository
• Issue Tracker
• Examples
• Sphinx Documentation
• Fast Forward Container
• PSR-20 Clock