Feature Offset clock

⏩ Смещение времени — OffsetClock

← Возможности · Главная · Сравнение

Декоратор: время внутренних часов ± фиксированный сдвиг. «Завтра» и «вчера» без перевода системного времени.

Принцип работы

Оборачивает любые часы пакета (или ваши PSR-20-совместимые с расширенным контрактом) и прибавляет смещение к каждому моменту:

use CloudCastle\Clock\OffsetClock;
use CloudCastle\Clock\SystemClock;

$tomorrow = OffsetClock::aheadBy(SystemClock::utc(), 86_400.0);
$yesterday = OffsetClock::behindBy(SystemClock::utc(), new DateInterval('P1D'));
$custom = new OffsetClock(SystemClock::utc(), -3.5);       // на 3.5 секунды в прошлое

$tomorrow->now(); // текущий момент + сутки

Смещение принимает секунды с дробной частью (точность — микросекунда, округление до ближайшей) или DateInterval, включая инвертированные.

withTimezone() сохраняет связь с теми же внутренними часами: если внутри управляемый MockClock, его дальнейшие сдвиги видны и новому декоратору.

Плюсы

• Проверка «поведения системы завтра» без изменения окружения.
• Комбинируется с любыми часами: смещённый Mock, смещённый Monotonic и т.д.
• timestamp()/microtime() считаются арифметикой, без создания объектов дат.

Минусы

• Смещение фиксированное: для «ускоренного времени» нужен ScaledClock.

✅ Рекомендуется

• Тестировать письма/уведомления, которые должны уйти «за сутки до события».
• Стенды, живущие «в будущем» относительно продакшна.

❌ Антипаттерны

• Эмулировать смещением таймзону — для этого есть withTimezone().

Схема фичи

flowchart LR
    IN[Любые часы] --> OC["OffsetClock(±сдвиг)"]
    OC -->|"now() = inner.now() ± offset"| OUT[Момент со сдвигом]
    OC -.->|"withTimezone() — та же связь с inner"| OC2["OffsetClock (другая зона)"]
    IN -.->|сдвиги видны| OC2

Loading

Жизненный цикл вызова

sequenceDiagram
    participant U as Код
    participant O as OffsetClock(+86400с)
    participant I as SystemClock

    U->>O: now()
    O->>I: now()
    I-->>O: текущий момент
    O->>O: modify(+86 400 000 000 мкс)
    O-->>U: «завтра в это время»

Loading

Сравнение с аналогами

Возможность	Clock	symfony/clock	lcobucci/clock	beste/clock	nesbot/carbon	ergebnis/clock	🏆 Победитель
Часы со смещением	✅	❌	❌	❌	❌	❌	Clock
Смещение интервалом и секундами	✅	—	—	—	—	—	Clock
Микросекундная точность смещения	✅	—	—	—	—	—	Clock