Feature Dates

📅 Дата и время (Dates)

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

CloudCastle\Support\Dates — хелперы даты и времени поверх DateTimeImmutable: fail-safe разбор, PSR-20-совместимое «сейчас», человекочитаемые интервалы с грамматически точными русскими счётными формами, границы периодов и предикаты. Лёгкая альтернатива Carbon: без макросов, локалей-переводов и мутабельности — и в 19 раз быстрее в diffHuman (см. Сравнение).

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

• parse($value, $timezone) — разбор строки с исключением InvalidDateException вместо тихого false; fromFormat($format, $value) — строгий разбор по формату; fromTimestamp($timestamp) — из Unix-времени с микросекундами.
• useClock(?ClockInterface $clock) — подмена источника времени (PSR-20): заморозка «сейчас» в тестах без глобальных моков; совместимо с cloudcastle/clock.
• now($timezone) — текущий момент из подменённых или системных часов.
• diffHuman($moment, $other, $language) — «5 минут назад», «через 21 час», «только что»: русские счётные формы согласуются словарной грамматикой cloudcastle/inflector («3 дня», «5 месяцев», «2 недели»), английские — правилами плюрализации. Никаких таблиц переводов и ext-intl.
• Предикаты isWeekend / isToday / isFuture / isPast.
• Границы startOfDay / endOfDay / startOfMonth / endOfMonth; diffInDays($a, $b) — знаковая календарная разница.

use CloudCastle\Support\Dates;
use CloudCastle\Inflector\Language;

// fail-safe разбор: исключение вместо false
$moment = Dates::parse('2026-01-15 10:30:00', 'Europe/Moscow');
Dates::parse('мусор');                       // InvalidDateException

// PSR-20: заморозка времени в тестах
Dates::useClock(new FrozenClock('2026-07-16 12:00:00'));
Dates::now();                                // всегда 2026-07-16 12:00:00

// интервалы с русской грамматикой
Dates::diffHuman($fiveMinutesAgo);           // '5 минут назад'
Dates::diffHuman($inTwentyOneHour);          // 'через 21 час'
Dates::diffHuman($threeDaysAgo);             // '3 дня назад' — не «3 дней»!
Dates::diffHuman($past, null, Language::English); // '5 minutes ago'

// границы и предикаты
Dates::startOfMonth($moment);                // 2026-01-01 00:00:00
Dates::isWeekend(Dates::parse('2026-07-18')); // true (суббота)
Dates::diffInDays($earlier, $later);         // 15 (знаковое)

Отличия от аналогов

Аспект	Dates	nesbot/carbon	nette/utils
Русская грамматика интервалов	✅ словарная	⚠️ переводы	❌
PSR-20 подмена «сейчас»	✅	⚠️ свой механизм	❌
Иммутабельность	✅ всегда	⚠️ Carbon мутабелен	⚠️
Разбор: fail-safe исключение	✅	✅	⚠️
Скорость diffHuman	~263K ops/s	~14K ops/s	—

Безопасность

• Fail-safe разбор: мусор на входе — типизированное исключение с сохранённой причиной, а не false, ползущее по коду.
• Тестируемое время: PSR-20 подмена убирает недетерминизм «сейчас» из критичной логики (сроки платежей, окна идемпотентности).
• Вывод diffHuman строится только из словарных форм и чисел — ввод не эхо-копируется.

См. также

• 🔢 Числа (Num)
• 🧮 Объекты (Obj)
• Сравнение производительности