Time as a Dependency: Advanced Patterns with the Symfony Clock

With Symfony 7.3 (released May 2025) and PHP 8.4, the symfony/clock component is no longer just a utility — it is the backbone of deterministic application architecture.

This article explores non-trivial, production-grade patterns for the Clock component, moving beyond simple “now” calls to integrating with JWT authentication, Task Scheduling and Precision Telemetry.

The Stack & Prerequisites

We assume a project running PHP 8.4+ and Symfony 7.3.

Required Packages

Run the following to install the specific versions used in this guide:

# Core Clock and Scheduler components
composer require symfony/clock:^7.3 symfony/scheduler:^7.3 symfony/messenger:^7.3

# JWT Library (supports PSR-20 Clock)
composer require lcobucci/jwt:^5.3

# For testing
composer require --dev symfony/phpunit-bridge:^7.3

Deterministic Security Tokens

One of the most common “time leaks” occurs in security services. When generating JSON Web Tokens (JWTs), developers often let the library grab the system time. This makes verifying “expiration” logic in tests difficult.

Since symfony/clock implements PSR-20, we can inject it directly into the lcobucci/jwt configuration.

The Service: TokenGenerator

We will build a generator that creates short-lived access tokens. Note the use of PHP 8.4 Asymmetric Visibility (private set) in the DTO if you wish, though standard readonly properties work perfectly here.

namespace App\Security;

use Lcobucci\JWT\Configuration;
use Lcobucci\JWT\Signer\Hmac\Sha256;
use Lcobucci\JWT\Signer\Key\InMemory;
use Psr\Clock\ClockInterface;
use Symfony\Component\DependencyInjection\Attribute\Autowire;

final readonly class TokenGenerator
{
    private Configuration $jwtConfig;

    public function __construct(
        private ClockInterface $clock,
        #[Autowire('%env(APP_SECRET)%')]
        string $appSecret
    ) {
        // Initialize JWT Configuration with OUR Clock
        $this->jwtConfig = Configuration::forSymmetricSigner(
            new Sha256(),
            InMemory::base64Encoded($appSecret)
        );
    }

    public function generateToken(string $userId): string
    {
        $now = $this->clock->now();

        return $this->jwtConfig->builder()
            ->issuedBy('https://api.myapp.com')
            ->issuedAt($now)
            ->expiresAt($now->modify('+15 minutes')) // Short lifetime
            ->withClaim('uid', $userId)
            ->getToken($this->jwtConfig->signer(), $this->jwtConfig->signingKey())
            ->toString();
    }
}

Why this matters: By manually passing $now derived from $this->clock, we gain 100% control over the iat (Issued At) and exp (Expiration) claims.

Testing the Untestable

Testing expiration usually involves sleep(901) — waiting 15 minutes and 1 second. This destroys test suite performance.

With MockClock (available automatically in tests via ClockSensitiveTrait), we can “time travel” instantly.

namespace App\Tests\Security;

use App\Security\TokenGenerator;
use Lcobucci\JWT\Encoding\JoseEncoder;
use Lcobucci\JWT\Token\Parser;
use Lcobucci\JWT\Validator\Validator;
use Lcobucci\JWT\Validation\Constraint\LooseValidAt;
use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;
use Symfony\Component\Clock\Test\ClockSensitiveTrait;

class TokenGeneratorTest extends KernelTestCase
{
    use ClockSensitiveTrait;

    public function testTokenExpiresAfterFifteenMinutes(): void
    {
        self::bootKernel();

        // 1. Freeze time at a known point
        $startTime = '2025-11-18 12:00:00';
        $clock = static::mockTime($startTime);

        $generator = static::getContainer()->get(TokenGenerator::class);
        $tokenString = $generator->generateToken('user_123');

        // 2. Verify token is valid NOW
        $this->assertTokenValidity($tokenString, true, "Token should be valid immediately");

        // 3. Time travel: Jump 16 minutes into the future
        $clock->sleep(16 * 60);

        // 4. Verify token is EXPIRED
        $this->assertTokenValidity($tokenString, false, "Token should be expired after 16 mins");
    }

    private function assertTokenValidity(string $tokenString, bool $expectValid, string $message): void
    {
        $parser = new Parser(new JoseEncoder());
        $token = $parser->parse($tokenString);

        $validator = new Validator();
        // We verify against the CURRENT clock time (which we shifted)
        $constraint = new LooseValidAt(static::getContainer()->get('clock'));

        $this->assertSame($expectValid, $validator->validate($token, $constraint), $message);
    }
}

Run php bin/phpunit. The test will complete in milliseconds, despite simulating a 16-minute delay.

Dynamic & Conditional Scheduling

The symfony/scheduler component usually relies on static attributes like #[AsPeriodicTask(‘1 hour’)]. However, real-world business logic is often more complex: Run this report only on business days between 9 AM and 5 PM.

We can inject the ClockInterface into a Schedule Provider to create dynamic schedules.

namespace App\Scheduler;

use App\Message\GenerateBusinessReport;
use Psr\Clock\ClockInterface;
use Symfony\Component\Scheduler\Attribute\AsSchedule;
use Symfony\Component\Scheduler\RecurringMessage;
use Symfony\Component\Scheduler\Schedule;
use Symfony\Component\Scheduler\ScheduleProviderInterface;

#[AsSchedule('business_reports')]
final readonly class BusinessHoursProvider implements ScheduleProviderInterface
{
    public function __construct(
        private ClockInterface $clock
    ) {}

    public function getSchedule(): Schedule
    {
        $schedule = new Schedule();
        $now = $this->clock->now();

        // Logic: Only schedule the task if it's a weekday (Mon-Fri)
        // AND within business hours (9-17).

        $isWeekday = $now->format('N') < 6;
        $isBusinessHour = $now->format('G') >= 9 && $now->format('G') < 17;

        if ($isWeekday && $isBusinessHour) {
            $schedule->add(
                RecurringMessage::every('1 hour', new GenerateBusinessReport())
            );
        }

        return $schedule;
    }
}

While Scheduler supports crontab syntax, using the Clock allows for complex holiday logic or maintenance windows defined in PHP, which is easier to unit test than a crontab string.

Testing the Scheduler

Because we injected ClockInterface, we can test that the schedule is empty on weekends without changing the system date.

public function testNoReportsOnSunday(): void
{
    // Set clock to a Sunday
    $clock = new MockClock('2025-11-23 10:00:00'); 
    $provider = new BusinessHoursProvider($clock);

    $schedule = $provider->getSchedule();
    $this->assertEmpty($schedule->getRecurringMessages());
}

Precision Performance Metrics

NativeClock is great for calendar time, but for measuring execution duration (metrics/telemetry), you should use MonotonicClock. It is immune to system time adjustments (e.g., NTP updates or leap seconds) and uses high-resolution nanoseconds.

We will create a Messenger Middleware that logs the precise execution time of every async message.

namespace App\Messenger\Middleware;

use Psr\Log\LoggerInterface;
use Symfony\Component\Clock\MonotonicClock;
use Symfony\Component\Messenger\Envelope;
use Symfony\Component\Messenger\Middleware\MiddlewareInterface;
use Symfony\Component\Messenger\Middleware\StackInterface;

final class PrecisionMetricsMiddleware implements MiddlewareInterface
{
    private MonotonicClock $stopwatch;

    public function __construct(
        private LoggerInterface $logger
    ) {
        $this->stopwatch = new MonotonicClock();
    }

    public function handle(Envelope $envelope, StackInterface $stack): Envelope
    {
        // 1. Snapshot start time (nanosecond precision)
        $start = $this->stopwatch->now();

        try {
            $result = $stack->next()->handle($envelope, $stack);
        } finally {
            // 2. Calculate precise duration
            // monotonic clocks are ideal for "diff" operations
            $duration = $this->stopwatch->now()->diff($start);

            // Convert to float milliseconds
            $ms = ($duration->s * 1000) + ($duration->f * 1000);

            $this->logger->info('Message Handled', [
                'message' => get_class($envelope->getMessage()),
                'duration_ms' => number_format($ms, 4)
            ]);
        }

        return $result;
    }
}

Configuration (config/packages/messenger.yaml)

framework:
    messenger:
        buses:
            default:
                middleware:
                    - App\Messenger\Middleware\PrecisionMetricsMiddleware

Summary of Best Practices

1. Always inject Psr\Clock\ClockInterface (or Symfony\…*ClockInterface), **never new DateTime()*.
2. Use ClockSensitiveTrait and mockTime(). Avoid sleep().
3. Configure default_timezone in php.ini, but treat ClockInterface as returning UTC by default for backend logic.
4. Use MonotonicClock for intervals/stopwatches, NativeClock for calendar dates.

Conclusion

The transition to symfony/clock in Symfony 7.3 represents more than a syntax update; it is a fundamental shift in how we treat temporal coupling. By promoting Time from a global, unpredictable side-effect (via new DateTime()) to an explicit, injectable dependency, we regain absolute control over our application’s behavior.

We have moved beyond the era of flaky tests that fail only on leap years or CI pipelines that hang on arbitrary sleep() calls. As demonstrated, the implementations are practical and high-impact:

1. Security becomes verifiable through deterministic JWT signing.
2. Scheduling becomes strictly logical, allowing us to test “Monday morning” logic on a Friday afternoon.
3. Observability becomes precise with MonotonicClock, decoupling performance metrics from system clock drift.

In modern PHP 8.4 architecture, Time is data. Treat it with the same discipline you apply to your database connections and API clients. When you own the clock, you own the reliability of your software.

I’d love to hear your thoughts in comments!

Stay tuned — and let’s keep the conversation going.