Feature Date point

📍 DatePoint — момент от часов приложения

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

DateTimeImmutable, который берёт «сейчас» из глобальных часов приложения и бросает типизированные исключения вместо false с warning-ом. Функциональный аналог Symfony\Component\Clock\DatePoint.

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

use CloudCastle\Clock\Clock;
use CloudCastle\Clock\ClockHolder;
use CloudCastle\Clock\DatePoint;
use CloudCastle\Clock\MockClock;

ClockHolder::set(MockClock::from('2026-03-01 10:00:00', 'UTC'));

new DatePoint();                       // 2026-03-01 10:00:00 — из часов приложения
new DatePoint('+1 hour');              // 11:00 — модификатор от «сейчас»
new DatePoint('now', 'Europe/Moscow'); // 13:00 московского

Clock::now('+30 minutes');             // шорткат фасада → DatePoint

DatePoint::createFromFormat('Y-m-d', '2026-05-05'); // исключение вместо false
DatePoint::fromInterface($anyDate);                  // снимок любого DateTimeInterface
(new DatePoint())->modify('+2 days');                // исключение на мусоре/NUL

Схема фичи

flowchart LR
    H[ClockHolder] -->|«сейчас»| DP[DatePoint]
    MOD["'+1 hour' / строка"] --> DP
    DP -->|валидация: NUL, date_parse| OK[Момент]
    DP -->|мусор| EX[InvalidClockValueException]

Loading

Жизненный цикл

sequenceDiagram
    participant T as Тест
    participant H as ClockHolder
    participant D as DatePoint

    T->>H: set(MockClock 10:00)
    T->>D: new DatePoint('+1 hour')
    D->>H: now()
    H-->>D: 10:00 (виртуальные)
    D-->>T: 11:00 — детерминированно

Loading

Плюсы

• Даты в бизнес-коде становятся тестируемыми без внедрения часов в каждый вызов.
• Ошибки разбора — типизированные исключения пакета, не false+warning.
• Микросекунды сохраняются при всех преобразованиях.

Минусы

• Читает глобальный слот: в новом коде с DI предпочтительнее явные часы + now().

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

• Миграция легаси с new DateTimeImmutable() на управляемое время заменой класса.

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

• new DatePoint() в цикле горячего пути — каждый вызов читает слот; вынесите момент в переменную.

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

Возможность	Clock	symfony/clock	lcobucci/clock	beste/clock	nesbot/carbon	ergebnis/clock	🏆 Победитель
Момент от часов приложения	✅	✅	❌	❌	⚠️	❌	Clock + symfony/clock
Исключения вместо false	✅	✅	—	—	⚠️	—	Clock + symfony/clock
Отклонение NUL-байтов	✅	❌	—	—	❌	—	Clock